org.umber.bellows
Class Datum

java.lang.Object
  extended byorg.umber.bellows.Datum
Direct Known Subclasses:
ListDatum, TypesafeDatum

public class Datum
extends java.lang.Object

A single unit of generic data. Each Datum object can contain an arbitrary set of properties with arbitrary values. By default, the Datum does no type or property name validation; setting a property implicitly creates that property in the Datum instance. That property can hold any value and any class type.

To better support mapping from XML documents, Datum properties can also reside in namespaces. A single property name can legally exist in more than one namespace, and is considered to be different properties. Thus, the "size" property in the "Dimensions" namespace might hold the value of new Rectangle(3, 5), while the "size" property in the "Descriptions" namespace might hold the value of "very large". The getNamespaces() method returns an array of all namespaces in current use in the Datum object.

A Datum may contain an optional parent. A Datum inherits all the properties and type declarations in its parent that it doesn't override locally. The getProperty() method falls back on parent properties if the property isn't locally defined; the getLocalProperty() only looks for the property in the current Datum object, ignoring any parent properties.

Author:
jsheets

Field Summary
static java.lang.String DEFAULT_NAMESPACE
          Default namespace to use when none is specified.
static Datum[] EMPTY_CHILDREN
          Empty child array shared by all Datum objects.
static java.lang.String NSURI_PROPERTY
          The name of the property which contains the xmlns namespace mapping.
 
Constructor Summary
Datum()
          Creates a new instance of Datum
Datum(Datum copyDatum)
          Creates a new instance of Datum by copying the properties from the copyDatum into the new Datum.
Datum(java.lang.String type)
          Creates a new instance of Datum with the given type name.
Datum(java.lang.String type, java.lang.String id)
          Creates a new instance of Datum with the given type and id names.
 
Method Summary
 java.lang.String extractPcdata(boolean collapseWhitespace)
          Recursively extracts PCDATA content from the given Datum node.
 java.lang.String extractText(java.lang.String propertyName, java.lang.String namespace, boolean collapseWhitespace)
          Recursively extracts the string values of the given property within the given namespace, in the supplied Datum and any child Datum objects, if present.
 java.lang.String[] findKeys(java.lang.String keyFilter, java.lang.String namespace)
          Retrieves an array of key names in this Datum object within the given namespace which match the regular expression in keyFilter.
 boolean getBooleanProperty(java.lang.String key, boolean defaultValue)
          Evaluates the property and converts it to a boolean value, using some simple heuristics.
 boolean getBooleanProperty(java.lang.String key, java.lang.String namespace, boolean defaultValue, boolean inherited)
          Evaluates the property within the given namespace and converts it to a boolean value, using some simple heuristics.
 Datum[] getChildren()
          Getter for property children.
 int getEnumProperty(java.lang.String key, java.lang.String[] enums, int defaultValue)
          Evaluates the value of the property in terms of an array of enumeration values.
 int getEnumProperty(java.lang.String key, java.lang.String namespace, java.lang.String[] enums, int defaultValue, boolean inherited)
          Evaluates the value of the property within the given namespace in terms of an array of enumeration values.
 java.lang.String getId()
          Getter for property id, the instance-specific identifier for this Datum object.
 int getIntegerProperty(java.lang.String key, int defaultValue)
          Evaluates the property and converts it to an integer value.
 int getIntegerProperty(java.lang.String key, java.lang.String namespace, int defaultValue, boolean inherited)
          Evaluates the property within the given namespace and converts it to an integer value.
 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 getNamespace()
          Getter for property namespace, the name of the namespace for the Datum as a whole.
 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.
protected  java.util.Map getPropertySpace(java.lang.String namespace)
          Returns an entire namespace Map.
 java.lang.String getStringProperty(java.lang.String key, java.lang.String defaultValue)
          Extracts a String version of a property from the Datum.
 java.lang.String getStringProperty(java.lang.String key, java.lang.String namespace, java.lang.String defaultValue, boolean inherited)
          Extracts a String version of a property from the Datum within the given namespace.
 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 hasPcdataOnly()
          Determines if the Datum contains only PCDATA content, with no element content.
 java.lang.String lookupUri(java.lang.String namespace)
          Searches a Datum and its parents until it finds a URI declaration for the given namespace.
 void setNamespace(java.lang.String namespace)
          Setter for property namespace, the name of the namespace for the Datum as a whole.
 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.
 java.lang.String toString()
          Creates a neatly formatted String version of the Datum object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

EMPTY_CHILDREN

public static final Datum[] EMPTY_CHILDREN
Empty child array shared by all Datum objects.


DEFAULT_NAMESPACE

public static final java.lang.String DEFAULT_NAMESPACE
Default namespace to use when none is specified.

See Also:
Constant Field Values

