Package org.apache.sis.internal.jaxb

Class Context

java.lang.Object
org.apache.sis.xml.MarshalContext
org.apache.sis.internal.jaxb.Context
public final class Context extends MarshalContext
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 Details

    • MARSHALLING

      public static final int MARSHALLING
      The 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_LANGUAGE
      The bit flag for enabling substitution of language codes by character strings.
      See Also:

    • SUBSTITUTE_COUNTRY

      public static final int SUBSTITUTE_COUNTRY
      The bit flag for enabling substitution of country codes by character strings.
      See Also:

    • SUBSTITUTE_FILENAME

      public static final int SUBSTITUTE_FILENAME
      The bit flag for enabling substitution of filenames by character strings.
      See Also:

    • SUBSTITUTE_MIMETYPE

      public static final int SUBSTITUTE_MIMETYPE
      The bit flag for enabling substitution of mime types by character strings.
      See Also:

    • LEGACY_METADATA

      public static final int LEGACY_METADATA
      Whether 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_UNMARSHAL
      Whether 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_SEMAPHORE
      Bit where to store whether finish() shall invoke Semaphores.clear(Semaphores.NULL_COLLECTION).
      See Also:

    • CURRENT

      private static final ThreadLocal<Context> CURRENT
      The thread-local context. Elements are created in the constructor, and removed in a finally block by the finish() method. This ThreadLocal shall not contain any value when no (un)marshalling is in progress.

    • LOGGER

      public static final Logger LOGGER
      The logger to use for warnings that are specific to XML.

    • bitMasks

      final int bitMasks
      Various boolean attributes determines by the above static constants.

    • locales

      private final Deque<Locale> locales
      The locale to use for marshalling, or an empty queue if no locale were explicitly specified.

    • timezone

      private final TimeZone timezone
      The timezone, or null if unspecified. In the latter case, an implementation-default (typically UTC) timezone is used.

    • schemas

      private final Map<String,String> schemas
      The base URL of ISO 19115-3 (or other standards) schemas. The valid values are documented in the XML.SCHEMAS property.

    • versionGML

      private final Version versionGML
      The GML version to be marshalled or unmarshalled, or null if unspecified. If null, than the latest version is assumed.

    • resolver

      private final ReferenceResolver resolver
      The reference resolver currently in use, or null for ReferenceResolver.DEFAULT.

    • converter

      private final ValueConverter converter
      The value converter currently in use, or null for ValueConverter.DEFAULT.

    • identifiers

      private final Map<String,Object> 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

      private final Map<Object,String> identifiedObjects
      The identifiers used for marshalled objects. This is the converse of identifiers, used in order to identify which gml:id to use for the given object. The gml:id to use are not necessarily the same than the one associated to IdentifierSpace.ID if the identifier was already used for another object in the same XML document.
      Since:
      0.7

    • logFilter

      private final Filter logFilter
      The object to inform about warnings, or null if none.

    • wrapper

      private PropertyType<?,?> wrapper
      The <gml:*PropertyType> which is wrapping the <gml:*Type> object to (un)marshal, or null if this information is not provided. See getWrapper(Context) for an example.

      For performance reasons, this wrapper information is not provided by default. See setWrapper(Context, PropertyType) for more information.

      See Also:

    • previous

      private final Context 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 to finish() in a finally block.
      Parameters:
      bitMasks - a combination of MARSHALLING, SUBSTITUTE_* or other bit masks.
      locale - the locale, or null if unspecified.
      timezone - the timezone, or null if unspecified.
      schemas - the schemas root URL, or null if none.
      versionGML - the GML version, or null.
      versionMetadata - the metadata version, or null.
      resolver - the resolver in use.
      converter - the converter in use.
      logFilter - the object to inform about warnings.

  • Method Details

    • getLocale

      public final Locale getLocale()
      Returns the locale to use for marshalling, or null if no locale were explicitly specified.
      Specified by:
      getLocale in class MarshalContext
      Returns:
      the locale in the context of current (un)marshalling process.
      See Also:

    • getTimeZone

      public final TimeZone getTimeZone()
      Returns the timezone to use for marshalling, or null if none were explicitly specified.
      Specified by:
      getTimeZone in class MarshalContext
      Returns:
      the timezone in the context of current (un)marshalling process.

    • getVersion

      public final Version getVersion(String prefix)
      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 class MarshalContext
      Parameters:
      prefix - one of the above-cited prefix.
      Returns:
      the version in the context of current (un)marshalling process.

    • current

      public static Context current()
      Returns the context of the XML (un)marshalling currently progressing in the current thread, or null if none.
      Returns:
      the current (un)marshalling context, or null if none.

    • push

      public static void push(Locale locale)
      Sets the locale to the given value. The old locales are remembered and will be restored by the next call to pull(). 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, or null.

    • pull

      public static void pull()
      Restores the locale which was used prior the call to push(Locale). It is not necessary to invoke this method in a finally block.

    • isFlagSet

      public static boolean isFlagSet(Context context, int flag)
      Returns true if the given flag is set.
      Parameters:
      context - the current context, or null if none.
      flag - one of MARSHALLING, SUBSTITUTE_LANGUAGE, SUBSTITUTE_COUNTRY or other bit masks.
      Returns:
      true if the given flag is set.

    • isGMLVersion

      public static boolean isGMLVersion(Context context, Version version)
      Returns true if the GML version is equal or newer than the specified version. If no GML version was specified, then this method returns true, 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, or null 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

      public static StringBuilder schema(Context context, String key, String defaultSchema)
      Returns the base URL of ISO 19115-3 (or other standards) schemas. The valid values are documented in the XML.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, or null if none.
      key - one of the value documented in the "Map key" column of XML.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

      public static PropertyType<?,?> getWrapper(Context context)
      Returns the <gml:*PropertyType> which is wrapping the <gml:*Type> object to (un)marshal, or null 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 the <gml:OperationParameter> (upper case O) element below, wrapper will be set to the temporary object representing <gml:operationParameter>. That adapter provides important information for the SIS <gml:OperationParameter> constructor.
      For performance reasons, this wrapper information is not provided by default. See setWrapper(Context, PropertyType) for more information.
      Parameters:
      context - the current context, or null if none.
      Returns:
      the <gml:*PropertyType> which is wrapping the <gml:*Type> object to (un)marshal, or null if unknown.

    • setWrapper

      public static void setWrapper(Context context, PropertyType<?,?> wrapper)
      Invoked by PropertyType 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, the PropertyType implementation needs to define the beforeUnmarshal(…) method. For an implementation example, see CC_OperationParameter.

      Parameters:
      context - the current context, or null if none.
      wrapper - the <gml:*PropertyType> which is wrapping the <gml:*Type> object to (un)marshal, or null if unknown.

    • getObjectID

      public static String getObjectID(Context context, Object object)
      If a gml:id value has already been used for the given object in the current XML document, returns that identifier. Otherwise returns null.
      Parameters:
      context - the current context, or null if none.
      object - the object for which to get the gml:id.
      Returns:
      the identifier used in the current XML document for the given object, or null if none.
      Since:
      0.7

    • getObjectForID

      public static Object getObjectForID(Context context, String id)
      Returns the object for the given gml:id, or null if none. This association is valid only for the current XML document.
      Parameters:
      context - the current context, or null 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

      public static boolean setObjectForID(Context context, Object object, String id)
      Returns true if the given identifier is available, or false if it is used by another object. If this method returns true, then the given identifier is associated to the given object for future invocation of Context methods. If this method returns false, then the caller is responsible for computing another identifier candidate.
      Parameters:
      context - the current context, or null if none.
      object - the object for which to assign the gml:id.
      id - the identifier to assign to the given object.
      Returns:
      true if the given identifier can be used.
      Since:
      0.7

    • resolver

      public static ReferenceResolver resolver(Context context)
      Returns the reference resolver in use for the current marshalling or unmarshalling process. If no resolver were explicitly set, then this method returns ReferenceResolver.DEFAULT.
      API note: This method is static for the convenience of performing the check for null context.
      Parameters:
      context - the current context, or null if none.
      Returns:
      the current reference resolver (never null).

    • converter

      public static ValueConverter converter(Context context)
      Returns the value converter in use for the current marshalling or unmarshalling process. If no converter were explicitly set, then this method returns ValueConverter.DEFAULT.
      API note: This method is static for the convenience of performing the check for null context.
      Parameters:
      context - the current context, or null 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 is null, then this method will build the log message from the exception.

      Parameters:
      context - the current context, or null 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, or null if none.
      resources - either Errors.class, Messages.class or null for the exception message.
      key - the resource keys as one of the constants defined in the Keys inner class.
      arguments - the arguments to be given to MessageFormat 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 the Errors or Messages resources. The message will be logged at Level.WARNING.
      Parameters:
      context - the current context, or null if none.
      classe - the class to declare as the warning source.
      method - the name of the method to declare as the warning source.
      resources - either Errors.class or Messages.class.
      key - the resource keys as one of the constants defined in the Keys inner class.
      arguments - the arguments to be given to MessageFormat 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, or null 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 for Level.WARNING, or false for Level.FINE.

    • finish

      public final void finish()
      Invoked in a finally block when a unmarshalling process is finished.