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
Author:
Martin Desruisseaux (Geomatys), Cullen Rombach (Image Matters)

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    LEGACY_METADATA
    Whether we are (un)marshalling legacy metadata as defined in 2003 model (ISO 19139:2007).
    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.
    static final Logger
    LOGGER
    The logger to use for warnings that are specific to XML.
    static final int
    MARSHALLING
    The bit flag telling if a marshalling process is under progress.
    static final int
    SUBSTITUTE_COUNTRY
    The bit flag for enabling substitution of country codes by character strings.
    static final int
    SUBSTITUTE_FILENAME
    The bit flag for enabling substitution of filenames by character strings.
    static final int
    SUBSTITUTE_LANGUAGE
    The bit flag for enabling substitution of language codes by character strings.
    static final int
    SUBSTITUTE_MIMETYPE
    The bit flag for enabling substitution of mime types by character strings.

  • Constructor Summary

    Constructors
    Constructor
    Description
    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.

  • Method Summary

    Modifier and Type
    Method
    Description
    static ValueConverter
    converter(Context context)
    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, or null if none.
    final void
    finish()
    Invoked in a finally block when a unmarshalling process is finished.
    final Locale
    getLocale()
    Returns the locale to use for marshalling, or null if no locale were explicitly specified.
    static Object
    getObjectForID(Context context, String id)
    Returns the object for the given gml:id, or null if none.
    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.
    final TimeZone
    getTimeZone()
    Returns the timezone to use for marshalling, or null 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, or null if this information is not provided.
    static boolean
    isFlagSet(Context context, int flag)
    Returns true if the given flag is set.
    static boolean
    isGMLVersion(Context context, Version version)
    Returns true if the GML version is equal or newer than the specified version.
    static void
    pull()
    Restores the locale which was used prior the call to push(Locale).
    static void
    push(Locale locale)
    Sets the locale to the given value.
    static ReferenceResolver
    resolver(Context context)
    Returns the reference resolver in use for the current marshalling or unmarshalling process.
    static StringBuilder
    schema(Context context, String key, String defaultSchema)
    Returns the base URL of ISO 19115-3 (or other standards) schemas.
    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.
    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.
    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.
    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.

    Methods inherited from class java.lang.Object

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

  • 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:

    • LOGGER

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

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