NSURI_PROPERTY

public static final java.lang.String NSURI_PROPERTY
The name of the property which contains the xmlns namespace mapping. The value of this property should always be a Map which points the namespace prefixes to their URIs. For example, the XML <root xmlns:ns="http://mydomain.com"/> would correspond to a Map with a key of "ns" and a value of "http://mydomain.com".

See Also:
Constant Field Values
Constructor Detail

Datum

public Datum()
Creates a new instance of Datum


Datum

public Datum(java.lang.String type)
Creates a new instance of Datum with the given type name. The type name does not need to be unique, but conceptually should be consistent with other Datum objects that share the same type name.

Parameters:
type - the type name of this Datum

Datum

public Datum(java.lang.String type,
             java.lang.String id)
Creates a new instance of Datum with the given type and id names. The type name does not need to be unique, but conceptually should be consistent with other Datum objects that share the same type name. The id should probably be unique, at least among other Datum objects with the same type name, but this constraint is not enforced.

Parameters:
type - the type name of this Datum
id - the unique id of this Datum

Datum

public Datum(Datum copyDatum)
Creates a new instance of Datum by copying the properties from the copyDatum into the new Datum. Does not copy any parent or child associations (use the ListDatum copy constructor for that).

Parameters:
copyDatum - source Datum to copy into the new Datum
Method Detail

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.

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.

Returns:
Value of property type.

setNamespace

public void setNamespace(java.lang.String namespace)
Setter for property namespace, the name of the namespace for the Datum as a whole. This namespace is separate from the property-level namespaces defined by getNamespaces().

Parameters:
namespace - New value of property namespace.

getNamespace

public java.lang.String getNamespace()
Getter for property namespace, the name of the namespace for the Datum as a whole. This namespace is separate from the property-level namespaces defined by getNamespaces().

Returns:
Value of property namespace.

getId

public java.lang.String getId()
Getter for property id, the instance-specific identifier for this Datum object.

Returns:
Value of property id.

getParent

public Datum getParent()
Getter for property parent. The object will inherit properties from its parent, if set.

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.

Parameters:
parent - New value of property parent.

getChildren

public Datum[] getChildren()
Getter for property children. Always returns an empty array, EMPTY_CHILDREN.

Returns:
Value of property children.

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.

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.

Parameters:
name - the key name of the metadata property
value - the metadata value

getPropertySpace

protected java.util.Map getPropertySpace(java.lang.String namespace)
Returns an entire namespace Map. The returned Map can then be used to look up properties in that namespace. A null namespace is equivalent to DEFAULT_NAMESPACE.

Parameters:
namespace - the namespace
Returns:
a Map of all properties in the namespace, or null if the namespace is empty

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. A null namespace is equivalent to DEFAULT_NAMESPACE.

Parameters:
name - the key name of the metadata property
value - the metadata value
namespace - the XML-style namespace for this property

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.

Parameters:
name - the key name of the property
Returns:
the property's value

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. A null namespace is equivalent to DEFAULT_NAMESPACE.

Parameters:
name - the key name of the property
namespace - the XML-style namespace for this property
Returns:
the property's value

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.

Parameters:
name - the key name of the property
Returns:
the property's value

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. A null namespace is equivalent to DEFAULT_NAMESPACE.

Parameters:
name - the key name of the property
namespace - the XML-style namespace for this property
Returns:
the property's value

getStringProperty

public java.lang.String getStringProperty(java.lang.String key,
                                          java.lang.String namespace,
                                          java.lang.String defaultValue,
                                          boolean inherited)
Extracts a String version of a property from the Datum within the given namespace. If the property value is a String, it just returns that. If the property does not exist, it returns the supplied default value. If the value is a non-String, it returns the value of toString() on the property value.

Parameters:
key - the property name
namespace - the XML-style namespace for this property
defaultValue - default to return if the property cannot be found
inherited - if true, search parent Datum for property if not in child
Returns:
the String contents of the property

getStringProperty

public java.lang.String getStringProperty(java.lang.String key,
                                          java.lang.String defaultValue)
Extracts a String version of a property from the Datum. If the property value is a String, it just returns that. If the property does not exist, it returns the supplied default value. If the value is a non-String, it returns the value of toString() on the property value. Does not inherit property values from parent Datum objects.

Parameters:
key - the property name
defaultValue - default to return if the property cannot be found
Returns:
the String contents of the property

getBooleanProperty

public boolean getBooleanProperty(java.lang.String key,
                                  java.lang.String namespace,
                                  boolean defaultValue,
                                  boolean inherited)
Evaluates the property within the given namespace and converts it to a boolean value, using some simple heuristics. A true value results from the strings "yes", "on", and "true"; false results from "no", "off", and "false". If the property does not exist, it returns the supplied default value.

