dsto.dfc.databeans
Class PropertyPath

java.lang.Object
  dsto.dfc.databeans.PropertyPath

public class PropertyPath
extends Object

Describes a path built of property names into a tree of IDataObject's, similar in concept to a file system path.

Version:

$Revision: 1.20 $

Author:

mpp

Field Summary

static PropertyPath

EMPTY_PATH

Constructor Summary

PropertyPath()
Create an empty path.

PropertyPath(Object path)

PropertyPath(Object[] path)
Create path from an array of property names.

PropertyPath(String pathExpr)
Create path from a path expression such as "root/bean1/bean2/property".

Method Summary

PropertyPath	append(Object entry) Append a new element to the end of the path.
Object	element(int index)
boolean	equals(Object o) Test if two paths are the same.
boolean	equals(PropertyPath p)
Object	first() Get the first component of the path.
Object	follow(IDataObject object) Follow this path into a given object and return the value.
IDataObject	followParent(IDataObject root) Follow the path to the last-but-one entry, starting with given root.
int	hashCode()
boolean	isEmpty()
boolean	isPrefixOf(PropertyPath propertyPath) Test if this path is prefix of the given path.
boolean	isSamePath(String pathExpr) Test if a given path expression is equivalent to this path.
Object	last() Get the last component of the path.
int	length()
IDataObject	make(IDataObject object) Ensure this path exists into a given object.
Object	make(IDataObject object, Class leafClass) Ensure this path exists into a given object.
Object	make(IDataObject object, Class leafClass, int mode) Ensure this path exists into a given object.
IDataObject	make(IDataObject object, int mode) Ensure this path exists into a given object.
PropertyPath	parent() Create a new path to the parent object of this path (ie the first length () - 1 elements).
PropertyPath	prepend(Object entry) Prepend a new element to the starting of the path.
boolean	startsWith(Object property) Shortcut to test whether path starts with a given property.
PropertyPath	tail() Create a new path from the last length () - 1 elements of this path.
PropertyPath	tail(int chop) Create a new path from the last length () - chop elements of this path.
String	toString() Turn the path into a string expression such as "bean/bean2/property".

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_PATH

public static final PropertyPath EMPTY_PATH

Constructor Detail

PropertyPath

public PropertyPath()

Create an empty path.

See Also:

EMPTY_PATH

PropertyPath

public PropertyPath(String pathExpr)

Create path from a path expression such as "root/bean1/bean2/property".

PropertyPath

public PropertyPath(Object path)

PropertyPath

public PropertyPath(Object[] path)

Create path from an array of property names.

Method Detail

followParent

public IDataObject followParent(IDataObject root)
                         throws IllegalArgumentException,
                                ClassCastException

Follow the path to the last-but-one entry, starting with given root.

Parameters:

root - A root data object.

Returns:

The parent object of the property described by this path.

Throws:

IllegalArgumentException - If the path is empty or one of the properties in the path cannot be read (ie null).

ClassCastException - If any of the entries except the last is not an IDataObject.

follow

public Object follow(IDataObject object)

Follow this path into a given object and return the value. This is equivalent to DataObjects.getValue(IDataObject, PropertyPath).

See Also:

followParent(IDataObject)

make

public IDataObject make(IDataObject object)
                 throws ClassCastException

Ensure this path exists into a given object. Any missing parts of the path are filled in with empty DataBean instances.

Parameters:

object - The object to create the path in.

Returns:

The last element in the path.

Throws:

ClassCastException - if the last item on the path already exists and is not an IDataObject.

make

public IDataObject make(IDataObject object,
                        int mode)
                 throws ClassCastException

Ensure this path exists into a given object. Any missing parts of the path are filled in with empty DataBean instances.

Parameters:

object - The object to create the path in.

mode - The create mode for new path elements. One of IDataObject.TRANSIENT or IDataObject.PERSISTENT.

Returns:

The last element in the path.

Throws:

ClassCastException - if the last item on the path already exists and is not an IDataObject.

make

public Object make(IDataObject object,
                   Class leafClass)
            throws ClassCastException,
                   IllegalArgumentException

Ensure this path exists into a given object. Any missing parts of the path are filled in with empty DataBean instances.

Parameters:

object - The object to create the path in.

leafClass - The class of the last object in the path. This is instantiated using the default constructor if it does not exist.

Returns:

The last element in the path.

Throws:

ClassCastException - if the last item on the path already exists and is not an IDataObject.

IllegalArgumentException - if leafClass cannot be instantiated.

make

public Object make(IDataObject object,
                   Class leafClass,
                   int mode)
            throws ClassCastException,
                   IllegalArgumentException

Ensure this path exists into a given object. Any missing parts of the path are filled in with empty DataBean instances.

Parameters:

object - The object to create the path in.

leafClass - The class of the last object in the path. This is instantiated using the default constructor if it does not exist.

mode - The create mode for new path elements. One of IDataObject.TRANSIENT or IDataObject.PERSISTENT.

Returns:

The last element in the path.

Throws:

ClassCastException - if the last item on the path already exists and is not an IDataObject.

IllegalArgumentException - if leafClass cannot be instantiated.

isEmpty

public boolean isEmpty()

length

public int length()

last

public Object last()
            throws IllegalArgumentException

Get the last component of the path.

Returns:

The last path component.

Throws:

IllegalArgumentException - If the path is empty.

first

public Object first()
             throws IllegalArgumentException

Get the first component of the path.

Returns:

The first path component.

Throws:

IllegalArgumentException - If the path is empty.

element

public Object element(int index)

append

public PropertyPath append(Object entry)

Append a new element to the end of the path.

Parameters:

entry - The new entry (may not be null).

Returns:

The new path.

prepend

public PropertyPath prepend(Object entry)

Prepend a new element to the starting of the path.

Parameters:

entry - The new entry (may not be null).

Returns:

The new path.

tail

public PropertyPath tail()

Create a new path from the last length () - 1 elements of this path. Path length must be >= 2.

See Also:

parent(), tail(int)

tail

public PropertyPath tail(int chop)

Create a new path from the last length () - chop elements of this path. e.g. path.tail (3) is the same as path.tail ().tail ().tail ().

See Also:

parent(), tail()

parent

public PropertyPath parent()

Create a new path to the parent object of this path (ie the first length () - 1 elements). Path length must be >= 2.

See Also:

tail()

isPrefixOf

public boolean isPrefixOf(PropertyPath propertyPath)

Test if this path is prefix of the given path. e.g "", "a", "a/b" and "a/b/c" are all prefixes of "a/b/c"

Parameters:

propertyPath - The path to test.

Returns:

True if this path is a prefix of propertyPath.

isSamePath

public boolean isSamePath(String pathExpr)

Test if a given path expression is equivalent to this path.

Parameters:

pathExpr - A path expression eg "bean1/bean2/property".

Returns:

boolean True of pathExpr is equivalent.

toString

public String toString()

Turn the path into a string expression such as "bean/bean2/property".

Overrides:

toString in class Object

startsWith

public boolean startsWith(Object property)

Shortcut to test whether path starts with a given property. Same as path.first ().equals (property);

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object o)

Test if two paths are the same.

Overrides:

equals in class Object

equals

public boolean equals(PropertyPath p)