org.geotoolkit.xml
Class NilReason

Object
  NilReason

All Implemented Interfaces:

Serializable

@Immutable
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.

Since:

3.18

Version:

3.18

Author:

Martin Desruisseaux (Geomatys)

See Also:

NilObject, Serialized Form

Module:

utility/geotk-xml-base (download)

View source code for this class

Field Summary

static NilReason	INAPPLICABLE There is no value.
static NilReason	MISSING The correct value is not readily available to the sender of this data.
static NilReason	OTHER Other brief explanation.
static NilReason	TEMPLATE The value will be available later.
static NilReason	UNKNOWN The correct value is not known to, and not computable by, the sender of this data.
static NilReason	WITHHELD The value is not divulged.

Method Summary

<T> T	createNilObject(Class<T> type) Returns an object of the given type which is nil for the reason represented by this enum.
boolean	equals(Object other) Compares this NilReason with the specified object for equality.
String	getExplanation() If this NilReason is an enumeration of kind OTHER, returns the explanation text.
URI	getURI() If the explanation of this NilReason is referenced by a URI, returns that URI.
int	hashCode() Returns a hash code value for this NilReason.
String	toString() Returns the GML string representation of this NilReason.
static NilReason	valueOf(String reason) Parses the given nil reason.
static NilReason[]	values() Returns an array containing every instances of this type that have not yet been garbage collected.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INAPPLICABLE

public static final NilReason INAPPLICABLE

There is no value.

The string representation is "inapplicable".

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".

TEMPLATE

public static final NilReason TEMPLATE

The value will be available later.

The string representation is "template".

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".

WITHHELD

public static final NilReason WITHHELD

The value is not divulged.

The string representation is "withheld".

OTHER

public static final NilReason OTHER

Other brief explanation. This constant does not provide any explanation. In order to test if an enumeration is "other", users should invoke the getExplanation() method instead than comparing against this enumeration.

The string representation is "other:text", where text is a string of two or more characters with no included spaces.

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 enumeration constants, 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 this type.

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, then the corresponding pre-defined constant is returned.

• Otherwise if the given argument is "other:" followed by an explanation text, then a new instance is created and returned for that explanation. Note that if the given explanation contains any characters that are not unicode identifier (for example white spaces), then those characters are omitted.

• 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 can not be parsed as a URI.

getExplanation

public String getExplanation()

If this NilReason is an enumeration of kind OTHER, returns the explanation text. Otherwise returns null. If non-null, then the explanation is a unicode identifier without white space.

Note that in the special case where this nil reason is the OTHER instance itself, then this method returns an empty string.

Returns:

The explanation as a unicode identifier, or null if this NilReason is not an enumeration of kind OTHER.

getURI

public URI getURI()

If the explanation of this NilReason is referenced by a URI, returns that URI. Otherwise returns null.

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:text", 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 enum. This method returns an object which implement the given interface together with the NilObject interface. The NilObject.getNilReason() method will return this enum, and all other methods (except the ones inherited from the Object class) will return null or an empty collection as appropriate.

Type Parameters:

T - The compile-time type of the type argument.

Parameters:

type - The object type as an interface. This is usually a GeoAPI interface.

Returns:

An NilObject of the given type.