Class XLink

java.lang.Object
org.apache.sis.xml.XLink
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
Anchor

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 RRRRRR
href O R   
role OOO O 
arcrole O  O  
title OOOOO 
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
Version:
0.3
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    Communicates the desired timing of traversal from the starting resource to the ending resource.
    static enum 
    Communicates the desired presentation of the ending resource on traversal from the starting resource.
    static enum 
    The type of a xlink.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    Communicates the desired timing of traversal from the starting resource to the ending resource.
    private URI
    A URI reference for some description of the arc role.
    private String
    The starting resource.
    private int
    The cached hash code value, computed only if this XLink is unmodifiable.
    private URI
    A URN to an external resources, or to another part of a XML document, or an identifier.
    private String
    Identifies the target of a from or to attribute.
    private URI
    A URI reference for some description of the arc role.
    private static final long
    For cross-version compatibility.
    private XLink.Show
    Communicates the desired presentation of the ending resource on traversal from the starting resource.
    private org.opengis.util.InternationalString
    Just as with resources, this is simply a human-readable string with a short description for the arc.
    private String
    The ending resource.
    private XLink.Type
    The type of link.
  • Constructor Summary

    Constructors
    Constructor
    Description
    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
    private static void
    append(StringBuilder buffer, String label, Object value)
    Appends the given attribute in the given buffer if the attribute value is not null.
    private void
    canWrite(int field, String name, Object value)
    Checks if the given attribute can be set.
    boolean
    equals(Object object)
    Compares this XLink with the given object for equality.
    private int
    Returns a mask of fields for which a non-null value has been defined.
    void
    Marks this xlink as unmodifiable.
    Returns the desired timing of traversal from the starting resource to the ending resource.
    Returns a URI reference for some description of the arc role.
    Returns the starting resource.
    Returns a URN to an external resources, or to another part of a XML document, or an identifier.
    Returns an identification of the target of a from or to attribute.
    Returns a URI reference for some description of the arc role.
    Returns the desired presentation of the ending resource on traversal from the starting resource.
    org.opengis.util.InternationalString
    Returns a human-readable string with a short description for the arc.
    Returns the ending resource.
    Returns the type of link.
    private int
    Computes the hash code now.
    int
    Returns a hash code value for this XLink.
    void
    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
    Sets the starting resource.
    void
    setHRef(URI href)
    Sets the URN to a resources.
    void
    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
    Sets the desired presentation of the ending resource on traversal from the starting resource.
    void
    setTitle(org.opengis.util.InternationalString title)
    Sets a human-readable string with a short description for the arc.
    void
    Sets the ending resource.
    void
    Sets the type of link.
    Returns a string representation of this object.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • type

      private XLink.Type type
      The type of link. If null, then the type will be inferred by getType().
      See Also:
    • href

      private URI href
      A URN to an external resources, or to another part of a XML document, or an identifier.
      See Also:
    • role

      private URI role
      A URI reference for some description of the arc role.
      See Also:
    • arcrole

      private URI arcrole
      A URI reference for some description of the arc role.
      See Also:
    • title

      private org.opengis.util.InternationalString title
      Just as with resources, this is simply a human-readable string with a short description for the arc.
      See Also:
    • show

      private XLink.Show show
      Communicates the desired presentation of the ending resource on traversal from the starting resource.
      See Also:
    • actuate

      private XLink.Actuate actuate
      Communicates the desired timing of traversal from the starting resource to the ending resource.
      See Also:
    • label

      private String label
      Identifies the target of a from or to attribute.
      See Also:
    • from

      private String from
      The starting resource. The value must correspond to the same value for some label attribute.
      See Also:
    • to

      private String to
      The ending resource. The value must correspond to the same value for some label attribute.
      See Also:
    • hashCode

      private int hashCode
      The cached hash code value, computed only if this XLink is unmodifiable. Otherwise, this field is left to zero. This field is computed when the freeze() method has been invoked.
  • 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

    • fieldMask

      private int fieldMask()
      Returns a mask of fields for which a non-null value has been defined. The bit values are defined in the fieldMask() javadoc.
    • 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.
    • canWrite

      private void canWrite(int field, String name, Object value) throws IllegalStateException
      Checks if the given attribute can be set.
      Parameters:
      field - the attribute code, as documented in fieldMask().
      Throws:
      UnsupportedOperationException - if this xlink is unmodifiable.
      IllegalStateException - if the given field cannot be set for this kind of xlink.
    • getHRef

      public URI getHRef()
      Returns a URN to an external resources, or to another 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 org.opengis.util.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(org.opengis.util.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
    • hash

      private int hash()
      Computes the hash code now. This method is guaranteed to return a value different than zero, in order to allow us to use 0 as a sentinel value for modifiable xlink.
    • 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:
      Overrides:
      toString in class Object
    • append

      private static void append(StringBuilder buffer, String label, Object value)
      Appends the given attribute in the given buffer if the attribute value is not null. If the given value is an attribute, the XML name will be used rather than the Java field name.