Class NilReason

  • All Implemented Interfaces:
    Serializable

    public final class NilReason
    extends Object
    implements Serializable
    Explanation for a missing XML element. The nil reason can be parsed and formatted as a string using the value­Of(String) and to­String() methods respectively. The string can be either a URI or an enumeration value described below. More specifically, Nil­Reason can be:
    • One of the predefined INAPPLICABLE, MISSING, TEMPLATE, UNKNOWN or WITHHELD enumeration values.
    • The OTHER enumeration value, or a new enumeration value formatted as "other:" concatenated with a brief textual explanation.
    • A URI which should refer to a resource which describes the reason for the exception.
    Nil­Reason is used in a number of XML elements where it is necessary to permit one of the above values as an alternative to the primary element.
    Immutability and thread safety
    This final class is immutable and thus inherently thread-safe.
    Since:
    0.3
    See Also:
    Nil­Object, Serialized Form

    Defined in the sis-metadata module

    • Field Detail

      • INAPPLICABLE

        public static final NilReason INAPPLICABLE
        There is no value.

        The string representation is "inapplicable". Other properties (explanation and URI) are null.

      • MISSING

        public static final NilReason MISSING
        The correct value is not readily available to the sender of this data. Furthermore, a correct value may not exist.

        The string representation is "missing". Other properties (explanation and URI) are null.

      • TEMPLATE

        public static final NilReason TEMPLATE
        The value will be available later.

        The string representation is "template". Other properties (explanation and URI) are null.

      • UNKNOWN

        public static final NilReason UNKNOWN
        The correct value is not known to, and not computable by, the sender of this data. However, a correct value probably exists.

        The string representation is "unknown". Other properties (explanation and URI) are null.

      • WITHHELD

        public static final NilReason WITHHELD
        The value is not divulged.

        The string representation is "withheld". Other properties (explanation and URI) are null.

      • OTHER

        public static final NilReason OTHER
        Other reason without explanation. The string representation of this constant is "other". The explanation property is an empty string, and the URI is null.
        Providing an explanation
        Users are encouraged to use the value­Of(String) method instead than this constant, in order to provide a brief explanation. The string representation for value­Of(…) is "other:explanation" where explanation is a string of two or more characters with no included spaces.

        When testing if a Nil­Reason instance is any kind of "other" reason, users should test if get­Other­Explanation() != null instead than comparing the reference against this constant.

    • Method Detail

      • values

        public static NilReason[] values()
        Returns an array containing every instances of this type that have not yet been garbage collected. The first elements of the returned array are the constants defined in this class, in declaration order. All other elements are the instances created by the value­Of(String) method, in no particular order.
        Returns:
        an array containing the instances of Nil­Reason.
      • valueOf

        public static NilReason valueOf​(String reason)
                                 throws URISyntaxException
        Parses the given nil reason. This method accepts the following cases:
        • If the given argument is one of the "inapplicable", "missing", "template", "unknown", "withheld" or "other" strings (ignoring cases and leading/trailing spaces), then the corresponding pre-defined constant is returned.
        • Otherwise if the given argument is "other:" followed by an explanation text, then an instance for that explanation is returned. More specifically:
        • Otherwise this method attempts to parse the given argument as a URI. Such URI should refer to a resource which describes the reason for the exception.
        This method returns existing instances when possible.
        Parameters:
        reason - the reason why an element is not present.
        Returns:
        the reason as a Nil­Reason object.
        Throws:
        URISyntax­Exception - if the given string is not one of the predefined enumeration values and can not be parsed as a URI.
      • getOtherExplanation

        public String getOtherExplanation()
        If this Nil­Reason is an enumeration of kind OTHER, returns the explanation text. Otherwise returns null. If non-null, then the explanation is a string without whitespace.

        Note that in the special case where this nil reason is the OTHER instance itself, then this method returns an empty string. For all other cases, the string contains at least two characters.

        Returns:
        the explanation, or null if this Nil­Reason is not of kind OTHER.
      • getURI

        public URI getURI()
        If the explanation of this Nil­Reason is referenced by a URI, returns that URI. Otherwise returns null. The URI and the other explanation attributes are mutually exclusive.
        Returns:
        the URI, or null if the explanation of this Nil­Reason is not referenced by a URI.
      • toString

        public String toString()
        Returns the GML string representation of this Nil­Reason. The returned string is a simple enumeration value (e.g. "inapplicable") if this Nil­Reason is one of the predefined constants, or a string of the form "other:explanation", or a URI.
        Overrides:
        to­String in class Object
        Returns:
        the GML string representation of this Nil­Reason.
      • hashCode

        public int hashCode()
        Returns a hash code value for this Nil­Reason.
        Overrides:
        hash­Code in class Object
      • equals

        public boolean equals​(Object other)
        Compares this Nil­Reason with the specified object for equality.
        Overrides:
        equals in class Object
        Parameters:
        other - the object to compare with this Nil­Reason.
      • createNilObject

        public <T> T createNilObject​(Class<T> type)
        Returns an object of the given type which is nil for the reason represented by this instance. The type argument can be one of the following cases:
        • An interface: in such case, this method returns an object which implement the given interface together with the Nil­Object and Lenient­Comparable interfaces:
          • The Nil­Object​.get­Nil­Reason() method will return this Nil­Reason instance.
          • The equals(…) and hash­Code() methods behave as documented in Lenient­Comparable.
          • The to­String() method is unspecified (may contain debugging information).
          • All other methods return an empty collections, empty arrays, null, Na­N, 0 or false, in this preference order, depending on the method return type.
        • One of Boolean, Byte, Short, Integer, Long, Float, Double or String types: in such case, this method returns a specific instance which will be recognized as "nil" by the XML marshaller.
        Type Parameters:
        T - the compile-time type of the type argument.
        Parameters:
        type - the object type as an interface (usually a GeoAPI one) or one of the special types.
        Returns:
        an Nil­Object of the given type.
        Throws:
        Illegal­Argument­Exception - if the given type is not a supported type.
      • forObject

        public static NilReason forObject​(Object object)
        If the given object is nil, returns the reason why it does not contain information. This method performs the following choices:
        Parameters:
        object - the object for which to get the Nil­Reason, or null.
        Returns:
        the reason why the given object contains no information, or null if the given object is not nil.
        Since:
        0.4
        See Also:
        Nil­Object​.get­Nil­Reason()