Class 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, seeMarshallerPool
). 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 Marshaller
andUnmarshaller
instances created byMarshallerPool
: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
oruuidref
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_FILTER
Filter
for being notified about non-fatal warnings. - Since:
- 0.3
Defined in the
sis-metadata
module
-
-
Field Summary
Fields Modifier and Type Field 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
Deprecated.This property is no longer honored by Apache SIS 1.0.static String
GML_VERSION
Specifies the GML version of the document to be marshalled or unmarshalled.static 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.static String
LOCALE
Specifies the locale to use for marshallingInternationalString
andCodeList
instances.static String
METADATA_VERSION
Specifies the metadata version of the document to be marshalled or unmarshalled.static String
RESOLVER
Allows client code to replacexlink
oruuidref
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_FILTER
Specifies a listener to be notified when a non-fatal error occurred during the (un)marshalling.static String
WARNING_LISTENER
Deprecated.Replaced byWARNING_FILTER
.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method 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(String xml)
Unmarshal an object from the given string.static Object
unmarshal(URL input)
Unmarshal an object from the given URL.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.
-
-
-
Field Detail
-
LOCALE
public static final String LOCALE
Specifies the locale to use for marshallingInternationalString
andCodeList
instances. The value for this property shall be an instance ofLocale
or aCharSequence
recognized byLocales.parse(String)
.This property is mostly for marshallers. However this property can also be used at unmarshalling time, for example if a
<lan:PT_FreeText>
element containing many localized strings need to be represented in a JavaString
object. In such case, the unmarshaller will try to pickup a string in the language specified by this property.Default behaviorIf 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 theDefaultInternationalString.toString(Locale)
javadoc.Special caseIf the object to be marshalled is an instance ofDefaultMetadata
, then the value given to itssetLanguage(Locale)
method will have precedence over this property. This behavior is compliant with INSPIRE rules.
-
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 ofTimeZone
or aCharSequence
recognized byTimeZone.getTimeZone(String)
.Default behaviorIf 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 ofMap<String,String>
. This property controls the URL to be used when marshalling the following elements:- The value of the
codeList
attribute when marshalling subclasses ofCodeList
. - The value of the
uom
attribute when marshalling measures (for example<gco:Distance>
).
Map
keys are currently recognized:"cat"
and"gmd"
, which stands for the new ISO 19115-3:2016 and the legacy ISO 19139:2007 schemas respectively. The key to be used depends on the metadata version to be marshalled. Additional keys, if any, are ignored. Future SIS versions may recognize more keys.Valid valuesThe following table gives some typical URLs. The URL in bold character is the default one.Supported schemas 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/
http://eden.ign.fr/xsd/fra/20060922/- See Also:
- Constant Field Values
- The value of the
-
DEFAULT_NAMESPACE
@Deprecated public static final String DEFAULT_NAMESPACE
Deprecated.This property is no longer honored by Apache SIS 1.0. UseXmlSchema
instead.Specifies the default namespace of the XML document to write. An example of value for this key is"http://www.isotc211.org/2005/gmd"
.- 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. Note that GML 3.2 is identical to ISO 19136:2007.Compatibility note: Newer versions typically have more elements, but not always. For example inThe value can be<gml:VerticalDatum>
, the<gml:verticalDatumType>
property presents in GML 3.0 and 3.1 has been removed in GML 3.2.String
orVersion
object. If no version is specified, then the most recent supported GML version is assumed.Supported GML versionsApache 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
-
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 beString
orVersion
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:domainOfValidity>
element inside a coordinate reference system is always marshalled using ISO 19139:2007 if the enclosing element uses GML 3.2 schema.Supported metadata versionsApache 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:
- Constant Field Values
-
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 aBoolean
instance, or"true"
or"false"
as aString
. If this value is not specified, then the default istrue
for allXML.unmarshal
methods andfalse
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 sometime produce undesirable results or make debugging more difficult. For this reason
MarshallerPool
applies the transformation only if explicitly requested, either by setting aMETADATA_VERSION
orGML_VERSION
explicitly, or by setting thisLENIENT_UNMARSHAL
property totrue
if the version to unmarshal is not known in advance.- Since:
- 1.0
- See Also:
- Constant Field Values
-
RESOLVER
public static final String RESOLVER
Allows client code to replacexlink
oruuidref
attributes by the actual objects to use. The value for this property shall be an instance ofReferenceResolver
.If a property in a XML document is defined only by
xlink
oruuidref
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 thegml: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.
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);
- If the reference is of the form
-
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 ofValueConverter
.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 thisCONVERTER
property key and a customValueConverter
instance.ValueConverter
can also be used for replacing an erroneous URL by a fixed URL. See theValueConverter
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. }
-
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 aString[]
array of any of the following values:- "
language
" for substituting<lan:LanguageCode>
elements - "
country
" for substituting<lan:Country>
elements - "
filename
" for substituting<gcx:FileName>
elements - "
mimetype
" for substituting<gcx:MimeFileType>
elements
Example: INSPIRE compliant language code shall be formatted like below (details may vary):
However if this property contains the "<gmd:language> <gmd:LanguageCode codeList="http://schemas.opengis.net/iso/19139/20070417/resources/Codelist/gmxCodelists.xml#LanguageCode" codeListValue="fra">French</gmd:LanguageCode> </gmd:language>
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:
- Constant Field Values
- "
-
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 ofFilter
.By default, warnings that occur during the (un)marshalling process are logged. However if a property is set for this key, then the
Filter.isLoggable(LogRecord)
method will be invoked. If that method returnsfalse
, then the warning will not be logged by the (un)marshaller.- Since:
- 1.0
- See Also:
- Constant Field Values
-
WARNING_LISTENER
@Deprecated public static final String WARNING_LISTENER
Deprecated.Replaced byWARNING_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 ofWarningListener<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 thisXML
class. The destination is specified by theoutput
argument implementation, for exampleStreamResult
for writing to a file or output stream. The optionalproperties
map can contain any key documented in thisXML
class, together with the keys documented in the supported properties section of the theMarshaller
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, ornull
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 thisXML
class. The source is specified by theinput
argument implementation, for exampleStreamSource
for reading from a file or input stream. The optionalproperties
map can contain any key documented in thisXML
class, together with the keys documented in the supported properties section of the theUnmarshaller
class.- Parameters:
input
- the file from which to read a XML representation.properties
- an optional map of properties to give to the unmarshaller, ornull
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 thisXML
class. The source is specified by theinput
argument implementation, for exampleStreamSource
for reading from a file or input stream. The optionalproperties
map can contain any key documented in thisXML
class, together with the keys documented in the supported properties section of the theUnmarshaller
class.- Type Parameters:
T
- compile-time value of thedeclaredType
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, ornull
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
-
-