Parameters:
key - the property name
namespace - the XML-style namespace for this property
defaultValue - default to return if the property cannot be found
inherited - if true, search parent Datum for property if not in child
Returns:
the boolean value of the property

getBooleanProperty

public boolean getBooleanProperty(java.lang.String key,
                                  boolean defaultValue)
Evaluates the property and converts it to a boolean value, using some simple heuristics. A true value results from the strings "yes", "on", and "true"; false results from "no", "off", and "false". If the property does not exist, it returns the supplied default value. Does not inherit property values from parent Datum objects.

Parameters:
key - the property name
defaultValue - default to return if the property cannot be found
Returns:
the boolean value of the property

getIntegerProperty

public int getIntegerProperty(java.lang.String key,
                              java.lang.String namespace,
                              int defaultValue,
                              boolean inherited)
Evaluates the property within the given namespace and converts it to an integer value. If the property's value is an Integer, it returns the int value. If the value is a String, it attempts to convert it to an int value. If the parsing fails, it returns the defaultValue.

Parameters:
key - the property name
namespace - the XML-style namespace for this property
defaultValue - default to return if the property cannot be found
inherited - if true, search parent Datum for property if not in child
Returns:
the int value of the property

getIntegerProperty

public int getIntegerProperty(java.lang.String key,
                              int defaultValue)
Evaluates the property and converts it to an integer value. If the property's value is an Integer, it returns the int value. If the value is a String, it attempts to convert it to an int value. If the parsing fails, it returns the defaultValue. Does not inherit property values from parent Datum objects.

Parameters:
key - the property name
defaultValue - default to return if the property cannot be found
Returns:
the int value of the property

getEnumProperty

public int getEnumProperty(java.lang.String key,
                           java.lang.String namespace,
                           java.lang.String[] enums,
                           int defaultValue,
                           boolean inherited)
Evaluates the value of the property within the given namespace in terms of an array of enumeration values. If the String version of the property value matches one of the values in the enums array, it returns the matching index number. If no match, returns the default value.

Parameters:
key - the property name
namespace - the XML-style namespace for this property
enums - an array of legal values for the enumeration
defaultValue - default to return if the property cannot be found
inherited - if true, search parent Datum for property if not in child
Returns:
the int value of the property

getEnumProperty

public int getEnumProperty(java.lang.String key,
                           java.lang.String[] enums,
                           int defaultValue)
Evaluates the value of the property in terms of an array of enumeration values. If the String version of the property value matches one of the values in the enums array, it returns the matching index number. If no match, returns the default value. Does not inherit property values from parent Datum objects.

Parameters:
key - the property name
enums - an array of legal values for the enumeration
defaultValue - default to return if the property cannot be found
Returns:
the int value of the property

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.

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.

Parameters:
namespace - the XML-style namespace for this property
Returns:
a Set of property key Objects

findKeys

public java.lang.String[] findKeys(java.lang.String keyFilter,
                                   java.lang.String namespace)
Retrieves an array of key names in this Datum object within the given namespace which match the regular expression in keyFilter.

Parameters:
keyFilter - a regular expression pattern to match keys against
namespace - the XML-style namespace for this property
Returns:
an array of key names that match the filter

lookupUri

public java.lang.String lookupUri(java.lang.String namespace)
Searches a Datum and its parents until it finds a URI declaration for the given namespace. In XML documents, this mapping is stored as xmlns declarations, for example:
   <root xmlns:ns="http://mydomain.com"/>
 

Parameters:
namespace - Datum namespace
Returns:
the namespace URI, or null if not found

extractText

public java.lang.String extractText(java.lang.String propertyName,
                                    java.lang.String namespace,
                                    boolean collapseWhitespace)
Recursively extracts the string values of the given property within the given namespace, in the supplied Datum and any child Datum objects, if present. This is useful for treating a Datum as XML PCDATA content. To remove nonessential whitespace, collapsing it down to single spaces, pass in a true to collapseWhitespace.

Parameters:
propertyName - the name of the property to search for text in
namespace - the XML-style namespace for this property
collapseWhitespace - whether to remove nonessential whitespace
Returns:
a String version of the Datum

extractPcdata

public java.lang.String extractPcdata(boolean collapseWhitespace)
Recursively extracts PCDATA content from the given Datum node.

Parameters:
collapseWhitespace - whether to remove nonessential whitespace
Returns:
concatenated PCDATA content

hasPcdataOnly

public boolean hasPcdataOnly()
Determines if the Datum contains only PCDATA content, with no element content. This is useful for identifying text-only elements.

Returns:
true if node contains PCDATA and no other Datum content

toString

public java.lang.String toString()
Creates a neatly formatted String version of the Datum object.

Returns:
a String version of this object
See Also:
Object.toString()