Class ReferenceResolver
Object
ReferenceResolver
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
FieldsModifier and TypeFieldDescriptionstatic final ReferenceResolver
The default and thread-safe instance.protected final URIResolver
Provider of sources to use for unmarshalling objects referenced by links to another document. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Creates a defaultReferenceResolver
.ReferenceResolver
(URIResolver externalSourceResolver) Creates a new resolver which will use the specified provider of sources for unmarshalling external documents. -
Method Summary
Modifier and TypeMethodDescriptionanchor
(MarshalContext context, Object value, CharSequence text) Returns the<gcx:Anchor>
to use for the given text, ornull
if none.<T> boolean
canSubstituteByReference
(MarshalContext context, Class<T> type, T object, String id) Returnstrue
if the marshaller can use axlink: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) Returnstrue
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) Returnstrue
if the marshaller can use axlink: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 givenuuid
attribute, ornull
if none.<T> T
resolve
(MarshalContext context, Class<T> type, XLink link) Returns an object of the given type for the givenxlink
attribute, ornull
if none.protected Object
resolveExternal
(MarshalContext context, Source source) Returns an object defined in an external document, ornull
if none.
-
Field Details
-
DEFAULT
The default and thread-safe instance. This instance is used at unmarshalling time when noReferenceResolver
was explicitly set by theXML.RESOLVER
property. -
externalSourceResolver
Provider of sources to use for unmarshalling objects referenced by links to another document. It provides thesource
argument inresolveExternal(MarshalContext, Source)
. Ifnull
, a default resolution is done.- Since:
- 1.5
-
-
Constructor Details
-
ReferenceResolver
protected ReferenceResolver()Creates a defaultReferenceResolver
. This constructor is for subclasses only. -
ReferenceResolver
Creates a new resolver which will use the specified provider of sources for unmarshalling external documents. The specified resolver is invoked when axlink:href
attribute is found, and the associated URI value has a path to an external document. The resolver provides thesource
argument which will be given toresolveExternal(MarshalContext, Source)
. If the specified resolver returnsnull
for a givenxlink:href
, thenReferenceResolver
will try to resolve the URI itself.- Parameters:
externalSourceResolver
- resolver of sources, ornull
for lettingReferenceResolver
resolving the URIs itself.- Since:
- 1.5
-
-
Method Details
-
newIdentifiedObject
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
andIdentifiedObject
interfaces from this package. IdentifiedObject.getIdentifiers()
will return the given identifiers.IdentifiedObject.getIdentifierMap()
will return aMap
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 orfalse
, depending on the method return type.
- Type Parameters:
T
- the compile-time type of thetype
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 inIdentifierSpace
.- Returns:
- an object of the given type for the given identifiers, or
null
if none.
- Implements the given
-
resolve
Returns an object of the given type for the givenuuid
attribute, ornull
if none. The default implementation returnsnull
in all cases.- Type Parameters:
T
- the compile-time type of thetype
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
- theuuid
attributes.- Returns:
- an object of the given type for the given
uuid
attribute, ornull
if none.
-
resolve
Returns an object of the given type for the givenxlink
attribute, ornull
if none. The default implementation fetches thexlink:href
attribute, then:- If
xlink:href
is null or opaque, returnsnull
. - Otherwise, if the
xlink:href
URI is is absolute or has a path, delegates toresolveExternal(MarshalContext, Source)
. - Otherwise, the URI is a fragment such as
"#foo"
. Then:- If an object of class
type
with an identifier attribute such asgml: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 thexlink:href
is a forward reference.
- If an object of class
type
, or if anException
was thrown during object unmarshalling, then this method emits a warning and returnsnull
.- Type Parameters:
T
- the compile-time type of thetype
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
- thexlink
attributes.- Returns:
- an object of the given type for the given
xlink
attribute, ornull
if none.
- If
-
resolveExternal
Returns an object defined in an external document, ornull
if none. This method is invoked automatically byresolve(MarshalContext, Class, XLink)
when thexlink: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 aXMLResolver
, delegates to it. - Otherwise, the caller tries to resolve the URI itself.
Source.getSystemId()
.Error handling
The default implementation keeps a cache during the execution of anXML.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 andnull
is returned directly on next attempts for the same source. Exceptions thrown by this method are caught byresolve(…)
and reported as warnings.- Parameters:
context
- context (GML version, locale, etc.) of the (un)marshalling process.source
- source of the document specified by thexlink: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
- If an
-
canSubstituteByReference
public <T> boolean canSubstituteByReference(MarshalContext context, Class<T> type, T object, String id) Returnstrue
if the marshaller can use axlink: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
).
- either specified explicitly by
true
, then the use ofxlink: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 thetype
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
- thegml:id
value of the object to be marshalled.- Returns:
true
if the marshaller can use thexlink: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) Returnstrue
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
implementsNilObject
. - If
object
implementsEmptiable
and itsisEmpty()
method returnstrue
.
- Type Parameters:
T
- the compile-time type of thetype
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 theuuidref
attribute instead of marshalling the given object.
- If
-
canSubstituteByReference
public <T> boolean canSubstituteByReference(MarshalContext context, Class<T> type, T object, XLink link) Returnstrue
if the marshaller can use axlink:href
reference to the given object instead of writing the full XML element. This method is invoked when an object to be marshalled has aXLink
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
implementsNilObject
. - If
object
implementsEmptiable
and itsisEmpty()
method returnstrue
.
- Type Parameters:
T
- the compile-time type of thetype
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 thexlink:href
attribute instead of marshalling the given object.
- If
-
anchor
Returns the<gcx:Anchor>
to use for the given text, ornull
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>
- 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 astext
, but can also be theURI
orLocale
instance for whichtext
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.
-