public class ValueConverter extends Object
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 custom
ValueConverter
to a (un)marshaller.Defined in the sis-utility module
Modifier and Type | Field and Description |
---|---|
static ValueConverter |
DEFAULT
The default, thread-safe and immutable instance.
|
Modifier | Constructor and Description |
---|---|
protected |
ValueConverter()
Creates a default
ValueConverter . |
Modifier and Type | Method and Description |
---|---|
protected <T> boolean |
exceptionOccured(MarshalContext context,
T value,
Class<T> sourceType,
Class<?> targetType,
Exception exception)
Invoked when an exception occurred in any
toXXX(…) method. |
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 a
NilReason . |
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.
|
public static final ValueConverter DEFAULT
ValueConverter
was explicitly set.protected ValueConverter()
ValueConverter
. This is for subclasses only,
since new instances are useful only if at least one method is overridden.protected <T> boolean exceptionOccured(MarshalContext context, T value, Class<T> sourceType, Class<?> targetType, Exception exception)
toXXX(…)
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
toXXX(…)
methods, like the example provided in this class
javadoc.
T
- The compile-time type of the sourceType
argument.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 always
URI.class
if the exception has been caught by the toURL(MarshalContext, URI)
method.targetType
- The expected type of the converted object.exception
- The exception that occurred during the conversion attempt.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.public String toLanguageCode(MarshalContext context, Locale value) throws MissingResourceException
Locale.getISO3Language()
.
However those codes may not be available for every locales.
The default implementation performs the following step:
value.getISO3Language()
:null
otherwise.exceptionOccured(…)
return true
, then
returns value.getLanguage()
if non-empty or null
otherwise.exceptionOccured(…)
returned false
(which is the default
behavior), then let the exception propagate.context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The locale to convert to a language code, or null
.null
if the given value was null or does not contains
a language code.MissingResourceException
- If there is no ISO 3-letters language code for the given locale.Locale.getISO3Language()
,
Locale.getLanguage()
public String toCountryCode(MarshalContext context, Locale value) throws MissingResourceException
Locale.getISO3Country()
.
However those codes may not be available for every locales.
The default implementation performs the following step:
value.getISO3Country()
:null
otherwise.exceptionOccured(…)
return true
, then
returns value.getCountry()
if non-empty or null
otherwise.exceptionOccured(…)
returned false
(which is the default
behavior), then let the exception propagate.context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The locale to convert to a country code, or null
.null
if the given value was null or does not contains
a country code.MissingResourceException
- If there is no ISO 3-letters country code for the given locale.Locale.getISO3Country()
,
Locale.getCountry()
public Locale toLocale(MarshalContext context, String value) throws IllegalArgumentException
'_'
character and the country code (again either as 2 or 3 letters), optionally followed
by '_'
and the variant.context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The string to convert to a locale, or null
.null
if the given value was null or empty, or
if an exception was thrown and exceptionOccured(…)
returned true
.IllegalArgumentException
- If the given string can not be converted to a locale.public Unit<?> toUnit(MarshalContext context, String value) throws IllegalArgumentException
exceptionOccured(…)
in case of error:
return Units.valueOf(value);
context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The string to convert to a unit, or null
.null
if the given value was null or empty, or
if an exception was thrown and exceptionOccured(…)
returned true
.IllegalArgumentException
- If the given string can not be converted to a unit.Units.valueOf(String)
public UUID toUUID(MarshalContext context, String value) throws IllegalArgumentException
exceptionOccured(…)
in case of error:
return UUID.fromString(value);
context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The string to convert to a UUID, or null
.null
if the given value was null or empty, or
if an exception was thrown and exceptionOccured(…)
returned true
.IllegalArgumentException
- If the given string can not be converted to a UUID.UUID.fromString(String)
public URI toURI(MarshalContext context, String value) throws URISyntaxException
exceptionOccured(…)
in case of error):
return new URI(value);
context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The string to convert to a URI, or null
.null
if the given value was null or empty, or if
an exception was thrown and exceptionOccured(…)
returned true
.URISyntaxException
- If the given string can not be converted to a URI.URI.URI(String)
public URI toURI(MarshalContext context, URL value) throws URISyntaxException
exceptionOccured(…)
in case of error:
return value.toURI();
context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The URL to convert to a URI, or null
.null
if the given value was null or if an
exception was thrown and exceptionOccured(…)
returned true
.URISyntaxException
- If the given URL can not be converted to a URI.URL.toURI()
public URL toURL(MarshalContext context, URI value) throws MalformedURLException
exceptionOccured(…)
in case of error:
return value.toURL();
context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The URI to convert to a URL, or null
.null
if the given value was null or if an
exception was thrown and exceptionOccured(…)
returned true
.MalformedURLException
- If the given URI can not be converted to a URL.URI.toURL()
public NilReason toNilReason(MarshalContext context, String value) throws URISyntaxException
NilReason
. The default implementation is as below,
omitting the check for null value and the call to exceptionOccured(…)
in case of error:
return NilReason.valueOf(value);
context
- Context (GML version, locale, etc.) of the (un)marshalling process.value
- The string to convert to a nil reason, or null
.null
if the given value was null or empty, or
if an exception was thrown and exceptionOccured(…)
returned true
.URISyntaxException
- If the given string can not be converted to a nil reason.NilReason.valueOf(String)
Copyright © 2010–2013 The Apache Software Foundation. All rights reserved.