public final class XML extends Static
Marshaller
and Unmarshaller
instances created by PooledMarshaller
:
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. |
Defined in the sis-utility
module
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.
|
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.
|
public static final String LOCALE
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.
DefaultInternationalString.toString(Locale)
javadoc.
DefaultMetadata
, then the value given to its
setLanguage(Locale)
method will have precedence over this property. This behavior is compliant with INSPIRE rules.public static final String TIMEZONE
TimeZone
or a CharSequence
recognized by TimeZone.getTimeZone(String)
.
public static final String SCHEMAS
Map<String,String>
.
This property controls the URL to be used when marshalling the following elements:
codeList
attribute when marshalling subclasses of
CodeList
in ISO 19139 compliant XML document.uom
attribute when marshalling measures (for example
<gco:Distance>
) in ISO 19139 compliant XML document.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.
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/ |
public static final String DEFAULT_NAMESPACE
"http://www.isotc211.org/2005/gmd"
.
MarshallerPool
constructors.
Specifying this property to Marshaller.setProperty(String, Object)
is too late.
This limitation may be fixed in a future SIS version.public static final String GML_VERSION
<gml:VerticalDatum>
,
the <gml:verticalDatumType>
property presents in GML 3.0 and 3.1 has been removed in GML 3.2.String
or Version
objects.
If no version is specified, then the most recent GML version is assumed.
public static final String RESOLVER
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);
public static final String CONVERTER
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.
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. }
public static final String STRING_SUBSTITUTES
<gco:CharacterString>
element.
The value for this property shall be a String[]
array of any of the following values:
language
" for substituting <gmd:LanguageCode>
elementscountry
" for substituting <gmd:Country>
elementsfilename
" for substituting <gmx:FileName>
elementsmimetype
" for substituting <gmx:MimeFileType>
elementsHowever 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):
<gmd:language> <gco:CharacterString>fra</gco:CharacterString> </gmd:language>
public static final String WARNING_LISTENER
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.
WarningListener
,
Constant Field Valuespublic static String marshal(Object object) throws JAXBException
object
- The root of content tree to be marshalled.JAXBException
- If an error occurred during the marshalling.public static void marshal(Object object, OutputStream output) throws JAXBException
object
- The root of content tree to be marshalled.output
- The stream where to write.JAXBException
- If an error occurred during the marshalling.public static void marshal(Object object, File output) throws JAXBException
object
- The root of content tree to be marshalled.output
- The file to be written.JAXBException
- If an error occurred during the marshalling.public static void marshal(Object object, Result output, Map<String,?> properties) throws JAXBException
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.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.JAXBException
- If a property has an illegal value, or if an error occurred during the marshalling.public static Object unmarshal(String xml) throws JAXBException
xml
- The XML representation of an object.JAXBException
- If an error occurred during the unmarshalling.public static Object unmarshal(InputStream input) throws JAXBException
input
- The stream from which to read a XML representation.JAXBException
- If an error occurred during the unmarshalling.public static Object unmarshal(URL input) throws JAXBException
input
- The URL from which to read a XML representation.JAXBException
- If an error occurred during the unmarshalling.public static Object unmarshal(File input) throws JAXBException
input
- The file from which to read a XML representation.JAXBException
- If an error occurred during the unmarshalling.public static Object unmarshal(Source input, Map<String,?> properties) throws JAXBException
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.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.JAXBException
- If a property has an illegal value, or if an error occurred during the unmarshalling.Copyright © 2010–2015 The Apache Software Foundation. All rights reserved.