org.geotoolkit.xml
Class ObjectConverters

Object
  ObjectConverters

public class ObjectConverters
extends Object

Performs conversions of objects 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:

class URLFixer extends ObjectConverters {
    public URL toURL(URI uri) throws MalformedURLException {
        try {
            return super.toURL(uri);
        } catch (MalformedURLException e) {
            if (uri.equals(KNOWN_ERRONEOUS_URI) {
                return FIXED_URL;
            } else {
                throw e;
            }
        }
    }
}

See the XML.CONVERTERS javadoc for an example of registering a custom ObjectConverters to a (un)marshaller.

Since:

3.07

Version:

3.18

Author:

Martin Desruisseaux (Geomatys)

Module:

utility/geotk-xml-base (download)

View source code for this class

Field Summary

static ObjectConverters

DEFAULT The default, thread-safe and immutable instance.

Constructor Summary

protected

ObjectConverters() Creates a default ObjectConverters.

Method Summary

protected <T> boolean	exceptionOccured(T value, Class<T> sourceType, Class<?> targetType, Exception exception) Invoked when an exception occurred in any toXXX(...) method.
Locale	toLocale(String value) Converts the given string to a locale.
NilReason	toNilReason(String value) Converts the given string to a NilReason.
Unit<?>	toUnit(String value) Converts the given string to a unit.
URI	toURI(String value) Converts the given string to a URI.
URI	toURI(URL value) Converts the given URL to a URI.
URL	toURL(URI value) Converts the given URI to a URL.
UUID	toUUID(String value) Converts the given string to a Universal Unique Identifier.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT

public static final ObjectConverters DEFAULT

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

Constructor Detail

ObjectConverters

protected ObjectConverters()

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

Method Detail

exceptionOccured

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

Invoked when an exception occurred in any 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.CONVERTERS javadoc. Subclasses also have the possibility to override individual toXXX(...) methods, like the example provided in this class javadoc.

Type Parameters:

T - The compile-time type of the sourceType argument.

Parameters:

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(URI) method.

targetType - The expected type of the converted object.

exception - The exception that occurred during the attempt to convert.

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.

toLocale

public Locale toLocale(String value)
                throws IllegalArgumentException

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:

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

Returns:

The converted locale, or null if the given value was null of if an exception was thrown and exceptionOccured returned true.

Throws:

IllegalArgumentException - If the given string can not be converted to a locale.

Since:

3.17

toUnit

public Unit<?> toUnit(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 to exceptionOccured in case of error:

return Units.valueOf(value);

Parameters:

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

Returns:

The converted unit, or null if the given value was null of if an exception was thrown and exceptionOccured returned true.

Throws:

IllegalArgumentException - If the given string can not be converted to a unit.

See Also:

Units.valueOf(String)

toUUID

public UUID toUUID(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 exceptionOccured in case of error:

return UUID.fromString(value);

Parameters:

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

Returns:

The converted UUID, or null if the given value was null of if an exception was thrown and exceptionOccured returned true.

Throws:

IllegalArgumentException - If the given string can not be converted to a UUID.

Since:

3.13

See Also:

UUID.fromString(String)

toURI

public URI toURI(String value)
          throws URISyntaxException

Converts the given string to a URI. The default implementation first escapes the characters that the URI(String) constructor would not accept (for example replacing space by %20), then performs the following work (omitting the check for null value and the call to exceptionOccured in case of error):

return new URI(escapedValue);

Parameters:

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

Returns:

The converted URI, or null if the given value was null of if an exception was thrown and exceptionOccured returned true.

Throws:

URISyntaxException - If the given string can not be converted to a URI.

See Also:

URI.URI(String)

toURI

public URI toURI(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 exceptionOccured in case of error:

return value.toURI();

Parameters:

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

Returns:

The converted URI, or null if the given value was null of if an exception was thrown and exceptionOccured returned true.

Throws:

URISyntaxException - If the given URL can not be converted to a URI.

See Also:

URL.toURI()

toURL

public URL toURL(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 exceptionOccured in case of error:

return value.toURL();

Parameters:

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

Returns:

The converted URL, or null if the given value was null of if an exception was thrown and exceptionOccured returned true.

Throws:

MalformedURLException - If the given URI can not be converted to a URL.

See Also:

URI.toURL()

toNilReason

public NilReason toNilReason(String value)
                      throws URISyntaxException

Converts the given string to a 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);

Parameters:

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

Returns:

The converted nil reason, or null if the given value was null of if an exception was thrown and exceptionOccured returned true.

Throws:

URISyntaxException - If the given string can not be converted to a nil reason.

Since:

3.18

See Also:

NilReason.valueOf(String)