Package org.apache.sis.xml

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

Version:

0.3

See Also:

• XML Linking Language
• OGC schema
• Serialized Form

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.

Field Summary

Fields

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

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
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	fieldMask()	Returns a mask of fields for which a non-null value has been defined.
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 another 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.
org.opengis.util.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.
private int	hash()	Computes the hash code now.
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(org.opengis.util.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 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:

• Constant Field Values

type

private XLink.Type type

The type of link. If null, then the type will be inferred by getType().

See Also:

• getType()

href

private URI href

A URN to an external resources, or to another part of a XML document, or an identifier.

See Also:

• getHRef()

role

private URI role

A URI reference for some description of the arc role.

See Also:

• getRole()

arcrole

private URI arcrole

A URI reference for some description of the arc role.

See Also:

• getArcRole()

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:

• getTitle()

show

private XLink.Show show

Communicates the desired presentation of the ending resource on traversal from the starting resource.

See Also:

• getShow()

actuate

private XLink.Actuate actuate

Communicates the desired timing of traversal from the starting resource to the ending resource.

See Also:

• getActuate()

label

private String label

Identifies the target of a from or to attribute.

See Also:

• getLabel()

from

private String from

The starting resource. The value must correspond to the same value for some label attribute.

See Also:

• getFrom()

to

private String to

The ending resource. The value must correspond to the same value for some label attribute.

See Also:

• getTo()

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.