Package org.apache.sis.internal.jaxb
Class Context
java.lang.Object
org.apache.sis.xml.MarshalContext
org.apache.sis.internal.jaxb.Context
Thread-local status of a marshalling or unmarshalling processes.
All non-static methods in this class except
finish()
are implementation of public API.
All static methods are internal API. Those methods expect a Context
instance as their first argument.
They can be though as if they were normal member methods, except that they accept null
instance
if no (un)marshalling is in progress.- Since:
- 0.3
- Version:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) final int
Various boolean attributes determines by the above static constants.private static final int
Bit where to store whetherfinish()
shall invokeSemaphores.clear(Semaphores.NULL_COLLECTION)
.private final ValueConverter
The value converter currently in use, ornull
forValueConverter.DEFAULT
.private static final ThreadLocal
<Context> The thread-local context.The identifiers used for marshalled objects.The objects associated to XML identifiers.static final int
Whether we are (un)marshalling legacy metadata as defined in 2003 model (ISO 19139:2007).static final int
Whether the unmarshalling process should accept any metadata or GML version if the user did not specified an explicit version.The locale to use for marshalling, or an empty queue if no locale were explicitly specified.private final Filter
The object to inform about warnings, ornull
if none.static final Logger
The logger to use for warnings that are specific to XML.static final int
The bit flag telling if a marshalling process is under progress.private final Context
The context which was previously used.private final ReferenceResolver
The reference resolver currently in use, ornull
forReferenceResolver.DEFAULT
.The base URL of ISO 19115-3 (or other standards) schemas.static final int
The bit flag for enabling substitution of country codes by character strings.static final int
The bit flag for enabling substitution of filenames by character strings.static final int
The bit flag for enabling substitution of language codes by character strings.static final int
The bit flag for enabling substitution of mime types by character strings.private final TimeZone
The timezone, ornull
if unspecified.private final Version
The GML version to be marshalled or unmarshalled, ornull
if unspecified.private PropertyType
<?, ?> The<gml:*PropertyType>
which is wrapping the<gml:*Type>
object to (un)marshal, ornull
if this information is not provided. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic ValueConverter
Returns the value converter in use for the current marshalling or unmarshalling process.static Context
current()
Returns the context of the XML (un)marshalling currently progressing in the current thread, ornull
if none.final void
finish()
Invoked in afinally
block when a unmarshalling process is finished.final Locale
Returns the locale to use for marshalling, ornull
if no locale were explicitly specified.static Object
getObjectForID
(Context context, String id) Returns the object for the givengml:id
, ornull
if none.static String
getObjectID
(Context context, Object object) If agml:id
value has already been used for the given object in the current XML document, returns that identifier.final TimeZone
Returns the timezone to use for marshalling, ornull
if none were explicitly specified.final Version
getVersion
(String prefix) Returns the schema version of the XML document being (un)marshalled.static PropertyType
<?, ?> getWrapper
(Context context) Returns the<gml:*PropertyType>
which is wrapping the<gml:*Type>
object to (un)marshal, ornull
if this information is not provided.static boolean
Returnstrue
if the given flag is set.static boolean
isGMLVersion
(Context context, Version version) Returnstrue
if the GML version is equal or newer than the specified version.static void
pull()
Restores the locale which was used prior the call topush(Locale)
.static void
Sets the locale to the given value.static ReferenceResolver
Returns the reference resolver in use for the current marshalling or unmarshalling process.static StringBuilder
Returns the base URL of ISO 19115-3 (or other standards) schemas.static boolean
setObjectForID
(Context context, Object object, String id) Returnstrue
if the given identifier is available, orfalse
if it is used by another object.static void
setWrapper
(Context context, PropertyType<?, ?> wrapper) Invoked byPropertyType
implementations for declaring the<gml:*PropertyType>
instance which is wrapping the<gml:*Type>
object to (un)marshal.static void
warningOccured
(Context context, Class<?> classe, String method, Class<? extends IndexedResourceBundle> resources, short key, Object... arguments) static void
warningOccured
(Context context, Class<?> classe, String method, Exception cause, boolean isWarning) Convenience method for sending a warning for the given exception.static void
warningOccured
(Context context, Level level, Class<?> classe, String method, Throwable exception, Class<? extends IndexedResourceBundle> resources, short key, Object... arguments) Sends a warning to the warning listener if there is one, or logs the warning otherwise.
-
Field Details
-
MARSHALLING
public static final int MARSHALLINGThe bit flag telling if a marshalling process is under progress. This flag is unset for unmarshalling processes.- See Also:
-
SUBSTITUTE_LANGUAGE
public static final int SUBSTITUTE_LANGUAGEThe bit flag for enabling substitution of language codes by character strings.- See Also:
-
SUBSTITUTE_COUNTRY
public static final int SUBSTITUTE_COUNTRYThe bit flag for enabling substitution of country codes by character strings.- See Also:
-
SUBSTITUTE_FILENAME
public static final int SUBSTITUTE_FILENAMEThe bit flag for enabling substitution of filenames by character strings.- See Also:
-
SUBSTITUTE_MIMETYPE
public static final int SUBSTITUTE_MIMETYPEThe bit flag for enabling substitution of mime types by character strings.- See Also:
-
LEGACY_METADATA
public static final int LEGACY_METADATAWhether we are (un)marshalling legacy metadata as defined in 2003 model (ISO 19139:2007). If this flag is not set, then we assume latest metadata as defined in 2014 model (ISO 19115-3).- See Also:
-
LENIENT_UNMARSHAL
public static final int LENIENT_UNMARSHALWhether the unmarshalling process should accept any metadata or GML version if the user did not specified an explicit version. Accepting any version may have surprising results since namespace substitutions may be performed on the fly.- See Also:
-
CLEAR_SEMAPHORE
private static final int CLEAR_SEMAPHOREBit where to store whetherfinish()
shall invokeSemaphores.clear(Semaphores.NULL_COLLECTION)
.- See Also:
-
CURRENT
The thread-local context. Elements are created in the constructor, and removed in afinally
block by thefinish()
method. ThisThreadLocal
shall not contain any value when no (un)marshalling is in progress. -
LOGGER
The logger to use for warnings that are specific to XML. -
bitMasks
final int bitMasksVarious boolean attributes determines by the above static constants. -
locales
The locale to use for marshalling, or an empty queue if no locale were explicitly specified. -
timezone
The timezone, ornull
if unspecified. In the latter case, an implementation-default (typically UTC) timezone is used. -
schemas
The base URL of ISO 19115-3 (or other standards) schemas. The valid values are documented in theXML.SCHEMAS
property. -
versionGML
The GML version to be marshalled or unmarshalled, ornull
if unspecified. If null, than the latest version is assumed. -
resolver
The reference resolver currently in use, ornull
forReferenceResolver.DEFAULT
. -
converter
The value converter currently in use, ornull
forValueConverter.DEFAULT
. -
identifiers
The objects associated to XML identifiers. At marhalling time, this is used for avoiding duplicated identifiers in the same XML document. At unmarshalling time, this is used for getting a previous object from its identifier.- Since:
- 0.7
-
identifiedObjects
The identifiers used for marshalled objects. This is the converse ofidentifiers
, used in order to identify whichgml:id
to use for the given object. Thegml:id
to use are not necessarily the same than the one associated toIdentifierSpace.ID
if the identifier was already used for another object in the same XML document.- Since:
- 0.7
-
logFilter
The object to inform about warnings, ornull
if none. -
wrapper
The<gml:*PropertyType>
which is wrapping the<gml:*Type>
object to (un)marshal, ornull
if this information is not provided. SeegetWrapper(Context)
for an example.For performance reasons, this
wrapper
information is not provided by default. SeesetWrapper(Context, PropertyType)
for more information.- See Also:
-
previous
The context which was previously used. This form a linked list allowing to push properties and pull back the context to its previous state once finished.
-
-
Constructor Details
-
Context
public Context(int bitMasks, Locale locale, TimeZone timezone, Map<String, String> schemas, Version versionGML, Version versionMetadata, ReferenceResolver resolver, ValueConverter converter, Filter logFilter) Invoked when a marshalling or unmarshalling process is about to begin. Must be followed by a call tofinish()
in afinally
block.- Parameters:
bitMasks
- a combination ofMARSHALLING
,SUBSTITUTE_*
or other bit masks.locale
- the locale, ornull
if unspecified.timezone
- the timezone, ornull
if unspecified.schemas
- the schemas root URL, ornull
if none.versionGML
- the GML version, ornull
.versionMetadata
- the metadata version, ornull
.resolver
- the resolver in use.converter
- the converter in use.logFilter
- the object to inform about warnings.
-
-
Method Details
-
getLocale
Returns the locale to use for marshalling, ornull
if no locale were explicitly specified.- Specified by:
getLocale
in classMarshalContext
- Returns:
- the locale in the context of current (un)marshalling process.
- See Also:
-
getTimeZone
Returns the timezone to use for marshalling, ornull
if none were explicitly specified.- Specified by:
getTimeZone
in classMarshalContext
- Returns:
- the timezone in the context of current (un)marshalling process.
-
getVersion
Returns the schema version of the XML document being (un)marshalled. See the super-class javadoc for the list of prefix that we shall support.- Specified by:
getVersion
in classMarshalContext
- Parameters:
prefix
- one of the above-cited prefix.- Returns:
- the version in the context of current (un)marshalling process.
-
current
Returns the context of the XML (un)marshalling currently progressing in the current thread, ornull
if none.- Returns:
- the current (un)marshalling context, or
null
if none.
-
push
Sets the locale to the given value. The old locales are remembered and will be restored by the next call topull()
. This method can be invoked when marshalling object that need to marshal their children in a different locale, like below:- Parameters:
locale
- the locale to set, ornull
.
-
pull
public static void pull()Restores the locale which was used prior the call topush(Locale)
. It is not necessary to invoke this method in afinally
block. -
isFlagSet
Returnstrue
if the given flag is set.- Parameters:
context
- the current context, ornull
if none.flag
- one ofMARSHALLING
,SUBSTITUTE_LANGUAGE
,SUBSTITUTE_COUNTRY
or other bit masks.- Returns:
true
if the given flag is set.
-
isGMLVersion
Returnstrue
if the GML version is equal or newer than the specified version. If no GML version was specified, then this method returnstrue
, i.e. newest version is assumed.API note: This method is static for the convenience of performing the check for null context.- Parameters:
context
- the current context, ornull
if none.version
- the version to compare to.- Returns:
true
if the GML version is equal or newer than the specified version.- See Also:
-
schema
Returns the base URL of ISO 19115-3 (or other standards) schemas. The valid values are documented in theXML.SCHEMAS
property. If the returned value is not empty, then this method guarantees it ends with'/'
.API note: This method is static for the convenience of performing the check for null context.- Parameters:
context
- the current context, ornull
if none.key
- one of the value documented in the "Map key" column ofXML.SCHEMAS
.defaultSchema
- the value to return if no schema is found for the given key.- Returns:
- the base URL of the schema, or an empty buffer if none were specified.
-
getWrapper
Returns the<gml:*PropertyType>
which is wrapping the<gml:*Type>
object to (un)marshal, ornull
if this information is not provided. The<gml:*PropertyType>
element can contains information not found in<gml:*Type>
objects like XLink or UUID.Example: before unmarshalling theFor performance reasons, this<gml:OperationParameter>
(upper caseO
) element below,wrapper
will be set to the temporary object representing<gml:operationParameter>
. That adapter provides important information for the SIS<gml:OperationParameter>
constructor.wrapper
information is not provided by default. SeesetWrapper(Context, PropertyType)
for more information.- Parameters:
context
- the current context, ornull
if none.- Returns:
- the
<gml:*PropertyType>
which is wrapping the<gml:*Type>
object to (un)marshal, ornull
if unknown.
-
setWrapper
Invoked byPropertyType
implementations for declaring the<gml:*PropertyType>
instance which is wrapping the<gml:*Type>
object to (un)marshal.For performance reasons, this
wrapper
information is not provided by default. To get this information, thePropertyType
implementation needs to define thebeforeUnmarshal(…)
method. For an implementation example, seeCC_OperationParameter
.- Parameters:
context
- the current context, ornull
if none.wrapper
- the<gml:*PropertyType>
which is wrapping the<gml:*Type>
object to (un)marshal, ornull
if unknown.
-
getObjectID
If agml:id
value has already been used for the given object in the current XML document, returns that identifier. Otherwise returnsnull
.- Parameters:
context
- the current context, ornull
if none.object
- the object for which to get thegml:id
.- Returns:
- the identifier used in the current XML document for the given object, or
null
if none. - Since:
- 0.7
-
getObjectForID
Returns the object for the givengml:id
, ornull
if none. This association is valid only for the current XML document.- Parameters:
context
- the current context, ornull
if none.id
- the identifier for which to get the object.- Returns:
- the object associated to the given identifier, or
null
if none. - Since:
- 0.7
-
setObjectForID
Returnstrue
if the given identifier is available, orfalse
if it is used by another object. If this method returnstrue
, then the given identifier is associated to the given object for future invocation ofContext
methods. If this method returnsfalse
, then the caller is responsible for computing another identifier candidate.- Parameters:
context
- the current context, ornull
if none.object
- the object for which to assign thegml:id
.id
- the identifier to assign to the given object.- Returns:
true
if the given identifier can be used.- Since:
- 0.7
-
resolver
Returns the reference resolver in use for the current marshalling or unmarshalling process. If no resolver were explicitly set, then this method returnsReferenceResolver.DEFAULT
.API note: This method is static for the convenience of performing the check for null context.- Parameters:
context
- the current context, ornull
if none.- Returns:
- the current reference resolver (never null).
-
converter
Returns the value converter in use for the current marshalling or unmarshalling process. If no converter were explicitly set, then this method returnsValueConverter.DEFAULT
.API note: This method is static for the convenience of performing the check for null context.- Parameters:
context
- the current context, ornull
if none.- Returns:
- the current value converter (never null).
-
warningOccured
public static void warningOccured(Context context, Level level, Class<?> classe, String method, Throwable exception, Class<? extends IndexedResourceBundle> resources, short key, Object... arguments) Sends a warning to the warning listener if there is one, or logs the warning otherwise. In the latter case, this method logs to the given logger.If the given
resources
isnull
, then this method will build the log message from theexception
.- Parameters:
context
- the current context, ornull
if none.level
- the logging level.classe
- the class to declare as the warning source.method
- the name of the method to declare as the warning source.exception
- the exception thrown, ornull
if none.resources
- eitherErrors.class
,Messages.class
ornull
for the exception message.key
- the resource keys as one of the constants defined in theKeys
inner class.arguments
- the arguments to be given toMessageFormat
for formatting the log message.- Since:
- 0.5
-
warningOccured
public static void warningOccured(Context context, Class<?> classe, String method, Class<? extends IndexedResourceBundle> resources, short key, Object... arguments) Convenience method for sending a warning for the given message from theErrors
orMessages
resources. The message will be logged atLevel.WARNING
.- Parameters:
context
- the current context, ornull
if none.classe
- the class to declare as the warning source.method
- the name of the method to declare as the warning source.resources
- eitherErrors.class
orMessages.class
.key
- the resource keys as one of the constants defined in theKeys
inner class.arguments
- the arguments to be given toMessageFormat
for formatting the log message.- Since:
- 0.5
-
warningOccured
public static void warningOccured(Context context, Class<?> classe, String method, Exception cause, boolean isWarning) Convenience method for sending a warning for the given exception. The logger will be"org.apache.sis.xml"
.- Parameters:
context
- the current context, ornull
if none.classe
- the class to declare as the warning source.method
- the name of the method to declare as the warning source.cause
- the exception which occurred.isWarning
-true
forLevel.WARNING
, orfalse
forLevel.FINE
.
-
finish
public final void finish()Invoked in afinally
block when a unmarshalling process is finished.
-