org.umber.bellows.validate
Class TypesafeDatum

java.lang.Object
  org.umber.bellows.Datum
      org.umber.bellows.validate.TypesafeDatum

public final class TypesafeDatum

extends Datum

A pass-through decorator to add typesafety control to an existing Datum object. All accessors check the type safety rules before getting or setting values. The original (inner) Datum object can still be accessed outside the typesafe wrapper, although any operations that short-circuit the wrapper might put the object into a non-typesafe state.

The typesafety wrapper adds methods to set up and monitor the type validation in the inner Datum object. The setTypeSafe() method turns type safety on and off. The isValid() method checks the object for validity. The get/setProperty() methods may throw IllegalArgumentException to express violations in the type names or values. The type constraints can be set individually with the declareProperty() method, or copied over from an existing Datum object with the copyTypes() method.

NOTE: This typesafety API will likely be replaced with a more comprehensive DTD-like validation system in the 0.3.0 release.

Author:

jsheets

Field Summary

Fields inherited from class org.umber.bellows.Datum

DEFAULT_NAMESPACE, EMPTY_CHILDREN, NSURI_PROPERTY

Method Summary

void	copyTypes(TypesafeDatum datum) Copies the property types from the supplied Datum into this Datum.
void	declareProperty(java.lang.String propertyName, java.lang.Class propertyType, java.lang.String namespace) Declares a typing info for a property.
java.lang.String	getId() Getter for property id, the instance-specific identifier for this Datum object.
java.lang.String[]	getKeyNames() Retrieves a Set of all property keys in the default namespace of this Datum.
java.lang.String[]	getKeyNames(java.lang.String namespace) Retrieves a Set of all property keys in the given namespace in this Datum.
java.lang.Object	getLocalProperty(java.lang.String name) Retrieves a property for the given key value.
java.lang.Object	getLocalProperty(java.lang.String name, java.lang.String namespace) Retrieves a property for the given key value.
java.lang.String[]	getNamespaces() Returns an array of all namespaces currently in use in this Datum.
Datum	getParent() Getter for property parent.
java.lang.Object	getProperty(java.lang.String name) Retrieves a property for the given key value.
java.lang.Object	getProperty(java.lang.String name, java.lang.String namespace) Retrieves a property for the given key value.
java.lang.Class	getPropertyType(java.lang.String propertyName, java.lang.String namespace) Retrieves the Java class set for the given property.
java.lang.String	getType() Getter for property type, the name of the type for the Datum and its contents, similar to a class name.
boolean	isValid() Returns the current type safety state of this Datum.
void	setParent(Datum parent) Setter for property parent.
void	setProperty(java.lang.String name, java.lang.Object value) Assigns a value to the stated property.
void	setProperty(java.lang.String name, java.lang.Object value, java.lang.String namespace) Assigns a value to the stated property in the given namespace.
void	setType(java.lang.String type) Setter for property type, the name of the type for the Datum and its contents, similar to a class name.
static TypesafeDatum	wrapDatum(Datum inner) Creates a new instance of TypesafeDatum which wraps the Datum with a type safe API extension.

Methods inherited from class org.umber.bellows.Datum

extractPcdata, extractText, findKeys, getBooleanProperty, getBooleanProperty, getChildren, getEnumProperty, getEnumProperty, getIntegerProperty, getIntegerProperty, getNamespace, getPropertySpace, getStringProperty, getStringProperty, hasPcdataOnly, lookupUri, setNamespace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

wrapDatum

public static TypesafeDatum wrapDatum(Datum inner)

Creates a new instance of TypesafeDatum which wraps the Datum with a type safe API extension.

Parameters:

inner - datum to encapsulate

Returns:

TypesafeDatum wrapper

setType

public void setType(java.lang.String type)

Setter for property type, the name of the type for the Datum and its contents, similar to a class name.

Overrides:

setType in class Datum

Parameters:

type - New value of property type.

getType

public java.lang.String getType()

Getter for property type, the name of the type for the Datum and its contents, similar to a class name.

Overrides:

getType in class Datum

Returns:

Value of property type.

getId

public java.lang.String getId()

Getter for property id, the instance-specific identifier for this Datum object.

Overrides:

getId in class Datum

Returns:

Value of property id.

getParent

public Datum getParent()

Getter for property parent. The object will inherit properties from its parent, if set.

Overrides:

getParent in class Datum

Returns:

Value of property parent.

setParent

public void setParent(Datum parent)

Setter for property parent. The object will inherit properties from its parent, if set.

Overrides:

setParent in class Datum

Parameters:

parent - New value of property parent.

getNamespaces

public java.lang.String[] getNamespaces()

