Package org.apache.sis.xml

## Class NilReason

- Object
- - NilReason

- All Implemented Interfaces:
    `Serializable`

      public final class NilReason
      extends Object
      implements Serializable

  Explanation for a missing XML element. The nil reason can be parsed and formatted as a string using the `valueOf(String)` and `toString()` methods respectively. The string can be either a `URI` or an enumeration value described below. More specifically, `NilReason` can be:
  - One of the predefined `INAPPLICABLE`, `MISSING`, `TEMPLATE`, `UNKNOWN` or `WITHHELD` enumeration values.
  - The `OTHER` enumeration value, or a new enumeration value formatted as `"other:"` concatenated with a brief textual explanation.
  - A URI which should refer to a resource which describes the reason for the exception.
  `NilReason` is used in a number of XML elements where it is necessary to permit one of the above values as an alternative to the primary element.
  Immutability and thread safety
  This final class is immutable and thus inherently thread-safe.
  Since:
    0.3
  See Also:
    `NilObject`, Serialized Form

  Defined in the `sis-metadata` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static NilReason` | `INAPPLICABLE` | There is no value.
    `static NilReason` | `MISSING` | The correct value is not readily available to the sender of this data.
    `static NilReason` | `OTHER` | Other reason without explanation.
    `static NilReason` | `TEMPLATE` | The value will be available later.
    `static NilReason` | `UNKNOWN` | The correct value is not known to, and not computable by, the sender of this data.
    `static NilReason` | `WITHHELD` | The value is not divulged.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `<T> T` | `createNilObject​(Class<T> type)` | Returns an object of the given type which is nil for the reason represented by this instance.
    `boolean` | `equals​(Object other)` | Compares this `NilReason` with the specified object for equality.
    `static NilReason` | `forObject​(Object object)` | If the given object is nil, returns the reason why it does not contain information.
    `String` | `getOtherExplanation()` | If this `NilReason` is an enumeration of kind `OTHER`, returns the explanation text.
    `URI` | `getURI()` | If the explanation of this `NilReason` is referenced by a URI, returns that URI.
    `int` | `hashCode()` | Returns a hash code value for this `NilReason`.
    `String` | `toString()` | Returns the GML string representation of this `NilReason`.
    `static NilReason` | `valueOf​(String reason)` | Parses the given nil reason.
    `static NilReason[]` | `values()` | Returns an array containing every instances of this type that have not yet been garbage collected.

    - ### Methods inherited from class Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### INAPPLICABLE

          public static final NilReason INAPPLICABLE

      There is no value.

      The string representation is `"inapplicable"`. Other properties (explanation and URI) are `null`.

    - #### MISSING

          public static final NilReason MISSING

      The correct value is not readily available to the sender of this data. Furthermore, a correct value may not exist.

      The string representation is `"missing"`. Other properties (explanation and URI) are `null`.

    - #### TEMPLATE

          public static final NilReason TEMPLATE

      The value will be available later.

      The string representation is `"template"`. Other properties (explanation and URI) are `null`.

    - #### UNKNOWN

          public static final NilReason UNKNOWN

      The correct value is not known to, and not computable by, the sender of this data. However, a correct value probably exists.

      The string representation is `"unknown"`. Other properties (explanation and URI) are `null`.

    - #### WITHHELD

          public static final NilReason WITHHELD

      The value is not divulged.

      The string representation is `"withheld"`. Other properties (explanation and URI) are `null`.

    - #### OTHER

          public static final NilReason OTHER

      Other reason without explanation. The string representation of this constant is `"other"`. The explanation property is an empty string, and the URI is `null`.
      Providing an explanation
      Users are encouraged to use the `valueOf(String)` method instead than this constant, in order to provide a brief explanation. The string representation for `valueOf(…)` is `"other:explanation"` where explanation is a string of two or more characters with no included spaces.

      When testing if a `NilReason` instance is any kind of `"other"` reason, users should test if `getOtherExplanation() != null` instead than comparing the reference against this constant.

  - ### Method Detail

    - #### values

          public static NilReason[] values()

      Returns an array containing every instances of this type that have not yet been garbage collected. The first elements of the returned array are the constants defined in this class, in declaration order. All other elements are the instances created by the `valueOf(String)` method, in no particular order.
      Returns:
        an array containing the instances of `NilReason`.

    - #### valueOf

          public static NilReason valueOf​(String reason)
                                   throws URISyntaxException

      Parses the given nil reason. This method accepts the following cases:
      - If the given argument is one of the `"inapplicable"`, `"missing"`, `"template"`, `"unknown"`, `"withheld"` or `"other"` strings (ignoring cases and leading/trailing spaces), then the corresponding pre-defined constant is returned.
      - Otherwise if the given argument is `"other:"` followed by an explanation text, then an instance for that explanation is returned. More specifically:
        - Space characters and ISO controls are silently omitted.
        - If the remaining string has less than two characters, then the `OTHER` constant is returned.
      - Otherwise this method attempts to parse the given argument as a `URI`. Such URI should refer to a resource which describes the reason for the exception.
      This method returns existing instances when possible.
      Parameters:
        `reason` - the reason why an element is not present.
      Returns:
        the reason as a `NilReason` object.
      Throws:
        `URISyntaxException` - if the given string is not one of the predefined enumeration values and can not be parsed as a URI.

    - #### getOtherExplanation

          public String getOtherExplanation()

      If this `NilReason` is an enumeration of kind `OTHER`, returns the explanation text. Otherwise returns `null`. If non-null, then the explanation is a string without whitespace.

      Note that in the special case where `this` nil reason is the `OTHER` instance itself, then this method returns an empty string. For all other cases, the string contains at least two characters.

      Returns:
        the explanation, or `null` if this `NilReason` is not of kind `OTHER`.

    - #### getURI

          public URI getURI()

      If the explanation of this `NilReason` is referenced by a URI, returns that URI. Otherwise returns `null`. The URI and the other explanation attributes are mutually exclusive.
      Returns:
        the URI, or `null` if the explanation of this `NilReason` is not referenced by a URI.

    - #### toString

          public String toString()

      Returns the GML string representation of this `NilReason`. The returned string is a simple enumeration value (e.g. `"inapplicable"`) if this `NilReason` is one of the predefined constants, or a string of the form `"other:explanation"`, or a URI.
      Overrides:
        `toString` in class `Object`
      Returns:
        the GML string representation of this `NilReason`.

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this `NilReason`.
      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals​(Object other)

      Compares this `NilReason` with the specified object for equality.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `other` - the object to compare with this `NilReason`.

    - #### createNilObject

          public <T> T createNilObject​(Class<T> type)

      Returns an object of the given type which is nil for the reason represented by this instance. The `type` argument can be one of the following cases:
      - An interface: in such case, this method returns an object which implement the given interface together with the `NilObject` and `LenientComparable` interfaces:
        - The `NilObject​.getNilReason()` method will return this `NilReason` instance.
        - The `equals(…)` and `hashCode()` methods behave as documented in `LenientComparable`.
        - The `toString()` method is unspecified (may contain debugging information).
        - All other methods return an empty collections, empty arrays, `null`, `NaN`, `0` or `false`, in this preference order, depending on the method return type.
      - One of `Boolean`, `Byte`, `Short`, `Integer`, `Long`, `Float`, `Double` or `String` types: in such case, this method returns a specific instance which will be recognized as "nil" by the XML marshaller.
      Type Parameters:
        `T` - the compile-time type of the `type` argument.
      Parameters:
        `type` - the object type as an interface (usually a GeoAPI one) or one of the special types.
      Returns:
        an `NilObject` of the given type.
      Throws:
        `IllegalArgumentException` - if the given type is not a supported type.

    - #### forObject

          public static NilReason forObject​(Object object)

      If the given object is nil, returns the reason why it does not contain information. This method performs the following choices:
      - If the given object implements the `NilObject` interface, then this method delegates to the `NilObject​.getNilReason()` method.
      - Otherwise if the given object is one of the `Boolean`, `Byte`, `Short`, `Integer`, `Long`, `Float`, `Double` or `String` instances returned by `createNilObject(Class)`, then this method returns the associated reason.
      - Otherwise this method returns `null`.
      Parameters:
        `object` - the object for which to get the `NilReason`, or `null`.
      Returns:
        the reason why the given object contains no information, or `null` if the given object is not nil.
      Since:
        0.4
      See Also:
        `NilObject​.getNilReason()`