Module org.apache.sis.metadata
Package org.apache.sis.xml

# Class MarshalContext

Object
MarshalContext

public abstract class MarshalContext extends Object
Context of a marshalling or unmarshalling process.

Since:
  0.3

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `MarshalContext()`
  Creates a new (un)marshalling context.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract Locale`
  `getLocale()`
  Returns the locale to use for (un)marshalling, or `null` if no locale were explicitly specified.
  `abstract TimeZone`
  `getTimeZone()`
  Returns the timezone to use for (un)marshalling, or `null` if none was explicitly specified.
  `abstract Version`
  `getVersion(String prefix)`
  Returns the schema version of the XML document being (un)marshalled.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### MarshalContext

    protected MarshalContext()
    Creates a new (un)marshalling context.

- ## Method Details

  - ### getLocale

    public abstract Locale getLocale()
    Returns the locale to use for (un)marshalling, or `null` if no locale were explicitly specified. The locale returned by this method can be used for choosing a language in an `InternationalString`.

    This locale may vary in different fragments of the same XML document. In particular children of `Metadata` inherit the locale specified by the `Metadata​.getLanguage()` attribute.

    #### Handling of `Locale​.ROOT`

    `Locale​.ROOT` is interpreted as a request for locale-neutral strings. The meaning of "locale-neutral" is implementation specific - this is usually very close to the English locale, but not necessarily. For examples dates are formatted according ISO standard instead of the rules of the English locale.

    #### Handling of `null` locale

    A `null` value means that the locale is unspecified. Callers are encouraged to use the root locale as the default value, but some flexibility is allowed.
    Returns:
      the locale for the XML fragment being (un)marshalled, or `null` if unspecified.
    See Also:
      - `DefaultInternationalString​.toString(Locale)`

  - ### getTimeZone

    public abstract TimeZone getTimeZone()
    Returns the timezone to use for (un)marshalling, or `null` if none was explicitly specified.

    #### Handling of `null` timezone

    A `null` value means that the timezone is unspecified. Callers are encouraged to use the UTC timezone as the default value, but some flexibility is allowed.
    Upcoming API change — Java time API: return type may be changed to `ZoneId` in a future version. This change may be applied in synchronization with GeoAPI 4.0.
    Returns:
      the timezone for the XML fragment being (un)marshalled, or `null` if unspecified.

  - ### getVersion

    public abstract Version getVersion(String prefix)
    Returns the schema version of the XML document being (un)marshalled. The `prefix` argument can be any of the following values (case-sensitive):

    Supported schemas
    Prefix | Standard | Typical values
    --- | --- | ---
    gml | Geographic Markup Language | `3.0`, `3.2`
    gmd | Geographic MetaData | `2007`, `2016`

    Parameters:
      `prefix` - one of the above-cited prefix.
    Returns:
      the version for the given schema, or `null` if unknown.