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

Class XML

Object
Static
XML
public final class XML extends Static
Provides convenience methods for marshalling and unmarshalling SIS objects. Marshalling operations use the standard versions listed below (for marshalling a document in a different version, see Marshaller­Pool). Unmarshalling detects the version automatically.
Versions of standards applied at marshalling time
Topic SIS 0.3 to 0.8 SIS 1.0 Remarks
Metadata ISO 19139:2007 ISO 19115-3:2016
Referencing ISO 19136:2007 ISO 19136:2007 Same as GML 3.2
This class defines also some property keys that can be given to the Marshaller and Unmarshaller instances created by Marshaller­Pool:
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.
GML_VERSION Version for specifying the GML version of the document to be (un)marshalled.
METADATA_VERSION Version for specifying the metadata version of the document to 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:Character­String> elements.
WARNING_FILTER Filter for being notified about non-fatal warnings.
Since:
0.3

  • Field Details

    • LOCALE

      public static final String LOCALE
      Specifies the locale to use for marshalling International­String and Code­List instances. The value for this property shall be an instance of Locale or a Char­Sequence 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 <lan:PT_Free­Text> 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 Default­International­String​.to­String(Locale) javadoc.

      Special case

      If the object to be marshalled is an instance of Default­Metadata, then the value given to its set­Language(Locale) method will have precedence over this property. This behavior is compliant with INSPIRE rules.
      See Also:

    • 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 Time­Zone or a Char­Sequence recognized by Time­Zone​.get­Time­Zone(String).

      Default behavior

      If this property is never set, then (un)marshalling will use the default timezone.
      See Also:

    • SCHEMAS

      public static final String SCHEMAS
      Specifies the root URLs of some schemas. This property modifies only the URL strings; it does not change the structure of marshalled XML documents (for content structure, see METADATA_VERSION). The value for this property shall be an instance of Map<String,String>. This property controls the URLs to be used when marshalling the following elements:
      • The value of the code­List attribute when marshalling subclasses of Code­List.
      • The value of the uom attribute when marshalling measures (for example <gco:Distance>).

      Examples

      URLs in code lists and is units of measurement may appear as below. The underlined fragment is the part that can be replaced by SCHEMAS values:
      • http://standards​.iso​.org/iso/19115/resources/Codelist/cat/codelists​.xml#Language­Code
      • http://www​.isotc211​.org/2005/resources/Codelist/gmx­Codelists​.xml#Language­Code
      • http://www​.isotc211​.org/2005/resources/uom/gmx­Uom​.xml#xpointer(//*[@gml:id='m'])

      Implementation note

      The currently recognized keys are listed below. The entries to be used depend on the metadata version to be marshalled. For example, the "cat" entry is used when marshalling ISO 19115-3:2016 document, while the "gmd" and "gmi" entries are used when marshalling ISO 19139:2007 documents. The following table gives some typical URLs, with the default URL in bold characters:
      Supported root URLs
      Map key Typical values (choose only one)
      cat http://standards.iso.org/iso/19115/
      gmd http://www.isotc211.org/2005/
      http://schemas.opengis.net/iso/19139/20070417/
      http://standards.iso.org/ittf/PubliclyAvailableStandards/ISO_19139_Schemas/
      Additional keys, if any, are ignored. Future SIS versions may recognize more keys.
      See Also:

    • 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. Note that GML 3.2 is identical to ISO 19136:2007. The value can be String or Version object. If no version is specified, then the most recent supported 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.

      Compatibility note

      Newer GML versions typically have more elements, but not always. For example, in <gml:Vertical­Datum>, the <gml:vertical­Datum­Type> property presents in GML 3.0 and 3.1 has been removed in GML 3.2.
      See Also:

    • METADATA_VERSION

      public static final String METADATA_VERSION
      Specifies the metadata version of the document to be marshalled or unmarshalled. The metadata version may affect the set of XML elements to be marshalled and their namespaces. The value can be String or Version object. If no version is specified, then the most recent supported metadata version is assumed.

      The metadata version may be ignored when the metadata to marshal is inside a GML element. For example, the <gml:domain­Of­Validity> element inside a coordinate reference system is always marshalled using ISO 19139:2007 if the enclosing element uses GML 3.2 schema.

      Supported metadata versions

      Apache SIS currently supports ISO 19115-3:2016 by default. This version can be explicitly set with value "2014" or above (because the abstract model was defined in ISO 19115-1:2014). SIS can write legacy ISO 19139:2007 documents if this property is set to a value less than "2014". Both versions can be read without the need to specify this property.
      Since:
      1.0
      See Also:

    • LENIENT_UNMARSHAL

      public static final String LENIENT_UNMARSHAL
      Specifies whether the unmarshalling process should accept any metadata or GML supported version if the user did not specified an explicit version. The value can be a Boolean instance, or "true" or "false" as a String. If this value is not specified, then the default is true for all XML​.unmarshal methods and false otherwise.

      Metadata and Geographic Markup Language have slightly different XML encoding depending on the OGC/ISO version in use. Often the namespaces are different, but not only. Internally, Apache SIS supports only the schema versions documented in this class javadoc, for example the ISO 19115-3:2016 version of metadata schema. For unmarshalling a document encoded according an older metadata schema (e.g. ISO 19139:2007), a transformation is applied on-the-fly. However this transformation may sometimes produce undesirable results or make debugging more difficult. For this reason Marshaller­Pool applies the transformation only if explicitly requested, either by setting a METADATA_VERSION or GML_VERSION explicitly, or by setting this LENIENT_UNMARSHAL property to true if the version to unmarshal is not known in advance.

      Since:
      1.0
      See Also:

    • 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 Reference­Resolver.

      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 sometimes do better by using some domain-specific knowledge, for example by searching in a database. Users can define their search algorithm by subclassing Reference­Resolver 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:

    • CONVERTER

      public static final String CONVERTER
      Controls the behaviors of the (un)marshalling process when an element cannot be processed, or alter the element values. The value for this property shall be an instance of Value­Converter.

      If an element in a XML document cannot 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​.set­Property(String, Object) with this CONVERTER property key and a custom Value­Converter instance. Value­Converter can also be used for replacing an erroneous URL by a fixed URL. See the Value­Converter 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:

    • STRING_SUBSTITUTES

      public static final String STRING_SUBSTITUTES
      Allows marshallers to substitute some code lists by the simpler <gco:Character­String> element. The value for this property shall be a String[] array of any of the following values:
      • "language" for substituting <lan:Language­Code> elements
      • "country" for substituting <lan:Country> elements
      • "filename" for substituting <gcx:File­Name> elements
      • "mimetype" for substituting <gcx:Mime­File­Type> elements

      Example

      INSPIRE compliant language code shall be formatted like below (details may vary): 
        <gmd:language>
    <gmd:LanguageCode
        codeList="http://www.isotc211.org/2005/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): 
        <lan:language>
    <gco:CharacterString>fra</gco:CharacterString>
  </lan:language>
      See Also:

    • WARNING_FILTER

      public static final String WARNING_FILTER
      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 Filter.

      By default, warnings that occur during the (un)marshalling process are logged. However if a property is set for this key, then the Filter​.is­Loggable(Log­Record) method will be invoked. If that method returns false, then the warning will not be logged by the (un)marshaller.

      Since:
      1.0
      See Also:

  • Method Details

    • 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 Stream­Result 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 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 Stream­Source 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 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 Stream­Source 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 Unmarshaller class.
      Type Parameters:
      T - compile-time value of the declared­Type argument.
      Parameters:
      input - the file from which to read a XML representation.
      declared­Type - 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