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

  Modifier and Type
  Method
  Description
  `NilReason`
  `getNilReason()`
  Returns the reason why this object contains no information.

- ## Method Details

  - ### 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)`