XML (XML base 3.19-geoapi-3.0 API)

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.geotoolkit.xml
Class XML

Object
  Static
      XML

public final class XML
extends Static
extends Static

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

LOCALE for specifying the locale to use for international strings and code lists.
TIMEZONE for specifying the timezone to use for dates and times.
SCHEMAS for specifying the root URL of metadata schemas to use.
LINKER for replacing xlink or uuidref attributes by the actual object to use.
CONVERTERS for controlling the conversion of URL, UUID, Units or similar objects.
STRING_SUBSTITUTES for specifying which code lists to replace by simpler <gco:CharacterString> elements.

Since:

3.00

Version:

3.18

Author:

Cédric Briançon (Geomatys), Martin Desruisseaux (Geomatys)

Module:

utility/geotk-xml-base (download)

View source code for this class

Field Summary
`static String`	`CONVERTERS` Allows client code to control the behavior of the (un)marshalling process when an element can not be processed, or alter the element values.
`static String`	`LINKER` Allows client code to replace `xlink` or `uuidref` attributes by the actual object to use.
`static String`	`LOCALE` Allows client code to specify the locale to use for marshalling `InternationalString` and `CodeList` instances.
`static String`	`SCHEMAS` Allows client code to specify 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` The timezone to use for marshalling dates and times.

Method Summary
`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 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(String input)` Unmarshall an object from the given string.

Methods inherited from class Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

LOCALE

public static final String LOCALE

Allows client code to specify the locale to use for marshalling InternationalString and CodeList instances. The value for this property shall be an instance of Locale.

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.

Since:: 3.17
See Also:: Marshaller.setProperty(String, Object), DefaultMetadata, Constant Field Values

TIMEZONE

public static final String TIMEZONE

The timezone to use for marshalling dates and times.

Default behavior
If this property is never set, then (un)marshalling will use the default timezone.

Since:: 3.17
See Also:: Constant Field Values

SCHEMAS

public static final String SCHEMAS

Allows client code to specify 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 Geotk 3.17, only one Map key is recognized: "gmd", which stands for the ISO 19139 schemas. Additional keys, if any, are ignored. Future Geotk versions may recognize more keys.

Valid values

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/

Since:: 3.17
See Also:: Constant Field Values

LINKER

public static final String LINKER

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

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 ObjectLinker and configure a unmarshaller as below:

ObjectLinker myLinker = ...;
Unmarshaller um = marshallerPool.acquireUnmarshaller();
um.setProperty(XML.LINKER, myLinker);
Object obj = um.unmarshal(xml);
marshallerPool.release(um);

Since:: 3.18
See Also:: Unmarshaller.setProperty(String, Object), ObjectLinker, Constant Field Values

CONVERTERS

public static final String CONVERTERS

Allows client code to control the behavior 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 ObjectConverters.

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 CONVERTERS property key and a custom ObjectConverters instance. ObjectConverters can also be used for replacing an erroneous URL by a fixed URL. See the ObjectConverters javadoc for more details.

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

class Warnings extends ObjectConverters {
    // 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.
    protected <T> boolean exceptionOccured(T value, Class<T> sourceType, Class<T> targetType, Exception e) {
        mesages.add(e.getLocalizedMessage());
        return true;
    }
}

// Unmarshall a XML string, trapping some kind of errors.
// Not all errors are trapped - see the ObjectConverters
// javadoc for more details.
Warnings myWarningList = new Warnings();
Unmarshaller um = marshallerPool.acquireUnmarshaller();
um.setProperty(XML.CONVERTERS, myWarningList);
Object obj = um.unmarshal(xml);
marshallerPool.release(um);
if (!myWarningList.isEmpty()) {
    // Report here the warnings to the user.
}

Since:: 3.17
See Also:: Unmarshaller.setProperty(String, Object), ObjectConverters, 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 coma-separated list of any of the following values: "language", "country".

Example
INSPIRE compliant language code shall be formatted like below (formatting may vary):

<gmd:language>
  <gmd:LanguageCode
      codeList="http://schemas.opengis.net/iso/19139/20070417/resources/Codelist/ML_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>

Since:: 3.18
See Also:: 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.

unmarshal

public static Object unmarshal(String input)
                        throws JAXBException

Unmarshall an object from the given string.

Parameters:: input - 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(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.

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.geotoolkit.xml Class XML

LOCALE

TIMEZONE

SCHEMAS

LINKER

CONVERTERS

STRING_SUBSTITUTES

marshal

marshal

marshal

unmarshal

unmarshal

unmarshal

org.geotoolkit.xml
Class XML