Package org.apache.sis.xml

## Class XLink

- Object
- - XLink

- All Implemented Interfaces:
    `Serializable`

      public class XLink
      extends Object
      implements Serializable

  The XML attributes defined by OGC in the xlink schema. The allowed combinations of any one attribute depend on the value of the special `type` attribute. Following is a summary of the element types (columns) on which the global attributes (rows) are allowed, with an indication of whether a value is required (R) or optional (O) (Source: W3C):

  XLink attribute usage patterns
  | `simple` | `extended` | `locator` | `arc` | `resource` | `title`
  --- | --- | --- | --- | --- | --- | ---
  `type` | R | R | R | R | R | R
  `href` | O |  | R |  |  |
  `role` | O | O | O |  | O |
  `arcrole` | O |  |  | O |  |
  `title` | O | O | O | O | O |
  `show` | O |  |  | O |  |
  `actuate` | O |  |  | O |  |
  `label` |  |  | O |  | O |
  `from` |  |  |  | O |  |
  `to` |  |  |  | O |  |

  When `xlink` attributes are found at unmarshalling time instead of an object definition, those attributes are given to the `ReferenceResolver​.resolve(MarshalContext, Class, XLink)` method. Users can override that method in order to fetch an instance in some catalog for the given `xlink` values.
  Since:
    0.3
  See Also:
    XML Linking Language, OGC schema, Serialized Form

  Defined in the `sis-metadata` module

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `XLink.Actuate` | Communicates the desired timing of traversal from the starting resource to the ending resource.
    `static class` | `XLink.Show` | Communicates the desired presentation of the ending resource on traversal from the starting resource.
    `static class` | `XLink.Type` | The type of a `xlink`.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XLink()` | Creates a new link.
    `XLink​(XLink link)` | Creates a new link as a copy of the given link.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object object)` | Compares this `XLink` with the given object for equality.
    `void` | `freeze()` | Marks this `xlink` as unmodifiable.
    `XLink.Actuate` | `getActuate()` | Returns the desired timing of traversal from the starting resource to the ending resource.
    `URI` | `getArcRole()` | Returns a URI reference for some description of the arc role.
    `String` | `getFrom()` | Returns the starting resource.
    `URI` | `getHRef()` | Returns a URN to an external resources, or to an other part of a XML document, or an identifier.
    `String` | `getLabel()` | Returns an identification of the target of a `from` or `to` attribute.
    `URI` | `getRole()` | Returns a URI reference for some description of the arc role.
    `XLink.Show` | `getShow()` | Returns the desired presentation of the ending resource on traversal from the starting resource.
    `InternationalString` | `getTitle()` | Returns a human-readable string with a short description for the arc.
    `String` | `getTo()` | Returns the ending resource.
    `XLink.Type` | `getType()` | Returns the type of link.
    `int` | `hashCode()` | Returns a hash code value for this XLink.
    `void` | `setActuate​(XLink.Actuate actuate)` | Sets the desired timing of traversal from the starting resource to the ending resource.
    `void` | `setArcRole​(URI arcrole)` | Sets a URI reference for some description of the arc role.
    `void` | `setFrom​(String from)` | Sets the starting resource.
    `void` | `setHRef​(URI href)` | Sets the URN to a resources.
    `void` | `setLabel​(String label)` | Sets an identification of the target of a `from` or `to` attribute.
    `void` | `setRole​(URI role)` | Sets the URI reference for some description of the arc role.
    `void` | `setShow​(XLink.Show show)` | Sets the desired presentation of the ending resource on traversal from the starting resource.
    `void` | `setTitle​(InternationalString title)` | Sets a human-readable string with a short description for the arc.
    `void` | `setTo​(String to)` | Sets the ending resource.
    `void` | `setType​(XLink.Type type)` | Sets the type of link.
    `String` | `toString()` | Returns a string representation of this object.

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### XLink

          public XLink()

      Creates a new link. The initial value of all attributes is `null`.

    - #### XLink

          public XLink​(XLink link)

      Creates a new link as a copy of the given link.
      Parameters:
        `link` - The link to copy, or `null` if none.

  - ### Method Detail

    - #### getType

          public XLink.Type getType()

      Returns the type of link. May have one of the following values:
      - simple: a simple link
      - extended: an extended, possibly multi-resource, link
      - locator: a pointer to an external resource
      - resource: an internal resource
      - arc: a traversal rule between resources
      - title: a descriptive title for another linking element
      The default value is `null`. If the `setType(XLink​.Type)` method has been invoked with the `AUTO` enum, then this method will infer a type from the attributes having a non-null value.
      Returns:
        the type of link, or `null`.

    - #### setType

          public void setType​(XLink.Type type)

      Sets the type of link. Any value different than `Type​.AUTO` (including `null`) will overwrite the value inferred automatically by `getType()`. A `AUTO` value will enable automatic type detection.
      Parameters:
        `type` - the new type of link, or `null` if none.

    - #### getHRef

          public URI getHRef()

      Returns a URN to an external resources, or to an other part of a XML document, or an identifier.
      Returns:
        a URN to a resources, or `null` if none.

    - #### setHRef

          public void setHRef​(URI href)
                       throws IllegalStateException

      Sets the URN to a resources.
      Parameters:
        `href` - a URN to a resources, or `null` if none.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"href"` attribute.

    - #### getRole

          public URI getRole()

      Returns a URI reference for some description of the arc role.
      Returns:
        a URI reference for some description of the arc role, or `null` if none.

    - #### setRole

          public void setRole​(URI role)
                       throws IllegalStateException

      Sets the URI reference for some description of the arc role.
      Parameters:
        `role` - a URI reference for some description of the arc role, or `null` if none.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"role"` attribute.

    - #### getArcRole

          public URI getArcRole()

      Returns a URI reference for some description of the arc role.
      Returns:
        a URI reference for some description of the arc role, or `null` if none.

    - #### setArcRole

          public void setArcRole​(URI arcrole)
                          throws IllegalStateException

      Sets a URI reference for some description of the arc role.
      Parameters:
        `arcrole` - a URI reference for some description of the arc role, or `null` if none.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"arcrole"` attribute.

    - #### getTitle

          public InternationalString getTitle()

      Returns a human-readable string with a short description for the arc.
      Returns:
        a human-readable string with a short description for the arc, or `null` if none.

    - #### setTitle

          public void setTitle​(InternationalString title)
                        throws IllegalStateException

      Sets a human-readable string with a short description for the arc.
      Parameters:
        `title` - a human-readable string with a short description for the arc, or `null` if none.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"title"` attribute.

    - #### getShow

          public XLink.Show getShow()

      Returns the desired presentation of the ending resource on traversal from the starting resource. It's value should be treated as follows:
      - new: load ending resource in a new window, frame, pane, or other presentation context
      - replace: load the resource in the same window, frame, pane, or other presentation context
      - embed: load ending resource in place of the presentation of the starting resource
      - other: behavior is unconstrained; examine other markup in the link for hints
      - none: behavior is unconstrained
      Returns:
        the desired presentation of the ending resource, or `null` if unspecified.

    - #### setShow

          public void setShow​(XLink.Show show)
                       throws IllegalStateException

      Sets the desired presentation of the ending resource on traversal from the starting resource.
      Parameters:
        `show` - the desired presentation of the ending resource, or `null` if unspecified.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"show"` attribute.

    - #### getActuate

          public XLink.Actuate getActuate()

      Returns the desired timing of traversal from the starting resource to the ending resource. It's value should be treated as follows:
      - onLoad: traverse to the ending resource immediately on loading the starting resource
      - onRequest: traverse from the starting resource to the ending resource only on a post-loading event triggered for this purpose
      - other: behavior is unconstrained; examine other markup in link for hints
      - none: behavior is unconstrained
      Returns:
        the desired timing of traversal from the starting resource to the ending resource, or `null` if unspecified.

    - #### setActuate

          public void setActuate​(XLink.Actuate actuate)
                          throws IllegalStateException

      Sets the desired timing of traversal from the starting resource to the ending resource.
      Parameters:
        `actuate` - the desired timing of traversal from the starting resource to the ending resource, or `null` if unspecified.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"actuate"` attribute.

    - #### getLabel

          public String getLabel()

      Returns an identification of the target of a `from` or `to` attribute.
      Returns:
        an identification of the target of a `from` or `to` attribute, or `null`.

    - #### setLabel

          public void setLabel​(String label)
                        throws IllegalStateException

      Sets an identification of the target of a `from` or `to` attribute.
      Parameters:
        `label` - an identification of the target of a `from` or `to` attribute, or `null`.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"label"` attribute.

    - #### getFrom

          public String getFrom()

      Returns the starting resource. The value must correspond to the same value for some `label` attribute.
      Returns:
        the starting resource, or `null`.

    - #### setFrom

          public void setFrom​(String from)
                       throws IllegalStateException

      Sets the starting resource. The value must correspond to the same value for some `label` attribute.
      Parameters:
        `from` - the starting resource, or `null`.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"from"` attribute.

    - #### getTo

          public String getTo()

      Returns the ending resource. The value must correspond to the same value for some `label` attribute.
      Returns:
        the ending resource, or `null`.

    - #### setTo

          public void setTo​(String to)
                     throws IllegalStateException

      Sets the ending resource. The value must correspond to the same value for some `label` attribute.
      Parameters:
        `to` - the ending resource, or `null`.
      Throws:
        `UnsupportedOperationException` - if this `xlink` is unmodifiable.
        `IllegalStateException` - if the link type has been explicitly set. and that type does not allow the `"to"` attribute.

    - #### freeze

          public void freeze()

      Marks this `xlink` as unmodifiable. After this method call, any call to a setter method will throw an `UnsupportedOperationException`.

      After the first call to this method, any subsequent calls have no effect.

    - #### equals

          public boolean equals​(Object object)

      Compares this `XLink` with the given object for equality.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - the object to compare with this XLink.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this XLink.
      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Returns a string representation of this object. The default implementation returns the simple class name followed by non-null attributes, as in the example below:

      >     XLink[type="locator", href="urn:ogc:def:method:EPSG::4326"]

      Overrides:
        `toString` in class `Object`