org.geotoolkit.xml
Class XLink

Object
  XLink

All Implemented Interfaces:

Serializable

@ThreadSafe
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):

	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 ObjectLinker.resolve(Class, XLink) method. Users can override that method in order to fetch an instance in some catalog for the given xlink values.

Since:

3.18 (derived from 2.5)

Version:

3.18

Author:

Guilhem Legal (Geomatys), Martin Desruisseaux (Geomatys)

See Also:

XML Linking Language, OGC schema, Serialized Form

Module:

utility/geotk-xml-base (download)

View source code for this class

Nested Class Summary

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

XLink()
Creates a new link.

XLink(XLink link)
Creates a new link as a copy of the given link.

Method Summary

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.

Note: This serves a role similar to idref. The idref attribute allows an XML element to refer to another XML element that has a corresponding id attribute.

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

TODO:

We have a hole, since the title attribute could be modifiable...

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