org.apache.sis.xml

Class ReferenceResolver

Object

ReferenceResolver

public class ReferenceResolver
extends Object

Controls the (un)marshaller behavior regarding the xlink or uuidref attributes. At marshalling time, this class controls whether the marshaller is allowed to write a reference to an existing instance instead than writing the full object definition. At unmarshalling time, this class replaces (if possible) a reference by the full object definition.

Subclasses can override the methods defined in this class in order to search in their own catalog. See the XML.RESOLVER javadoc for an example of registering a custom ReferenceResolver to a unmarshaller.

Since:

0.3

Defined in the sis-utility module

Field Summary

Fields

Modifier and Type	Field and Description
static ReferenceResolver	DEFAULT The default and thread-safe instance.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ReferenceResolver() Creates a default ReferenceResolver.

Method Summary

Methods

Modifier and Type	Method and Description
XLink	anchor(MarshalContext context, Object value, CharSequence text) Returns the <gmx:Anchor> to use for the given text, or null if none.
<T> boolean	canSubstituteByReference(MarshalContext context, Class<T> type, T object, UUID uuid) Returns true if the marshaller can use a reference to the given metadata instead than writing the full element.
<T> boolean	canSubstituteByReference(MarshalContext context, Class<T> type, T object, XLink link) Returns true if the marshaller can use a xlink:href reference to the given metadata instead than writing the full element.
<T> T	newIdentifiedObject(MarshalContext context, Class<T> type, Identifier... identifiers) Returns an empty object of the given type having the given identifiers.
<T> T	resolve(MarshalContext context, Class<T> type, UUID uuid) Returns an object of the given type for the given uuid attribute, or null if none.
<T> T	resolve(MarshalContext context, Class<T> type, XLink link) Returns an object of the given type for the given xlink attribute, or null if none.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT

public static final ReferenceResolver DEFAULT

The default and thread-safe instance. This instance is used at unmarshalling time when no ReferenceResolver was explicitly set by the XML.RESOLVER property.

Constructor Detail

ReferenceResolver

protected ReferenceResolver()

Creates a default ReferenceResolver. This constructor is for subclasses only.

Method Detail

newIdentifiedObject

public <T> T newIdentifiedObject(MarshalContext context,
                        Class<T> type,
                        Identifier... identifiers)

Returns an empty object of the given type having the given identifiers. The object returned by the default implementation has the following properties:

• Implements the given type interface.
• Implements the NilObject and IdentifiedObject interfaces from this package.
• IdentifiedObject.getIdentifiers() will return the given identifiers.
• IdentifiedObject.getIdentifierMap() will return a Map view over the given identifiers.
• All other methods except the ones inherited from the Object class will return an empty collection, an empty array, null, NaN, 0 or false, depending on the method return type.

Type Parameters:

T - The compile-time type of the type argument.

Parameters:

context - Context (GML version, locale, etc.) of the (un)marshalling process.

type - The type of object to be unmarshalled as an interface. This is usually a GeoAPI interface.

identifiers - An arbitrary amount of identifiers. For each identifier, the authority is typically (but not necessarily) one of the constants defined in IdentifierSpace.

Returns:

An object of the given type for the given identifiers, or null if none.

resolve

public <T> T resolve(MarshalContext context,
            Class<T> type,
            UUID uuid)

Returns an object of the given type for the given uuid attribute, or null if none. The default implementation returns null in all cases.

Type Parameters:

T - The compile-time type of the type argument.

Parameters:

context - Context (GML version, locale, etc.) of the (un)marshalling process.

type - The type of object to be unmarshalled as an interface. This is usually a GeoAPI interface.

uuid - The uuid attributes.

Returns:

An object of the given type for the given uuid attribute, or null if none.

resolve

public <T> T resolve(MarshalContext context,
            Class<T> type,
            XLink link)

Returns an object of the given type for the given xlink attribute, or null if none. The default implementation returns null in all cases.

Type Parameters:

T - The compile-time type of the type argument.

Parameters:

context - Context (GML version, locale, etc.) of the (un)marshalling process.

type - The type of object to be unmarshalled, often as an interface.

link - The xlink attributes.

Returns:

An object of the given type for the given xlink attribute, or null if none.

canSubstituteByReference

public <T> boolean canSubstituteByReference(MarshalContext context,
                                   Class<T> type,
                                   T object,
                                   UUID uuid)

Returns true if the marshaller can use a reference to the given metadata instead than writing the full element. This method is invoked when a metadata to be marshalled has a UUID identifier. Because those metadata may be defined externally, SIS can not know if the metadata shall be fully marshalled or not. Such information needs to be provided by the application.

The default implementation returns true in the following cases:

• If object implements NilObject.
• If object implements Emptiable and its isEmpty() method returns true.

Subclasses can override this method if they know whether the receiver will be able to resolve the reference.

Type Parameters:

T - The compile-time type of the type argument.

Parameters:

context - Context (GML version, locale, etc.) of the (un)marshalling process.

type - The type of object to be unmarshalled, often as an interface.

object - The object to be marshalled.

uuid - The unique identifier of the object to be marshalled.

Returns:

true if the marshaller can use the uuidref attribute instead than marshalling the given metadata.

canSubstituteByReference

public <T> boolean canSubstituteByReference(MarshalContext context,
                                   Class<T> type,
                                   T object,
                                   XLink link)

Returns true if the marshaller can use a xlink:href reference to the given metadata instead than writing the full element. This method is invoked when a metadata to be marshalled has a XLink identifier. Because those metadata may be defined externally, SIS can not know if the metadata shall be fully marshalled or not. Such information needs to be provided by the application.

The default implementation returns true in the following cases:

• If object implements NilObject.
• If object implements Emptiable and its isEmpty() method returns true.

Subclasses can override this method if they know whether the receiver will be able to resolve the reference.

Type Parameters:

T - The compile-time type of the type argument.

Parameters:

context - Context (GML version, locale, etc.) of the (un)marshalling process.

type - The type of object to be marshalled as an interface. This is usually a GeoAPI interface.

object - The object to be marshalled.

link - The reference of the object to be marshalled.

Returns:

true if the marshaller can use the xlink:href attribute instead than marshalling the given metadata.

anchor

public XLink anchor(MarshalContext context,
           Object value,
           CharSequence text)

Returns the <gmx:Anchor> to use for the given text, or null if none. Anchors can appear in ISO 19139 documents where we would normally expect a character sequence. For example:

XML representations of string

As <gco:CharacterString>	As <gmx:Anchor>
<gmd:country> <gco:CharacterString>France</gco:CharacterString> </gmd:country>	<gmd:country> <gmx:Anchor xlink:href="SDN:C320:2:FR">France</gmx:Anchor> </gmd:country>

Subclasses can override this method if they can provide a mapping from some text values to anchors.

Parameters:

context - Context (GML version, locale, etc.) of the (un)marshalling process.

value - The value for which an anchor is requested. Often the same instance than text, but can also be the URI or Locale instance for which text is a string representation.

text - The textual representation of the value for which to get the anchor.

Returns:

The anchor for the given text, or null if none.