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 enum`
  `XLink​.Actuate`
  Communicates the desired timing of traversal from the starting resource to the ending resource.
  `static enum`
  `XLink​.Show`
  Communicates the desired presentation of the ending resource on traversal from the starting resource.
  `static enum`
  `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

  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 Details

  - ### 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 Details

  - ### 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`