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 since if a mandatory ISO 19115 attribute is absent, then the ISO 19139 standard requires us to said why it is so. 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
  --- | ---
      <gmd:CI_Citation>
        <gmd:series>
          <gmd:CI_Series>
            <!-- Some content here -->
          </gmd:CI_Series>
        </gmd:series>
      </gmd:CI_Citation>
      <gmd:CI_Citation>
        <gmd:series nilReason="unknown"/>
      </gmd: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-utility` module

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and 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)`

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.