org.apache.sis.xml

## Class XML

- Object
- - Static
  - - XML

-     public final class XML
      extends Static

  Provides convenience methods for marshalling and unmarshalling SIS objects. This class defines also some property keys that can be given to the `Marshaller` and `Unmarshaller` instances created by `PooledMarshaller`:

  Supported (un)marshaller properties
  Key | Value type | Purpose
  --- | --- | ---
  `LOCALE` | `Locale` | for specifying the locale to use for international strings and code lists.
  `TIMEZONE` | `TimeZone` | for specifying the timezone to use for dates and times.
  `SCHEMAS` | `Map` | for specifying the root URL of metadata schemas to use.
  `DEFAULT_NAMESPACE` | `String` | for specifying the default namespace of the XML document to write.
  `GML_VERSION` | `Version` | for specifying the GML version to the document be (un)marshalled.
  `RESOLVER` | `ReferenceResolver` | for replacing `xlink` or `uuidref` attributes by the actual object to use.
  `CONVERTER` | `ValueConverter` | for controlling the conversion of URL, UUID, Units or similar objects.
  `STRING_SUBSTITUTES` | `String[]` | for specifying which code lists to replace by simpler `<gco:CharacterString>` elements.
  `WARNING_LISTENER` | `WarningListener` | for being notified about non-fatal warnings.

  Since:
    0.3

  Defined in the `sis-utility` module

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONVERTER` Controls the behaviors of the (un)marshalling process when an element can not be processed, or alter the element values.
    `static String` | `DEFAULT_NAMESPACE` Specifies the default namespace of the XML document to write.
    `static String` | `GML_VERSION` Specifies the GML version of the document to be marshalled or unmarshalled.
    `static String` | `LOCALE` Specifies the locale to use for marshalling `InternationalString` and `CodeList` instances.
    `static String` | `RESOLVER` Allows client code to replace `xlink` or `uuidref` attributes by the actual objects to use.
    `static String` | `SCHEMAS` Specifies the root URL of schemas.
    `static String` | `STRING_SUBSTITUTES` Allows marshallers to substitute some code lists by the simpler `<gco:CharacterString>` element.
    `static String` | `TIMEZONE` Specifies the timezone to use for marshalling dates and times.
    `static String` | `WARNING_LISTENER` Specifies a listener to be notified when a non-fatal error occurred during the (un)marshalling.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `marshal(Object object)` Marshal the given object into a string.
    `static void` | `marshal(Object object, File output)` Marshal the given object into a file.
    `static void` | `marshal(Object object, OutputStream output)` Marshal the given object into a stream.
    `static void` | `marshal(Object object, Path output)` Marshal the given object into a path.
    `static void` | `marshal(Object object, Result output, Map<String,?> properties)` Marshal the given object to a stream, DOM or other destinations.
    `static Object` | `unmarshal(File input)` Unmarshal an object from the given file.
    `static Object` | `unmarshal(InputStream input)` Unmarshal an object from the given stream.
    `static Object` | `unmarshal(Path input)` Unmarshal an object from the given path.
    `static <T> JAXBElement<T>` | `unmarshal(Source input, Class<T> declaredType, Map<String,?> properties)` Unmarshal an object from the given stream, DOM or other sources.
    `static Object` | `unmarshal(Source input, Map<String,?> properties)` Unmarshal an object from the given stream, DOM or other sources.
    `static Object` | `unmarshal(String xml)` Unmarshal an object from the given string.
    `static Object` | `unmarshal(URL input)` Unmarshal an object from the given URL.

    - ### Methods inherited from class Object

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

- - ### Field Detail

    - #### LOCALE

          public static final String LOCALE

      Specifies the locale to use for marshalling `InternationalString` and `CodeList` instances. The value for this property shall be an instance of `Locale` or a `CharSequence` recognized by `Locales​.parse(String)`.

      This property is mostly for marshallers. However this property can also be used at unmarshalling time, for example if a `<gmd:PT_FreeText>` element containing many localized strings need to be represented in a Java `String` object. In such case, the unmarshaller will try to pickup a string in the language specified by this property.

      Default behavior
      If this property is never set, then (un)marshalling will try to use "unlocalized" strings - typically some programmatic strings like UML identifiers. While such identifiers often look like English words, they are not considered as the English localization. The algorithm attempting to find a "unlocalized" string is defined in the `DefaultInternationalString​.toString(Locale)` javadoc.
      Special case
      If the object to be marshalled is an instance of `DefaultMetadata`, then the value given to its `setLanguage(Locale)` method will have precedence over this property. This behavior is compliant with INSPIRE rules.
      See Also:
        `OptionKey​.LOCALE`, `Marshaller​.setProperty(String, Object)`, `DefaultMetadata​.setLanguage(Locale)`, Constant Field Values

    - #### TIMEZONE

          public static final String TIMEZONE

      Specifies the timezone to use for marshalling dates and times. The value for this property shall be an instance of `TimeZone` or a `CharSequence` recognized by `TimeZone​.getTimeZone(String)`.
      Default behavior
      If this property is never set, then (un)marshalling will use the default timezone.
      See Also:
        `OptionKey​.TIMEZONE`, Constant Field Values

    - #### SCHEMAS

          public static final String SCHEMAS

      Specifies the root URL of schemas. The value for this property shall be an instance of `Map<String,String>`. This property controls the URL to be used when marshalling the following elements:
      - The value of the `codeList` attribute when marshalling subclasses of `CodeList` in ISO 19139 compliant XML document.
      - The value of the `uom` attribute when marshalling measures (for example `<gco:Distance>`) in ISO 19139 compliant XML document.
      As of SIS 0.3, only one `Map` key is recognized: `"gmd"`, which stands for the ISO 19139 schemas. Additional keys, if any, are ignored. Future SIS versions may recognize more keys.
      Valid values

      Supported schemas
      Map key | Typical values (choose only one)
      --- | ---
      gmd | http://schemas.opengis.net/iso/19139/20070417/ http://standards.iso.org/ittf/PubliclyAvailableStandards/ISO_19139_Schemas/ http://eden.ign.fr/xsd/fra/20060922/

      See Also:
        Constant Field Values

    - #### DEFAULT_NAMESPACE

          public static final String DEFAULT_NAMESPACE

      Specifies the default namespace of the XML document to write. An example of value for this key is `"http://www​.isotc211​.org/2005/gmd"`.
      Current limitation
      In current SIS implementation, this property is honored only by the `MarshallerPool` constructors. Specifying this property to `Marshaller​.setProperty(String, Object)` is too late.
      See Also:
        Constant Field Values

    - #### GML_VERSION

          public static final String GML_VERSION

      Specifies the GML version of the document to be marshalled or unmarshalled. The GML version may affect the set of XML elements to be marshalled and their namespaces.
      Compatibility note: Newer versions typically have more elements, but not always. For example in `<gml:VerticalDatum>`, the `<gml:verticalDatumType>` property presents in GML 3.0 and 3.1 has been removed in GML 3.2.
      The value can be `String` or `Version` objects. If no version is specified, then the most recent GML version is assumed.
      Supported GML versions
      Apache SIS currently supports GML 3.2.1 by default. SIS can read and write GML 3.2 if this property is set to "3.2". It is also possible to set this property to "3.1", but the marshalled XML is not GML 3.1.1 conformant because of the differences between the two schemas. See SIS-160: Need XSLT between GML 3.1 and 3.2 for information about the status of GML 3.1.1 support.
      See Also:
        Constant Field Values

    - #### RESOLVER

          public static final String RESOLVER

      Allows client code to replace `xlink` or `uuidref` attributes by the actual objects to use. The value for this property shall be an instance of `ReferenceResolver`.

      If a property in a XML document is defined only by `xlink` or `uuidref` attributes, without any concrete definition, then the default behavior is as below:

      - If the reference is of the form `xlink:href="#foo"` and an object with the `gml:id="foo"` attribute was previously found in the same XML document, then that object will be used.
      - Otherwise an empty element containing only the values of the above-cited attributes is created.
      Applications can sometime do better by using some domain-specific knowledge, for example by searching in a database. Users can define their search algorithm by subclassing `ReferenceResolver` and configuring a unmarshaller as below:

          ReferenceResolver  myResolver = ...;
          Map<String,Object> properties = new HashMap<>();
          properties.put(XML.RESOLVER, myResolver);
          Object obj = XML.unmarshal(source, properties);

      See Also:
        `Unmarshaller​.setProperty(String, Object)`, `ReferenceResolver`, Constant Field Values

    - #### CONVERTER

          public static final String CONVERTER

      Controls the behaviors of the (un)marshalling process when an element can not be processed, or alter the element values. The value for this property shall be an instance of `ValueConverter`.

      If an element in a XML document can not be parsed (for example if a URL string is not valid), the default behavior is to throw an exception which cause the (un)marshalling of the entire document to fail. This default behavior can be customized by invoking `Marshaller​.setProperty(String, Object)` with this `CONVERTER` property key and a custom `ValueConverter` instance. `ValueConverter` can also be used for replacing an erroneous URL by a fixed URL. See the `ValueConverter` javadoc for more details.

      Example: the following example collects the failures in a list without stopping the (un)marshalling process.

          class WarningCollector extends ValueConverter {
              // The warnings collected during (un)marshalling.
              List<String> messages = new ArrayList<String>();

              // Override the default implementation in order to
              // collect the warnings and allow the process to continue.
              @Override
              protected <T> boolean exceptionOccured(MarshalContext context,
                      T value, Class<T> sourceType, Class<T> targetType, Exception e)
              {
                  mesages.add(e.getLocalizedMessage());
                  return true;
              }
          }

          // Unmarshal a XML string, trapping some kind of errors.
          // Not all errors are trapped - see the ValueConverter
          // javadoc for more details.
          WarningCollector myWarningList = new WarningCollector();
          Map<String,Object> properties = new HashMap<>();
          properties.put(XML.CONVERTER, myWarningList);
          Object obj = XML.unmarshal(source, properties);
          if (!myWarningList.isEmpty()) {
              // Report here the warnings to the user.
          }

      See Also:
        `Unmarshaller​.setProperty(String, Object)`, `ValueConverter`, Constant Field Values

    - #### STRING_SUBSTITUTES

          public static final String STRING_SUBSTITUTES

      Allows marshallers to substitute some code lists by the simpler `<gco:CharacterString>` element. The value for this property shall be a `String[]` array of any of the following values:
      - "`language`" for substituting `<gmd:LanguageCode>` elements
      - "`country`" for substituting `<gmd:Country>` elements
      - "`filename`" for substituting `<gmx:FileName>` elements
      - "`mimetype`" for substituting `<gmx:MimeFileType>` elements
      Example: INSPIRE compliant language code shall be formatted like below (details may vary):

          <gmd:language>
            <gmd:LanguageCode
                codeList="http://schemas.opengis.net/iso/19139/20070417/resources/Codelist/gmxCodelists.xml#LanguageCode"
                codeListValue="fra">French</gmd:LanguageCode>
          </gmd:language>

      However if this property contains the "`language`" value, then the marshaller will format the language code like below (which is legal according OGC schemas, but is not INSPIRE compliant):

          <gmd:language>
            <gco:CharacterString>fra</gco:CharacterString>
          </gmd:language>

      See Also:
        Constant Field Values

    - #### WARNING_LISTENER

          public static final String WARNING_LISTENER

      Specifies a listener to be notified when a non-fatal error occurred during the (un)marshalling. The value for this property shall be an instance of `WarningListener<Object>`.

      By default, warnings that occur during the (un)marshalling process are logged. However if a property is set for this key, then the `WarningListener​.warningOccured(Object, LogRecord)` method will be invoked and the warning will not be logged by the (un)marshaller.

      See Also:
        `WarningListener`, Constant Field Values

  - ### Method Detail

    - #### marshal

          public static String marshal(Object object)
                                throws JAXBException

      Marshal the given object into a string.
      Parameters:
        `object` - the root of content tree to be marshalled.
      Returns:
        the XML representation of the given object.
      Throws:
        `JAXBException` - if an error occurred during the marshalling.

    - #### marshal

          public static void marshal(Object object,
                                     OutputStream output)
                              throws JAXBException

      Marshal the given object into a stream.
      Parameters:
        `object` - the root of content tree to be marshalled.
        `output` - the stream where to write.
      Throws:
        `JAXBException` - if an error occurred during the marshalling.

    - #### marshal

          public static void marshal(Object object,
                                     File output)
                              throws JAXBException

      Marshal the given object into a file.
      Parameters:
        `object` - the root of content tree to be marshalled.
        `output` - the file to be written.
      Throws:
        `JAXBException` - if an error occurred during the marshalling.

    - #### marshal

          public static void marshal(Object object,
                                     Path output)
                              throws JAXBException

      Marshal the given object into a path.
      Parameters:
        `object` - the root of content tree to be marshalled.
        `output` - the file to be written.
      Throws:
        `JAXBException` - if an error occurred during the marshalling.

    - #### marshal

          public static void marshal(Object object,
                                     Result output,
                                     Map<String,?> properties)
                              throws JAXBException

      Marshal the given object to a stream, DOM or other destinations. This is the most flexible marshalling method provided in this `XML` class. The destination is specified by the `output` argument implementation, for example `StreamResult` for writing to a file or output stream. The optional `properties` map can contain any key documented in this `XML` class, together with the keys documented in the supported properties section of the the `Marshaller` class.
      Parameters:
        `object` - the root of content tree to be marshalled.
        `output` - the file to be written.
        `properties` - an optional map of properties to give to the marshaller, or `null` if none.
      Throws:
        `JAXBException` - if a property has an illegal value, or if an error occurred during the marshalling.
      Since:
        0.4

    - #### unmarshal

          public static Object unmarshal(String xml)
                                  throws JAXBException

      Unmarshal an object from the given string. Note that the given argument is the XML document itself, not a URL to a XML document.
      Parameters:
        `xml` - the XML representation of an object.
      Returns:
        the object unmarshalled from the given input.
      Throws:
        `JAXBException` - if an error occurred during the unmarshalling.

    - #### unmarshal

          public static Object unmarshal(InputStream input)
                                  throws JAXBException

      Unmarshal an object from the given stream.
      Parameters:
        `input` - the stream from which to read a XML representation.
      Returns:
        the object unmarshalled from the given input.
      Throws:
        `JAXBException` - if an error occurred during the unmarshalling.

    - #### unmarshal

          public static Object unmarshal(URL input)
                                  throws JAXBException

      Unmarshal an object from the given URL.
      Parameters:
        `input` - the URL from which to read a XML representation.
      Returns:
        the object unmarshalled from the given input.
      Throws:
        `JAXBException` - if an error occurred during the unmarshalling.

    - #### unmarshal

          public static Object unmarshal(File input)
                                  throws JAXBException

      Unmarshal an object from the given file.
      Parameters:
        `input` - the file from which to read a XML representation.
      Returns:
        the object unmarshalled from the given input.
      Throws:
        `JAXBException` - if an error occurred during the unmarshalling.

    - #### unmarshal

          public static Object unmarshal(Path input)
                                  throws JAXBException

      Unmarshal an object from the given path.
      Parameters:
        `input` - the path from which to read a XML representation.
      Returns:
        the object unmarshalled from the given input.
      Throws:
        `JAXBException` - if an error occurred during the unmarshalling.

    - #### unmarshal

          public static Object unmarshal(Source input,
                                         Map<String,?> properties)
                                  throws JAXBException

      Unmarshal an object from the given stream, DOM or other sources. Together with the Unmarshal by Declared Type variant, this is the most flexible unmarshalling method provided in this `XML` class. The source is specified by the `input` argument implementation, for example `StreamSource` for reading from a file or input stream. The optional `properties` map can contain any key documented in this `XML` class, together with the keys documented in the supported properties section of the the `Unmarshaller` class.
      Parameters:
        `input` - the file from which to read a XML representation.
        `properties` - an optional map of properties to give to the unmarshaller, or `null` if none.
      Returns:
        the object unmarshalled from the given input.
      Throws:
        `JAXBException` - if a property has an illegal value, or if an error occurred during the unmarshalling.
      Since:
        0.4

    - #### unmarshal

          public static <T> JAXBElement<T> unmarshal(Source input,
                                                     Class<T> declaredType,
                                                     Map<String,?> properties)
                                              throws JAXBException

      Unmarshal an object from the given stream, DOM or other sources. Together with the Unmarshal Global Root Element variant, this is the most flexible unmarshalling method provided in this `XML` class. The source is specified by the `input` argument implementation, for example `StreamSource` for reading from a file or input stream. The optional `properties` map can contain any key documented in this `XML` class, together with the keys documented in the supported properties section of the the `Unmarshaller` class.
      Type Parameters:
        `T` - compile-time value of the `declaredType` argument.
      Parameters:
        `input` - the file from which to read a XML representation.
        `declaredType` - the JAXB mapped class of the object to unmarshal.
        `properties` - an optional map of properties to give to the unmarshaller, or `null` if none.
      Returns:
        the object unmarshalled from the given input, wrapped in a JAXB element.
      Throws:
        `JAXBException` - if a property has an illegal value, or if an error occurred during the unmarshalling.
      Since:
        0.8

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.