Package org.apache.sis.xml

Class NilReason

java.lang.Object
org.apache.sis.xml.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 valueOf(String) and toString() methods respectively. The string can be either a URI or an enumeration value described below. More specifically, NilReason 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.
NilReason 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
Version:
0.4
See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:

    • 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

      private static final String other
      The "other" string.
      See Also:

    • 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 valueOf(String) method instead of this constant, in order to provide a brief explanation. The string representation for valueOf(…) is "other:explanation" where explanation is a string of two or more characters with no included spaces.

      When testing if a NilReason instance is any kind of "other" reason, users should test if getOtherExplanation() != null instead than comparing the reference against this constant.

    • PREDEFINED

      private static final NilReason[] PREDEFINED
      List of predefined constants.

    • POOL

      private static final WeakHashSet<NilReason> POOL
      The pool of other nil reasons created up to date.

    • reason

      private final Object reason
      Either the XML value as a String (including the explanation if the prefix is "other", or a URI.

    • handler

      private transient InvocationHandler handler
      The invocation handler for NilObject instances, created when first needed. The same handler can be shared for all objects having the same NilReason, no matter the interface they implement.

    • nilObjects

      private transient Map<Class<?>,Object> nilObjects
      The values created by createNilObject(Class). They are often instances of NilObject, except for some JDK types like String, Boolean or Integer which are handled in a special way.

  • Constructor Details

    • NilReason

      private NilReason(Object reason)
      Creates a new reason for the given XML value or the given URI.

  • Method Details

    • 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 valueOf(String) method, in no particular order.
      Returns:
      an array containing the instances of NilReason.

    • 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 predefined 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 NilReason object.
      Throws:
      URISyntaxException - if the given string is not one of the predefined enumeration values and cannot be parsed as a URI.

    • readResolve

      private Object readResolve() throws ObjectStreamException
      Invoked after deserialization in order to return a unique instance if possible.
      Returns:
      a unique instance of the deserialized NilReason.
      Throws:
      ObjectStreamException - required by specification but should never be thrown.

    • getOtherExplanation

      public String getOtherExplanation()
      If this NilReason 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 NilReason is not of kind OTHER.

    • getURI

      public URI getURI()
      If the explanation of this NilReason 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 NilReason is not referenced by a URI.

    • toString

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

    • hashCode

      public int hashCode()
      Returns a hash code value for this NilReason.
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object other)
      Compares this NilReason with the specified object for equality.
      Overrides:
      equals in class Object
      Parameters:
      other - the object to compare with this NilReason.

    • 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 NilObject and LenientComparable interfaces:
        • The NilObject.getNilReason() method will return this NilReason instance.
        • The equals(…) and hashCode() methods behave as documented in LenientComparable.
        • The toString() method is unspecified (may contain debugging information).
        • All other methods return an empty collections, empty arrays, null, NaN, 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 NilObject of the given type.
      Throws:
      IllegalArgumentException - if the given type is not a supported type.

    • createNilPrimitive

      private static Object createNilPrimitive(Class<?> type)
      Returns a new Boolean, Byte, Short, Integer, Long, Float, Double or String instance to be considered as a nil value. The caller is responsible for registering the value in PrimitiveTypeProperties.

      Reminder: If more special cases are added, do not forget to update the mayBeNil(Object) method and to update the createNilObject(Class) and forObject(Object) javadoc.

      Implementation note: There is no special case for Character because Java chars are not really full Unicode characters. They are parts of UTF-16 encoding instead. If there is a need to represent a single Unicode character, we should probably still use a String where the string contain 1 or 2 Java characters. This may also facilitate the encoding in the XML files, since many files use another encoding than UTF-16 anyway.
      Throws:
      IllegalArgumentException - if the given type is not a supported type.

    • mayBeNil

      private static boolean mayBeNil(Object object)
      Returns true if the given object may be one of the sentinel values created by createNilPrimitive(Class). This method only checks the value. If this method returns true, then the caller still needs to check the actual instance using the PrimitiveTypeProperties class. The purpose of this method is to filter the values that cannot be sentinel values, in order to avoid the synchronization done by PrimitiveTypeProperties.

    • 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 NilReason, 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: