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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ReferenceResolver`
  `DEFAULT`
  The default and thread-safe instance.
  `protected final URIResolver`
  `externalSourceResolver`
  Provider of sources to use for unmarshalling objects referenced by links to another document.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ReferenceResolver()`
  Creates a default `ReferenceResolver`.
  ``
  `ReferenceResolver(URIResolver externalSourceResolver)`
  Creates a new resolver which will use the specified provider of sources for unmarshalling external documents.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `XLink`
  `anchor(MarshalContext context, Object value, CharSequence text)`
  Returns the `<gcx:Anchor>` to use for the given text, or `null` if none.
  `<T> boolean`
  `canSubstituteByReference(MarshalContext context, Class<T> type, T object, String id)`
  Returns `true` if the marshaller can use a `xlink:href="#id"` reference to the given object instead of writing the full XML element.
  `<T> boolean`
  `canSubstituteByReference(MarshalContext context, Class<T> type, T object, UUID uuid)`
  Returns `true` if the marshaller can use a reference to the given object instead of writing the full XML 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 object instead of writing the full XML 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.
  `protected Object`
  `resolveExternal(MarshalContext context, Source source)`
  Returns an object defined in an external document, or `null` if none.

  ### Methods inherited from class Object

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

- ## Field Details

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

  - ### externalSourceResolver

    protected final URIResolver externalSourceResolver
    Provider of sources to use for unmarshalling objects referenced by links to another document. It provides the `source` argument in `resolveExternal(MarshalContext, Source)`. If `null`, a default resolution is done.
    Since:
      1.5

- ## Constructor Details

  - ### ReferenceResolver

    protected ReferenceResolver()
    Creates a default `ReferenceResolver`. This constructor is for subclasses only.

  - ### ReferenceResolver

    public ReferenceResolver(URIResolver externalSourceResolver)
    Creates a new resolver which will use the specified provider of sources for unmarshalling external documents. The specified resolver is invoked when a `xlink:href` attribute is found, and the associated URI value has a path to an external document. The resolver provides the `source` argument which will be given to `resolveExternal(MarshalContext, Source)`. If the specified resolver returns `null` for a given `xlink:href`, then `ReferenceResolver` will try to resolve the URI itself.
    Parameters:
      `externalSourceResolver` - resolver of sources, or `null` for letting `ReferenceResolver` resolving the URIs itself.
    Since:
      1.5

- ## Method Details

  - ### 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`, `Double​.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, often as a GeoAPI interface.
      `identifiers` - an arbitrary number 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, often as 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 fetches the `xlink:href` attribute, then:
    - If `xlink:href` is null or opaque, returns `null`.
    - Otherwise, if the `xlink:href` URI is is absolute or has a path, delegates to `resolveExternal(MarshalContext, Source)`.
    - Otherwise, the URI is a fragment such as `"#foo"`. Then:
      - If an object of class `type` with an identifier attribute such as `gml:id="foo"` has previously been seen in the same XML document (i.e., "foo" is a backward reference), returns that object.
      - Otherwise, emits a warning and returns `null`. Note that it may happen if the `xlink:href` is a forward reference.
    If an object is found but is not of the class declared in `type`, or if an `Exception` was thrown during object unmarshalling, then this method emits a warning and returns `null`.
    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 a GeoAPI interface.
      `link` - the `xlink` attributes.
    Returns:
      an object of the given type for the given `xlink` attribute, or `null` if none.

  - ### resolveExternal

    protected Object resolveExternal(MarshalContext context, Source source) throws Exception
    Returns an object defined in an external document, or `null` if none. This method is invoked automatically by `resolve(MarshalContext, Class, XLink)` when the `xlink:href` attribute is absolute or contains the path to a document. The default implementation loads the file from the given source if it is not in the cache, then returns the object identified by the fragment part of the URI.

    The `source` argument should have been determined by the caller has below:

    - If an `URIResolver` has been specified at construction time, delegates to it.
    - Otherwise or if the above returned `null`, then if the source of the current document is associated to a `XMLResolver`, delegates to it.
    - Otherwise, the caller tries to resolve the URI itself.
    The resolved URL, if known, should be available in `Source​.getSystemId()`.

    #### Error handling

    The default implementation keeps a cache during the execution of an `XML​.unmarshall(…)` method (or actually, during a pooled unmarshaller method). If an exception is thrown during the document unmarshalling, this failure is also recorded in the cache. Therefore, the exception is thrown only during the first attempt to read the document and `null` is returned directly on next attempts for the same source. Exceptions thrown by this method are caught by `resolve(…)` and reported as warnings.
    Parameters:
      `context` - context (GML version, locale, etc.) of the (un)marshalling process.
      `source` - source of the document specified by the `xlink:href` attribute value.
    Returns:
      an object for the given source, or `null` if none, for example because of failure in a previous attempt.
    Throws:
      `Exception` - if an error occurred while opening or parsing the document.
    Since:
      1.5

  - ### canSubstituteByReference

    public <T> boolean canSubstituteByReference(MarshalContext context, Class<T> type, T object, String id)
    Returns `true` if the marshaller can use a `xlink:href="#id"` reference to the given object instead of writing the full XML element. This method is invoked by the marshaller when:
    - The given object has already been marshalled in the same XML document.
    - The marshalled object had a `gml:id` attribute
      - either specified explicitly by `IdentifierMap​.put(IdentifierSpace​.ID, id)`
      - or inferred automatically by the marshalled object (e.g. `AbstractIdentifiedObject`).
    Note that if this method returns `true`, then the use of `xlink:href="#id"` will have precedence over UUID and XLink alternatives.

    The default implementation unconditionally returns `true`. Subclasses can override this method if they want to filter which objects to declare by 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 a GeoAPI interface.
      `object` - the object to be marshalled.
      `id` - the `gml:id` value of the object to be marshalled.
    Returns:
      `true` if the marshaller can use the `xlink:href="#id"` attribute instead of marshalling the given object.
    Since:
      0.7

  - ### 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 object instead of writing the full XML element. This method is invoked when an object to be marshalled has a UUID identifier. Because those object may be defined externally, SIS cannot know if the object 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 a GeoAPI 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 of marshalling the given object.

  - ### 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 object instead of writing the full XML element. This method is invoked when an object to be marshalled has a `XLink` identifier. Because those object may be defined externally, SIS cannot know if the object 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 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 of marshalling the given object.

  - ### anchor

    public XLink anchor(MarshalContext context, Object value, CharSequence text)
    Returns the `<gcx:Anchor>` to use for the given text, or `null` if none. Anchors can appear in ISO 19115-3 documents where we would normally expect a character sequence. For example:

    XML representations of string
    As `<gco:CharacterString>` | As `<gcx:Anchor>`
    --- | ---
         <cit:country>
            <gco:CharacterString>France</gco:CharacterString>
        </cit:country>
         <cit:country>
            <gcx:Anchor xlink:href="SDN:C320:2:FR">France</gcx:Anchor>
        </cit: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 as `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.