Package org.apache.sis.xml

## Interface NilObject

-     public interface NilObject

  A marker interface for nil XML elements providing an explanation about why the information is absent. GeoAPI getter methods usually return a `null` value when no information is available for a given attribute. However it is possible to specify why an information is absent, in which case the corresponding getter method will rather return an instance of this `NilObject` interface. The information may be absent for various reasons, including the attribute being inapplicable in the metadata context (`NilReason​.INAPPLICABLE`), the information probably exists but is unknown to the data provider (`UNKNOW`), the information may not exist at all (`MISSING`) or can not be divulged (`WITHHELD`).

  Nil objects appear most frequently in XML documents because if a mandatory ISO 19115-1 attribute is absent, then the ISO 19115-3 standard requires us to said why it is absent. The following example shows a `CI_Citation` fragment with an ordinary `CI_Series` element on the left side, and an unknown `CI_Series` element on the right side:

  Example of missing object
  Normal `Series` element | Unknown `Series` element
  --- | ---
  >     <cit:CI_Citation>
  >       <cit:series>
  >         <cit:CI_Series>
  >           <!-- Some content here -->
  >         </cit:CI_Series>
  >       </cit:series>
  >     </cit:CI_Citation>
  >     <cit:CI_Citation>
  >       <cit:series nilReason="unknown"/>
  >     </cit:CI_Citation>

  If the `CI_Series` element was completely omitted, then `Citation​.getSeries()` method would return `null` in Apache SIS implementation. But since a `nilReason` is provided, then the SIS implementation of `getSeries()` will rather return an object which implement both the `Series` and the `NilObject` interfaces, and the `getNilReason()` method on that instance will return the `NilReason​.UNKNOWN` constant.
  Instantiation
  Instances of `NilObject` are created by first fetching the reason why the information is missing, then invoking `NilReason​.createNilObject(Class)`. The following example instantiates a `Citation` object which is nil because the information are missing:

  >     Citation nil = NilReason.MISSING.createNilObject(Citation.class);

  Since:
    0.3
  See Also:
    `NilReason​.createNilObject(Class)`, `Numbers​.valueOfNil(Class)`

  Defined in the `sis-metadata` module

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `NilReason` | `getNilReason()` | Returns the reason why this object contains no information.

- - ### Method Detail

    - #### getNilReason

          NilReason getNilReason()

      Returns the reason why this object contains no information.
      Returns:
        the reason why this object contains no information.
      See Also:
        `NilReason​.forObject(Object)`