Module org.apache.sis.metadata

Package org.apache.sis.xml

Class ValueConverter

Object

ValueConverter

public class ValueConverter
extends Object

Performs conversions of XML element or attribute values encountered during XML (un)marshalling. Each method in this class is a converter and can be invoked at (un)marshalling time. The default implementation is straightforward and documented in the javadoc of each method.

This class provides a way to handle the errors which may exist in some XML documents. For example, a URL in the document may be malformed, causing a Malformed­URLException to be thrown. If this error is not handled, it will cause the (un)marshalling of the entire document to fail. An application may want to change this behavior by replacing URLs that are known to be erroneous by fixed versions of those URLs. Example:

class URLFixer extends ValueConverter {
    @Override
    public URL toURL(MarshalContext context, URI uri) throws MalformedURLException {
        try {
            return super.toURL(context, uri);
        } catch (MalformedURLException e) {
            if (uri.equals(KNOWN_ERRONEOUS_URI) {
                return FIXED_URL;
            } else {
                throw e;
            }
        }
    }
}

See the XML.CONVERTER javadoc for an example of registering a custom Value­Converter to a (un)marshaller.

Since:

0.3

Field Summary

Fields

Modifier and Type	Field	Description
static final Value­Converter	DEFAULT	The default, thread-safe and immutable instance.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Value­Converter()	Creates a default Value­Converter.

Method Summary

Modifier and Type	Method	Description
protected <T> boolean	exception­Occured(Marshal­Context context, T value, Class<T> source­Type, Class<?> target­Type, Exception exception)	Invoked when an exception occurred in any to­XXX(…) method.
Charset	to­Charset(Marshal­Context context, String value)	Converts the given string to a character set.
String	to­Charset­Code(Marshal­Context context, Charset value)	Converts the given character set to a code.
String	to­Country­Code(Marshal­Context context, Locale value)	Converts the given locale to a country code.
String	to­Language­Code(Marshal­Context context, Locale value)	Converts the given locale to a language code.
Locale	to­Locale(Marshal­Context context, String value)	Converts the given string to a locale.
Nil­Reason	to­Nil­Reason(Marshal­Context context, String value)	Converts the given string to a Nil­Reason.
Unit<?>	to­Unit(Marshal­Context context, String value)	Converts the given string to a unit.
URI	to­URI(Marshal­Context context, String value)	Converts the given string to a URI.
URI	to­URI(Marshal­Context context, URL value)	Converts the given URL to a URI.
URL	to­URL(Marshal­Context context, URI value)	Converts the given URI to a URL.
UUID	to­UUID(Marshal­Context context, String value)	Converts the given string to a Universal Unique Identifier.

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Field Details

DEFAULT

public static final ValueConverter DEFAULT

The default, thread-safe and immutable instance. This instance defines the converters used during every (un)marshalling if no Value­Converter was explicitly set.

Constructor Details

ValueConverter

protected ValueConverter()

Creates a default Value­Converter. This is for subclasses only, since new instances are useful only if at least one method is overridden.

Method Details

exceptionOccured

protected <T> boolean exceptionOccured(MarshalContext context,
 T value,
 Class<T> sourceType,
 Class<?> targetType,
 Exception exception)

Invoked when an exception occurred in any to­XXX(…) method. The default implementation does nothing and return false, which will cause the (un)marshalling process of the whole XML document to fail.

This method provides a single hook that subclasses can override in order to provide their own error handling for every methods defined in this class, like the example documented in the XML.CONVERTER javadoc. Subclasses also have the possibility to override individual to­XXX(…) methods, like the example provided in this class javadoc.

Type Parameters:

T - the compile-time type of the source­Type argument.

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the value that cannot be converted.

source­Type - the base type of the value to convert. This is determined by the argument type of the method that caught the exception. For example, the source type is always URI.class if the exception has been caught by the to­URL(Marshal­Context, URI) method.

target­Type - the expected type of the converted object.

exception - the exception that occurred during the conversion attempt.

Returns:

true if the (un)marshalling process should continue despite this error, or false (the default) if the exception should be propagated, thus causing the (un)marshalling to fail.

toLanguageCode

public String toLanguageCode(MarshalContext context,
 Locale value)
                      throws MissingResourceException

Converts the given locale to a language code. For better compliance with ISO standards, the language code should be a 3-letters ISO 639-2 code (e.g. "jpn" for Japanese). However, those codes may not be available for every locales.

The default implementation performs the following steps:

• Try Locale.get­ISO3Language():
  • On success, return that value if non-empty, or null otherwise.
  • If an exception has been thrown, then:
    • If exception­Occured(…) return true, then returns value.get­Language() if non-empty or null otherwise.
    • If exception­Occured(…) returned false (which is the default behavior), then let the exception propagate.

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the locale to convert to a language code, or null.

Returns:

the language code, or null if the given value was null or does not contains a language code.

Throws:

Missing­Resource­Exception - if no language code can be found for the given locale.

See Also:

• Locale.get­ISO3Language()
• Locale.get­Language()

toCountryCode

public String toCountryCode(MarshalContext context,
 Locale value)
                     throws MissingResourceException

Converts the given locale to a country code. For better compliance with ISO standards, the country code should be a 2-letters ISO 3166 code (e.g. "JP" for Japan).

The default implementation returns Locale.get­Country() if non-empty, or null otherwise.

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the locale to convert to a country code, or null.

Returns:

the country code, or null if the given value was null or does not contains a country code.

Throws:

Missing­Resource­Exception - if no country code can be found for the given locale.

See Also:

• Locale.get­ISO3Country()
• Locale.get­Country()

toCharsetCode

public String toCharsetCode(MarshalContext context,
 Charset value)

Converts the given character set to a code.

The default implementation first invokes Charset.name(). Then if marshalling to legacy ISO 19139:2007, this method converts the IANA name to a ISO 19115:2003 MD_Character­Set­Code using the following equivalence table:

IANA to ISO 19115:2003 character set code

From ISO codes IANA ISO 19115:2003 ISO-8859-1 8859part1 ISO-8859-2 8859part2 ISO-8859-3 8859part3 ISO-8859-4 8859part4 ISO-8859-5 8859part5 ISO-8859-6 8859part6 ISO-8859-7 8859part7 ISO-8859-8 8859part8 ISO-8859-9 8859part9 ISO-8859-10 8859part10 ISO-8859-11 8859part11 ISO-8859-12 8859part12 ISO-8859-13 8859part13 ISO-8859-14 8859part14 ISO-8859-15 8859part15 ISO-8859-16 8859part16

Others IANA ISO 19115:2003 UCS-2 ucs2 UCS-4 ucs4 UTF-7 utf7 UTF-8 utf8 UTF-16 utf16 JIS_X0201 jis Shift_JIS shiftJIS EUC-JP eucJP US-ASCII usAscii EBCDIC ebcdic EUC-KR eucKR Big5 big5 GB2312 GB2312

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the locale to convert to a character set code, or null.

Returns:

the country code, or null if the given value was null.

Since:

0.5

See Also:

• Charset.name()

toLocale

public Locale toLocale(MarshalContext context,
 String value)
                throws IllformedLocaleException

Converts the given string to a locale. The string is the language code either as the 2 letters or the 3 letters ISO code. It can optionally be followed by the '_' character and the country code (again either as 2 or 3 letters), optionally followed by '_' and the variant.

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the string to convert to a locale, or null.

Returns:

the converted locale, or null if the given value was null or empty, or if an exception was thrown and exception­Occured(…) returned true.

Throws:

Illformed­Locale­Exception - if the given string cannot be converted to a locale.

See Also:

• Locales.parse(String)

toCharset

public Charset toCharset(MarshalContext context,
 String value)
                  throws IllegalCharsetNameException

Converts the given string to a character set. The string can be either a IANA identifier, or one of the ISO 19115:2003 MD_Character­Set­Code identifier.

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the string to convert to a character set, or null.

Returns:

the converted character set, or null if the given value was null or empty, or if an exception was thrown and exception­Occured(…) returned true.

Throws:

Illegal­Charset­Name­Exception - if the given string cannot be converted to a character set.

Since:

0.5

See Also:

• Charset.for­Name(String)

toUnit

public Unit<?> toUnit(MarshalContext context,
 String value)
               throws IllegalArgumentException

Converts the given string to a unit. This method shall accept all the following forms (example for the metre unit):

• m
• EPSG:9001
• urn:ogc:def:uom:epsg::9001
• http://www.opengis.net/def/uom/EPSG/0/9001
• http://www.isotc211.org/2005/resources/uom/gmx­Uom.xml#xpointer(//*[@gml:id='m'])

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the string to convert to a unit, or null.

Returns:

the converted unit, or null if the given value was null or empty, or if an exception was thrown and exception­Occured(…) returned true.

Throws:

Illegal­Argument­Exception - if the given string cannot be converted to a unit.

See Also:

• Units.value­Of(String)

toUUID

public UUID toUUID(MarshalContext context,
 String value)
            throws IllegalArgumentException

Converts the given string to a Universal Unique Identifier. The default implementation is as below, omitting the check for null value and the call to exception­Occured(…) in case of error:

return UUID.fromString(value);

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the string to convert to a UUID, or null.

Returns:

the converted UUID, or null if the given value was null or empty, or if an exception was thrown and exception­Occured(…) returned true.

Throws:

Illegal­Argument­Exception - if the given string cannot be converted to a UUID.

See Also:

• UUID.from­String(String)

toURI

public URI toURI(MarshalContext context,
 String value)
          throws URISyntaxException

Converts the given string to a URI. The default performs the following work (omitting the check for null value and the call to exception­Occured(…) in case of error):

return new URI(value);

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the string to convert to a URI, or null.

Returns:

the converted URI, or null if the given value was null or empty, or if an exception was thrown and exception­Occured(…) returned true.

Throws:

URISyntax­Exception - if the given string cannot be converted to a URI.

See Also:

• URI(String)

toURI

public URI toURI(MarshalContext context,
 URL value)
          throws URISyntaxException

Converts the given URL to a URI. The default implementation is as below, omitting the check for null value and the call to exception­Occured(…) in case of error:

return value.toURI();

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the URL to convert to a URI, or null.

Returns:

the converted URI, or null if the given value was null or if an exception was thrown and exception­Occured(…) returned true.

Throws:

URISyntax­Exception - if the given URL cannot be converted to a URI.

See Also:

• URL.to­URI()

toURL

public URL toURL(MarshalContext context,
 URI value)
          throws MalformedURLException

Converts the given URI to a URL. The default implementation is as below, omitting the check for null value and the call to exception­Occured(…) in case of error:

return value.toURL();

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the URI to convert to a URL, or null.

Returns:

the converted URL, or null if the given value was null or if an exception was thrown and exception­Occured(…) returned true.

Throws:

Malformed­URLException - if the given URI cannot be converted to a URL.

See Also:

• URI.to­URL()

toNilReason

public NilReason toNilReason(MarshalContext context,
 String value)
                      throws URISyntaxException

Converts the given string to a Nil­Reason. The default implementation is as below, omitting the check for null value and the call to exception­Occured(…) in case of error:

return NilReason.valueOf(value);

Parameters:

context - context (GML version, locale, etc.) of the (un)marshalling process.

value - the string to convert to a nil reason, or null.

Returns:

the converted nil reason, or null if the given value was null or empty, or if an exception was thrown and exception­Occured(…) returned true.

Throws:

URISyntax­Exception - if the given string cannot be converted to a nil reason.

See Also:

• Nil­Reason.value­Of(String)