Returns an array of all namespaces currently in use in this Datum. Namespaces should implicitly appear when properties are set in them, then disappear when all their properties are set to null.

Overrides:

getNamespaces in class Datum

Returns:

an array of namespace names

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)

Assigns a value to the stated property.

Overrides:

setProperty in class Datum

Parameters:

name - the key name of the metadata property

value - the metadata value

Throws:

java.lang.IllegalArgumentException - if type safe and value cannot be casted to the declared property type

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value,
                        java.lang.String namespace)

Assigns a value to the stated property in the given namespace.

Overrides:

setProperty in class Datum

Parameters:

name - the key name of the metadata property

value - the metadata value

namespace - the XML-style namespace for this property

Throws:

java.lang.IllegalArgumentException - if type safe and value cannot be casted to the declared property type

getLocalProperty

public java.lang.Object getLocalProperty(java.lang.String name)

Retrieves a property for the given key value. Does not resolve to parent if property is not defined in this object.

Overrides:

getLocalProperty in class Datum

Parameters:

name - the key name of the property

Returns:

the property's value

Throws:

java.lang.IllegalArgumentException - if type safe and the current value cannot be casted to the declared property type

getLocalProperty

public java.lang.Object getLocalProperty(java.lang.String name,
                                         java.lang.String namespace)

Retrieves a property for the given key value. Does not resolve to parent if property is not defined in this object.

Overrides:

getLocalProperty in class Datum

Parameters:

name - the key name of the property

namespace - the XML-style namespace for this property

Returns:

the property's value

Throws:

java.lang.IllegalArgumentException - if type safe and the current value cannot be casted to the declared property type

getProperty

public java.lang.Object getProperty(java.lang.String name)

Retrieves a property for the given key value. Searches for property in the parent if property is not defined in this object.

Overrides:

getProperty in class Datum

Parameters:

name - the key name of the property

Returns:

the property's value

Throws:

java.lang.IllegalArgumentException - if type safe and the current value cannot be casted to the declared property type

getProperty

public java.lang.Object getProperty(java.lang.String name,
                                    java.lang.String namespace)

Retrieves a property for the given key value. Searches for property in the parent if property is not defined in this object.

Overrides:

getProperty in class Datum

Parameters:

name - the key name of the property

namespace - the XML-style namespace for this property

Returns:

the property's value

Throws:

java.lang.IllegalArgumentException - if type safe and the current value cannot be casted to the declared property type

getKeyNames

public java.lang.String[] getKeyNames()

Retrieves a Set of all property keys in the default namespace of this Datum. The keys are typically String objects, but may be other types.

Overrides:

getKeyNames in class Datum

Returns:

a Set of property key Objects

getKeyNames

public java.lang.String[] getKeyNames(java.lang.String namespace)

Retrieves a Set of all property keys in the given namespace in this Datum. The keys are typically String objects, but may be other types.

Overrides:

getKeyNames in class Datum

Parameters:

namespace - the XML-style namespace for this property

Returns:

a Set of property key Objects

isValid

public boolean isValid()

Returns the current type safety state of this Datum.

Returns:

true if this Datum is type safe, or false if not

declareProperty

public void declareProperty(java.lang.String propertyName,
                            java.lang.Class propertyType,
                            java.lang.String namespace)

Declares a typing info for a property. If type safety is turned on, the defined property can only be set to an object that can be casted to the propertyType. Any attempts to set a property that hasn't been declared at all with declareProperty() will cause an IllegalArgumentException to be thrown. If type safety is turned off, all property declarations are ignored.

Property types declared in parent Datum objects are inherited similarly to property values, using the most-local value available. Thus, it is possible to change the type of a property between a parent and a child if both declare the same property with different propertyType.

If propertyType is null, the type of the property will not be checked, even with type safety enabled. This makes it possible to enforce property names without enforcing types, and on a property-by-property basis.

If namespace is null, the property declaration applies to the default namespace.

Parameters:

propertyName - the property name

propertyType - the optional type name of the property

namespace - the optional namespace for this property declaration

copyTypes

public void copyTypes(TypesafeDatum datum)

Copies the property types from the supplied Datum into this Datum. Can use this to transfer a complete type definition from one Datum to another. If type declarations already exist in this Datum, they will be overwritten. Types in parent Datum objects are ignored.

Parameters:

datum - the source of the type definitions to initialize this Datum to

getPropertyType

public java.lang.Class getPropertyType(java.lang.String propertyName,
                                       java.lang.String namespace)

Retrieves the Java class set for the given property. If the type hasn't been set for a property, returns Object.class instead. If namespace is null, assumes the default namespace.

Parameters:

propertyName - the property name

namespace - the optional namespace for this property declaration

Returns:

the Java class of that property, or java.lang.Object if none was specified