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
MalformedURLException
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:
See theclass 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; } } } }
XML.CONVERTER
javadoc for an example of registering a customValueConverter
to a (un)marshaller.- Since:
- 0.3
Defined in the
sis-metadata
module
-
-
Field Summary
Fields Modifier and Type Field Description static ValueConverter
DEFAULT
The default, thread-safe and immutable instance.
-
Constructor Summary
Constructors Modifier Constructor Description protected
ValueConverter()
Creates a defaultValueConverter
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected <T> boolean
exceptionOccured(MarshalContext context, T value, Class<T> sourceType, Class<?> targetType, Exception exception)
Invoked when an exception occurred in anytoXXX(…)
method.Charset
toCharset(MarshalContext context, String value)
Converts the given string to a character set.String
toCharsetCode(MarshalContext context, Charset value)
Converts the given character set to a code.String
toCountryCode(MarshalContext context, Locale value)
Converts the given locale to a country code.String
toLanguageCode(MarshalContext context, Locale value)
Converts the given locale to a language code.Locale
toLocale(MarshalContext context, String value)
Converts the given string to a locale.NilReason
toNilReason(MarshalContext context, String value)
Converts the given string to aNilReason
.Unit<?>
toUnit(MarshalContext context, String value)
Converts the given string to a unit.URI
toURI(MarshalContext context, String value)
Converts the given string to a URI.URI
toURI(MarshalContext context, URL value)
Converts the given URL to a URI.URL
toURL(MarshalContext context, URI value)
Converts the given URI to a URL.UUID
toUUID(MarshalContext context, String value)
Converts the given string to a Universal Unique Identifier.
-
-
-
Field Detail
-
DEFAULT
public static final ValueConverter DEFAULT
The default, thread-safe and immutable instance. This instance defines the converters used during every (un)marshalling if noValueConverter
was explicitly set.
-
-
Method Detail
-
exceptionOccured
protected <T> boolean exceptionOccured(MarshalContext context, T value, Class<T> sourceType, Class<?> targetType, Exception exception)
Invoked when an exception occurred in anytoXXX(…)
method. The default implementation does nothing and returnfalse
, 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 individualtoXXX(…)
methods, like the example provided in this class javadoc.- Type Parameters:
T
- the compile-time type of thesourceType
argument.- Parameters:
context
- context (GML version, locale, etc.) of the (un)marshalling process.value
- the value that can't be converted.sourceType
- 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 alwaysURI.class
if the exception has been caught by thetoURL(MarshalContext, URI)
method.targetType
- 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, orfalse
(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.getISO3Language()
:- On success, return that value if non-empty, or
null
otherwise. - If an exception has been thrown, then:
- If
exceptionOccured(…)
returntrue
, then returnsvalue.getLanguage()
if non-empty ornull
otherwise. - If
exceptionOccured(…)
returnedfalse
(which is the default behavior), then let the exception propagate.
- If
- On success, return that value if non-empty, or
- Parameters:
context
- context (GML version, locale, etc.) of the (un)marshalling process.value
- the locale to convert to a language code, ornull
.- Returns:
- the language code, or
null
if the given value was null or does not contains a language code. - Throws:
MissingResourceException
- if no language code can be found for the given locale.- See Also:
Locale.getISO3Language()
,Locale.getLanguage()
- Try
-
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.getCountry()
if non-empty, ornull
otherwise.- Parameters:
context
- context (GML version, locale, etc.) of the (un)marshalling process.value
- the locale to convert to a country code, ornull
.- Returns:
- the country code, or
null
if the given value was null or does not contains a country code. - Throws:
MissingResourceException
- if no country code can be found for the given locale.- See Also:
Locale.getISO3Country()
,Locale.getCountry()
-
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:2003MD_CharacterSetCode
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, ornull
.- 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, ornull
.- Returns:
- the converted locale, or
null
if the given value was null or empty, or if an exception was thrown andexceptionOccured(…)
returnedtrue
. - Throws:
IllformedLocaleException
- if the given string can not 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:2003MD_CharacterSetCode
identifier.- Parameters:
context
- context (GML version, locale, etc.) of the (un)marshalling process.value
- the string to convert to a character set, ornull
.- Returns:
- the converted character set, or
null
if the given value was null or empty, or if an exception was thrown andexceptionOccured(…)
returnedtrue
. - Throws:
IllegalCharsetNameException
- if the given string can not be converted to a character set.- Since:
- 0.5
- See Also:
Charset.forName(String)
-
toUnit
public Unit<?> toUnit(MarshalContext context, String value) throws IllegalArgumentException
Converts the given string to a unit. The default implementation is as below, omitting the check for null value and the call toexceptionOccured(…)
in case of error:return Units.valueOf(value);
- Parameters:
context
- context (GML version, locale, etc.) of the (un)marshalling process.value
- the string to convert to a unit, ornull
.- Returns:
- the converted unit, or
null
if the given value was null or empty, or if an exception was thrown andexceptionOccured(…)
returnedtrue
. - Throws:
IllegalArgumentException
- if the given string can not be converted to a unit.- See Also:
Units.valueOf(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 toexceptionOccured(…)
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, ornull
.- Returns:
- the converted UUID, or
null
if the given value was null or empty, or if an exception was thrown andexceptionOccured(…)
returnedtrue
. - Throws:
IllegalArgumentException
- if the given string can not be converted to a UUID.- See Also:
UUID.fromString(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 toexceptionOccured(…)
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, ornull
.- Returns:
- the converted URI, or
null
if the given value was null or empty, or if an exception was thrown andexceptionOccured(…)
returnedtrue
. - Throws:
URISyntaxException
- if the given string can not 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 toexceptionOccured(…)
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, ornull
.- Returns:
- the converted URI, or
null
if the given value was null or if an exception was thrown andexceptionOccured(…)
returnedtrue
. - Throws:
URISyntaxException
- if the given URL can not be converted to a URI.- See Also:
URL.toURI()
-
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 toexceptionOccured(…)
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, ornull
.- Returns:
- the converted URL, or
null
if the given value was null or if an exception was thrown andexceptionOccured(…)
returnedtrue
. - Throws:
MalformedURLException
- if the given URI can not be converted to a URL.- See Also:
URI.toURL()
-
toNilReason
public NilReason toNilReason(MarshalContext context, String value) throws URISyntaxException
Converts the given string to aNilReason
. The default implementation is as below, omitting the check for null value and the call toexceptionOccured(…)
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, ornull
.- Returns:
- the converted nil reason, or
null
if the given value was null or empty, or if an exception was thrown andexceptionOccured(…)
returnedtrue
. - Throws:
URISyntaxException
- if the given string can not be converted to a nil reason.- See Also:
NilReason.valueOf(String)
-
-