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
(
NilReason#UNKNOWN), the information may not exist at all (
NilReason#MISSING) or can not be divulged (
NilReason#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 |
xml |
xml |
If the
CI_Series element was completely omitted, then
org.opengis.metadata.citation.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:
java