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 Nil­Object interface. The information may be absent for various reasons, including the attribute being inapplicable in the metadata context (Nil­Reason.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.get­Series() method would return null in Apache SIS implementation. But since a nil­Reason is provided, then the SIS implementation of get­Series() will rather return an object which implement both the Series and the Nil­Object interfaces, and the get­Nil­Reason() method on that instance will return the Nil­Reason.UNKNOWN constant.

Instantiation

Instances of Nil­Object are created by first fetching the reason why the information is missing, then invoking Nil­Reason.create­Nil­Object(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:

Nil­Reason.create­Nil­Object(Class), Numbers.value­Of­Nil(Class)

Defined in the sis-utility module

Method Summary

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:

Nil­Reason.for­Object(Object)