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 Reference­Resolver to a unmarshaller.

Since:
0.3

  • Field Details

    • DEFAULT

      public static final ReferenceResolver DEFAULT
      The default resolver used at unmarshalling time when no resolver was explicitly set. For security reasons, this instance follows only the following types of xlink:href:
      • references to fragments inside the current document, or
      • references to files in the same directory or in a sub-directory of the file containing the xlink:href.
      See Also:

    • 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 resolve­External(Marshal­Context, Source). If null, relative URIs will be resolved against the URI of the document which contains the reference.
      Since:
      1.5

  • Constructor Details

    • ReferenceResolver

      protected ReferenceResolver()
      Creates a default Reference­Resolver. 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 resolve­External(Marshal­Context, Source). If the specified resolver returns null for a given xlink:href, then Reference­Resolver will try to resolve the URI itself.
      Parameters:
      external­Source­Resolver - resolver of sources, or null for letting Reference­Resolver 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:
      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 Identifier­Space.
      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 resolve­External(Marshal­Context, 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(Marshal­Context, 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 is constructed by the caller (resolve(…)) 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 with a XMLResolver, delegates to it.
      • Otherwise, the caller tries to resolve the URI itself.
      The resolved URL, if known, is available in Source​.get­System­Id(). If the given source argument wraps an URI, then this method asks to access­Control(URI) whether this Reference­Resolver can open that URI. If access­Control(…) returns DENIED, then an Access­Denied­Exception is thrown. 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

    • accessControl

      public Authorization accessControl(URI document)
      Returns whether the specified document or fragment referenced in a xlink:href can be opened. The return value control the resolve­External(Marshal­Context, Source) behavior as below:
      • GRANTED: parse the document or fragment at the given URI.
      • DENIED: throw an Access­Denied­Exception.
      • DEFAULT: behave like GRANTED if the file is in the same directory or in a subdirectory of the document containing the xlink:href, otherwise behave like DENIED.
      The default implementation returns GRANTED in a trusted environment, or DEFAULT otherwise. Security policy can be tuned more finely by overriding this method and specifying the customized Resolver instance as documented in XML​.RESOLVER.
      Parameters:
      document - the document or fragment referenced in a xlink:href.
      Returns:
      whether the given document or fragment can be opened.
      Since:
      1.7

    • 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: 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 Nil­Object.
      • If object implements Emptiable and its is­Empty() 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 Nil­Object.
      • If object implements Emptiable and its is­Empty() 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:Character­String> 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.