Package org.apache.sis.xml

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

  >     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 `ValueConverter` 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 default `ValueConverter`.

  - ### 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 any `toXXX(…)` 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 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.

    - ### Methods inherited from class Object

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

- - ### 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 `ValueConverter` was explicitly set.

  - ### Constructor Detail

    - #### ValueConverter

          protected ValueConverter()

      Creates a default `ValueConverter`. 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 `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.

      Type Parameters:
        `T` - the compile-time type of the `sourceType` 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 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.
      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​.getISO3Language()`:
        - On success, return that value if non-empty, or `null` otherwise.
        - If an exception has been thrown, then:
          - If `exceptionOccured(…)` return `true`, then returns `value​.getLanguage()` if non-empty or `null` otherwise.
          - If `exceptionOccured(…)` 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:
        `MissingResourceException` - if no language code can be found for the given locale.
      See Also:
        `Locale​.getISO3Language()`, `Locale​.getLanguage()`

    - #### 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, 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:
        `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:2003 `MD_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, 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 `exceptionOccured(…)` returned `true`.
      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:2003 `MD_CharacterSetCode` 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 `exceptionOccured(…)` returned `true`.
      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 to `exceptionOccured(…)` 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 `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​(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 `exceptionOccured(…)` 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 `exceptionOccured(…)` returned `true`.
      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 to `exceptionOccured(…)` 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 `exceptionOccured(…)` returned `true`.
      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 to `exceptionOccured(…)` 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 `exceptionOccured(…)` returned `true`.
      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 to `exceptionOccured(…)` 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 `exceptionOccured(…)` returned `true`.
      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 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:
        `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 `exceptionOccured(…)` returned `true`.
      Throws:
        `URISyntaxException` - if the given string can not be converted to a nil reason.
      See Also:
        `NilReason​.valueOf(String)`