XML (Apache SIS utilities 0.6 API)

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

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 object 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

Methods
Modifier and Type	Method and Description
`static String`	`marshal(Object object)` Marshall the given object into a string.
`static void`	`marshal(Object object, File output)` Marshall the given object into a file.
`static void`	`marshal(Object object, OutputStream output)` Marshall the given object into a stream.
`static void`	`marshal(Object object, Result output, Map<String,?> properties)` Marshall the given object to a stream, DOM or other destinations.
`static Object`	`unmarshal(File input)` Unmarshall an object from the given file.
`static Object`	`unmarshal(InputStream input)` Unmarshall an object from the given stream.
`static Object`	`unmarshal(Source input, Map<String,?> properties)` Unmarshall an object from the given stream, DOM or other sources.
`static Object`	`unmarshal(String xml)` Unmarshall an object from the given string.
`static Object`	`unmarshal(URL input)` Unmarshall 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 org.apache.sis.metadata.iso.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:
Marshaller.setProperty(String, Object), org.apache.sis.metadata.iso.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:
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. This limitation may be fixed in a future SIS version.

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 object 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 to create an empty element which contain only the values of the above-cited attributes. This is usually not the right behavior, since we should use the reference (href or uuidref attributes) for fetching the appropriate object. However doing so require some application knowledge, for example a catalog where to perform the search, which is left to users. Users can define their search algorithm by subclassing ReferenceResolver and configure 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
```
  Marshall 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
```
  Marshall 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
```
  Marshall 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,
           Result output,
           Map<String,?> properties)
                    throws JAXBException
```
  Marshall 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
```
  Unmarshall 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
```
  Unmarshall 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
```
  Unmarshall 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
```
  Unmarshall 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(Source input,
               Map<String,?> properties)
                        throws JAXBException
```
  Unmarshall an object from the given stream, DOM or other sources. 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

Class XML

Field Summary

Method Summary

Methods inherited from class Object

Field Detail

LOCALE

TIMEZONE

SCHEMAS

DEFAULT_NAMESPACE

GML_VERSION

RESOLVER

CONVERTER

STRING_SUBSTITUTES

WARNING_LISTENER

Method Detail

marshal

marshal

marshal

marshal

unmarshal

unmarshal

unmarshal

unmarshal

unmarshal