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

Defined in the sis-metadata module

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