Class NilReason
- All Implemented Interfaces:
Serializable
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
orWITHHELD
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 Summary
FieldsModifier and TypeFieldDescriptionprivate InvocationHandler
The invocation handler forNilObject
instances, created when first needed.static final NilReason
There is no value.static final NilReason
The correct value is not readily available to the sender of this data.The values created bycreateNilObject(Class)
.private static final String
The "other" string.static final NilReason
Other reason without explanation.private static final WeakHashSet<NilReason>
The pool of other nil reasons created up to date.private static final NilReason[]
List of predefined constants.private final Object
private static final long
For cross-version compatibility.static final NilReason
The value will be available later.static final NilReason
The correct value is not known to, and not computable by, the sender of this data.static final NilReason
The value is not divulged. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription<T> T
createNilObject
(Class<T> type) Returns an object of the given type which is nil for the reason represented by this instance.private static Object
createNilPrimitive
(Class<?> type) boolean
Compares thisNilReason
with the specified object for equality.static NilReason
If the given object is nil, returns the reason why it does not contain information.If thisNilReason
is an enumeration of kindOTHER
, returns the explanation text.getURI()
If the explanation of thisNilReason
is referenced by a URI, returns that URI.int
hashCode()
Returns a hash code value for thisNilReason
.private static boolean
Returnstrue
if the given object may be one of the sentinel values created bycreateNilPrimitive(Class)
.private Object
Invoked after deserialization in order to return a unique instance if possible.toString()
Returns the GML string representation of thisNilReason
.static NilReason
Parses the given nil reason.static NilReason[]
values()
Returns an array containing every instances of this type that have not yet been garbage collected.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
INAPPLICABLE
There is no value.The string representation is
"inapplicable"
. Other properties (explanation and URI) arenull
. -
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) arenull
. -
TEMPLATE
The value will be available later.The string representation is
"template"
. Other properties (explanation and URI) arenull
. -
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) arenull
. -
WITHHELD
The value is not divulged.The string representation is
"withheld"
. Other properties (explanation and URI) arenull
. -
other
The "other" string.- See Also:
-
OTHER
Other reason without explanation. The string representation of this constant is"other"
. The explanation property is an empty string, and the URI isnull
.Providing an explanation
Users are encouraged to use thevalueOf(String)
method instead of this constant, in order to provide a brief explanation. The string representation forvalueOf(…)
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 ifgetOtherExplanation() != null
instead than comparing the reference against this constant. -
PREDEFINED
List of predefined constants. -
POOL
The pool of other nil reasons created up to date. -
reason
-
handler
The invocation handler forNilObject
instances, created when first needed. The same handler can be shared for all objects having the sameNilReason
, no matter the interface they implement. -
nilObjects
The values created bycreateNilObject(Class)
. They are often instances ofNilObject
, except for some JDK types likeString
,Boolean
orInteger
which are handled in a special way.
-
-
Constructor Details
-
NilReason
Creates a new reason for the given XML value or the given URI.
-
-
Method Details
-
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 thevalueOf(String)
method, in no particular order.- Returns:
- an array containing the instances of
NilReason
.
-
valueOf
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:- Space characters and ISO controls are silently omitted.
- If the remaining string has less than two characters, then the
OTHER
constant is returned.
- 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.
- 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.
- If the given argument is one of the
-
readResolve
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
If thisNilReason
is an enumeration of kindOTHER
, returns the explanation text. Otherwise returnsnull
. If non-null, then the explanation is a string without whitespace.Note that in the special case where
this
nil reason is theOTHER
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 thisNilReason
is not of kindOTHER
.
-
getURI
If the explanation of thisNilReason
is referenced by a URI, returns that URI. Otherwise returnsnull
. The URI and the other explanation attributes are mutually exclusive.- Returns:
- the URI, or
null
if the explanation of thisNilReason
is not referenced by a URI.
-
toString
Returns the GML string representation of thisNilReason
. The returned string is a simple enumeration value (e.g."inapplicable"
) if thisNilReason
is one of the predefined constants, or a string of the form"other:explanation"
, or a URI. -
hashCode
public int hashCode()Returns a hash code value for thisNilReason
. -
equals
Compares thisNilReason
with the specified object for equality. -
createNilObject
Returns an object of the given type which is nil for the reason represented by this instance. Thetype
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
andLenientComparable
interfaces:- The
NilObject.getNilReason()
method will return thisNilReason
instance. - The
equals(…)
andhashCode()
methods behave as documented inLenientComparable
. - The
toString()
method is unspecified (may contain debugging information). - All other methods return an empty collections, empty arrays,
null
,NaN
,0
orfalse
, in this preference order, depending on the method return type.
- The
- One of
Boolean
,Byte
,Short
,Integer
,Long
,Float
,Double
orString
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 thetype
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.
- An interface: in such case, this method returns an object which implement the given
interface together with the
-
createNilPrimitive
Returns a newBoolean
,Byte
,Short
,Integer
,Long
,Float
,Double
orString
instance to be considered as a nil value. The caller is responsible for registering the value inPrimitiveTypeProperties
.Reminder: If more special cases are added, do not forget to update the
mayBeNil(Object)
method and to update thecreateNilObject(Class)
andforObject(Object)
javadoc.Implementation note: There is no special case forCharacter
because Javachar
s 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 aString
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
Returnstrue
if the given object may be one of the sentinel values created bycreateNilPrimitive(Class)
. This method only checks the value. If this method returnstrue
, then the caller still needs to check the actual instance using thePrimitiveTypeProperties
class. The purpose of this method is to filter the values that cannot be sentinel values, in order to avoid the synchronization done byPrimitiveTypeProperties
. -
forObject
If the given object is nil, returns the reason why it does not contain information. This method performs the following choices:- If the given object implements the
NilObject
interface, then this method delegates to theNilObject.getNilReason()
method. - Otherwise if the given object is one of the
Boolean
,Byte
,Short
,Integer
,Long
,Float
,Double
orString
instances returned bycreateNilObject(Class)
, then this method returns the associated reason. - Otherwise this method returns
null
.
- Parameters:
object
- the object for which to get theNilReason
, ornull
.- Returns:
- the reason why the given object contains no information, or
null
if the given object is not nil. - Since:
- 0.4
- See Also:
- If the given object implements the
-