Class 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

    Defined in the sis-metadata module

    • 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 no Value­Converter was explicitly set.
    • Constructor Detail

      • 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 Detail

      • 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 can't 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()
      • 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
        IANAISO 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
        IANAISO 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 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: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 can not 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. The default implementation is as below, omitting the check for null value and the call to exception­Occured(…) 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, 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 can not 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 can not 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 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 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 can not 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 can not 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 can not be converted to a nil reason.
        See Also:
        Nil­Reason​.value­Of(String)