dsto.dfc.databeans
Class DataObjects

java.lang.Object
  dsto.dfc.databeans.DataObjects

public final class DataObjects
extends Object

Utility methods for data objects.

Version:

$Revision: 1.43 $

Author:

mpp

Method Summary

static IDataObject	deepClone(IDataObject root) Deep clone a graph of IDataObject's.
static IDataObject	find(IDataObject objects, Object property, Object value) Find a data object with a given property value in a data objects value set.
static IDataObject	findInCollection(Collection objects, Object property, Object value) Find a data object with a given property value in a collection.
static IDataObject	findInCollection(Comparator comparator, Collection objects, Object property, Object value) Find a data object with a given property value in a collection.
static int	findIndex(List objects, Object property, Object value) Find the index of a data object with a given property value in a list.
static void	fireChangedEvents(AbstractDataObject oldObject, AbstractDataObject newObject) Compare the properties of two data objects and fire appropriate property change events.
static Object	getValue(IDataObject object, PropertyPath path) Get a value using a property path.
static Object	getValue(IDataObject object, String pathExpr) Get a value using a path expression.
static boolean	getValue(IDataObject object, String path, boolean defaultValue) Get a boolean value from a data object using the path expression, returning a default if none set.
static int	getValue(IDataObject object, String path, int defaultValue) Get an int value from a data object using the path expression, returning a default if none set.
static Object	getValue(IDataObject object, String pathExpr, Object defaultValue) Get a value from a data object using the path expression, returning a default if none set.
static String	getValue(IDataObject object, String pathExpr, String defaultValue) Get a string value from a data object using the path expression, returning a default if none set.
static boolean	isSoftLink(Object value) Test if an object is a soft link (i.e.
static IDataObject	makePath(IDataObject object, String path) Ensure a path exists into a given object.
static Object	makePath(IDataObject object, String path, Class leafClass) Ensure a path exists into a given object.
static Object	makePath(IDataObject object, String path, Class leafClass, int mode) Ensure a path exists into a given object.
static IDataObject	makePath(IDataObject object, String path, int mode) Ensure a path exists into a given object.
static void	merge(IDataObject source, IDataObject target) Merge a source object into a target object.
static void	merge(IDataObject source, IDataObject target, int orMode) Merge a source object into a target object.
static void	merge(IDataObject source, IDataObject target, int orMode, boolean equalise) Merge a source object into a target object.
static void	merge(PropertyPath path, Object source, IDataObject target) Shortcut to merge a source object into a property of a target object, recursively merging embedded IDataObject's using merge(IDataObject, IDataObject).
static void	merge(PropertyPath path, Object source, IDataObject target, int orMode, boolean equalise) Shortcut to merge a source object into a property of a target object, recursively merging embedded IDataObject's using merge(IDataObject, IDataObject).
static boolean	objectsEqual(IDataObject o1, IDataObject o2) Test if two data objects are equal.
static Set<String>	propertySet(IDataObject object) Shorcut to create a copy of the current property set of a data object.
static void	registerChildValue(IDataObjectChildListener parent, Object property, Object value) Provides support for data object implementations in propagating child events.
static void	setValue(IDataObject object, PropertyPath path, Object value)
static void	setValue(IDataObject object, PropertyPath path, Object value, int mode) Set a value using a property path.
static void	setValue(IDataObject object, String pathExpr, Object value) Set a value using a path expression.
static void	setValue(IDataObject object, String pathExpr, Object value, int mode)
static void	shallowCopy(IDataObject source, IDataObject target) Shallow copy the property values of one object to another.
static String[]	stringValues(Collection objects, String property) Generate an array of string property values from a collection of IDataObject's.
static void	unregisterChildValue(IDataObjectChildListener parent, Object value) Reverses the effect of registerChildValue(IDataObjectChildListener, Object, Object).
static Set	valueSet(IDataObject object) Shorcut to create a copy of the current set of values of a data object.

Methods inherited from class java.lang.Object

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

Method Detail

deepClone

public static IDataObject deepClone(IDataObject root)
                             throws UnsupportedOperationException

Deep clone a graph of IDataObject's. Non IDataObject's are assumed to be immutable and are not cloned.

Parameters:

root - The root of the object graph.

Returns:

A copy of root.

Throws:

UnsupportedOperationException - if an object could not be cloned.

shallowCopy

public static void shallowCopy(IDataObject source,
                               IDataObject target)

Shallow copy the property values of one object to another. The property values themselves are not cloned. The transient status of property values is preserved.

setValue

public static void setValue(IDataObject object,
                            String pathExpr,
                            Object value)

Set a value using a path expression. Any missing parent entries will be filled in by empty, transient DataBean instances.

Parameters:

object - The root object.

pathExpr - A path expression such as "bean1/bean2/property".

value - The value to set the property referenced by pathExpr to.

Throws:

IllegalArgumentException - If path expr is not valid for the root bean.

See Also:

makePath(IDataObject, String)

setValue

public static void setValue(IDataObject object,
                            String pathExpr,
                            Object value,
                            int mode)
                     throws IllegalArgumentException

Throws:

IllegalArgumentException

setValue

public static void setValue(IDataObject object,
                            PropertyPath path,
                            Object value)
                     throws IllegalArgumentException

Throws:

IllegalArgumentException

setValue

public static void setValue(IDataObject object,
                            PropertyPath path,
                            Object value,
                            int mode)
                     throws IllegalArgumentException

Set a value using a property path. Any missing parent entries will be filled in by empty, transient DataBean instances.

Parameters:

object - The root object.

path - The path to the property.

value - The value to set the property referenced by path to.

Throws:

IllegalArgumentException - If path expr is not valid for the root bean.

ClassCastException - if an object on the parent path exists already and is not an IDataObject.

See Also:

makePath(IDataObject, String)

getValue

public static Object getValue(IDataObject object,
                              String pathExpr)
                       throws IllegalArgumentException

Get a value using a path expression.

Parameters:

object - The root object.

pathExpr - A path expression such as "bean1/bean2/property".

Returns:

The value of the property referenced by pathExpr.

Throws:

IllegalArgumentException - If path expr is not valid for the root bean.

getValue

public static Object getValue(IDataObject object,
                              PropertyPath path)
                       throws IllegalArgumentException

Get a value using a property path.

Parameters:

object - The root object.

path - A property path.

Returns:

The value of the property referenced by path.

Throws:

IllegalArgumentException - If path expr is not valid for the root bean.

getValue

public static Object getValue(IDataObject object,
                              String pathExpr,
                              Object defaultValue)

Get a value from a data object using the path expression, returning a default if none set.

Parameters:

object - The object.

pathExpr - The property path.

defaultValue - The default value.

Returns:

Either the value of property or defaultValue if no value in bean.

getValue

public static String getValue(IDataObject object,
                              String pathExpr,
                              String defaultValue)

Get a string value from a data object using the path expression, returning a default if none set.

Parameters:

object - The object.

pathExpr - The property path.

defaultValue - The default value.

Returns:

Either the value of property or defaultValue if no value in bean.

getValue

public static int getValue(IDataObject object,
                           String path,
                           int defaultValue)

Get an int value from a data object using the path expression, returning a default if none set.

Parameters:

object - The object.

path - The property path.

defaultValue - The default value.

Returns:

Either the value of property or defaultValue if no value in bean.

Throws:

IllegalArgumentException - If path expr is not valid for the object.

getValue

public static boolean getValue(IDataObject object,
                               String path,
                               boolean defaultValue)

Get a boolean value from a data object using the path expression, returning a default if none set.

Parameters:

object - The object.

path - The property path.

defaultValue - The default value.

Returns:

Either the value of property or defaultValue if no value in bean.

makePath

public static IDataObject makePath(IDataObject object,
                                   String path)
                            throws ClassCastException

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

Parameters:

object - The bean to create the path on.

path - The path expression (eg "folder/name").

Returns:

The last element in the path.

Throws:

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

See Also:

makePath(IDataObject, String, int), PropertyPath.make(IDataObject)

makePath

public static IDataObject makePath(IDataObject object,
                                   String path,
                                   int mode)
                            throws ClassCastException

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

Parameters:

object - The bean to create the path on.

path - The path expression (eg "folder/name").

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.

See Also:

PropertyPath.make(IDataObject)

makePath

public static Object makePath(IDataObject object,
                              String path,
                              Class leafClass)
                       throws ClassCastException

Ensure a path exists into a given object. Any missing parts of the path are filled in with empty DataBean instances, except the last which will be an instance of the supplied leafClass type.

Parameters:

object - The bean to create the path on.

path - The path expression (eg "folder/name").

leafClass - The type of the last element in the path.

Returns:

The last element in the path.

Throws:

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

See Also:

PropertyPath.make(IDataObject)

makePath

public static Object makePath(IDataObject object,
                              String path,
                              Class leafClass,
                              int mode)
                       throws ClassCastException

Ensure a path exists into a given object. Any missing parts of the path are filled in with empty DataBean instances, except the last which will be an instance of the supplied leafClass type.

Parameters:

object - The bean to create the path on.

path - The path expression (eg "folder/name").

leafClass - The type of the last element in the path.

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.

See Also:

PropertyPath.make(IDataObject)

fireChangedEvents

public static void fireChangedEvents(AbstractDataObject oldObject,
                                     AbstractDataObject newObject)

Compare the properties of two data objects and fire appropriate property change events. This can be useful for generating events when simple data objects (eg SimpleDataObject) have changed in an unknown way.

Parameters:

oldObject - The old value.

newObject - The new value. This is the value for which events will be fired.

find

public static IDataObject find(IDataObject objects,
                               Object property,
                               Object value)

Find a data object with a given property value in a data objects value set.

Parameters:

objects - A data object.

property - The property to match.

value - The value to match.

Returns:

The first matching object, or null if none found.

findInCollection

public static IDataObject findInCollection(Collection objects,
                                           Object property,
                                           Object value)

Find a data object with a given property value in a collection.

Parameters:

objects - A collection of IDataObject's.

property - The property to match.

value - The value to match.

Returns:

The first matching object, or null if none found.

findInCollection

public static IDataObject findInCollection(Comparator comparator,
                                           Collection objects,
                                           Object property,
                                           Object value)

Find a data object with a given property value in a collection.

Parameters:

comparator - The comparator to use in matching objects.

objects - A collection of IDataObject's.

property - The property to match.

value - The value to match.

Returns:

The first matching object, or null if none found.

findIndex

public static int findIndex(List objects,
                            Object property,
                            Object value)

Find the index of a data object with a given property value in a list.

Parameters:

objects - A list of IDataObject's.

property - The property to match.

value - The value to match.

Returns:

The index of the first matching object, or -1 if none found.

stringValues

public static String[] stringValues(Collection objects,
                                    String property)

Generate an array of string property values from a collection of IDataObject's.

Parameters:

objects - A collection of IDataObject's.

property - The property to extract from each object.

objectsEqual

public static boolean objectsEqual(IDataObject o1,
                                   IDataObject o2)

Test if two data objects are equal. This does a deep test of any IDataObject properties.

merge

public static void merge(PropertyPath path,
                         Object source,
                         IDataObject target)

Shortcut to merge a source object into a property of a target object, recursively merging embedded IDataObject's using merge(IDataObject, IDataObject).

Parameters:

path - The path into the target to merge the source object with. Using an empty path is equivalent to just calling merge(IDataObject, IDataObject)

source - The source to merge into target. This may either be an IDataObject, in which case it is merged with the target value if it is also an IDataObject, or a primitive value, in which case this call has the same effect as a setValue ().

target - The target to merge to.

See Also:

merge(IDataObject, IDataObject)

merge

public static void merge(PropertyPath path,
                         Object source,
                         IDataObject target,
                         int orMode,
                         boolean equalise)

Shortcut to merge a source object into a property of a target object, recursively merging embedded IDataObject's using merge(IDataObject, IDataObject).

Parameters:

path - The path into the target to merge the source object with. Using an empty path is equivalent to just calling merge(IDataObject, IDataObject)

source - The source to merge into target. This may either be an IDataObject, in which case it is merged with the target value if it is also an IDataObject, or a primitive value, in which case this call has the same effect as a setValue ().

target - The target to merge to.

orMode - A bitwise OR of TRANSIENT and/or OVERRIDE. These bits will be or'd with the default mode used in IDataObject.setValue(Object, Object, int).

equalise - If true then the property set of target is made equal to that of the source source by deleting any properties in target that are not in the source. i.e. the target becomes a logical copy of source. This can be used to generate the minimal number of changes needed to change target into source. If false, then target becomes a union of the property sets of source and target.

See Also:

merge(IDataObject, IDataObject, int, boolean)

merge

public static void merge(IDataObject source,
                         IDataObject target)

Merge a source object into a target object. Recursively merges embedded IDataObject's. Values in target are overrwritten by values in source.

Parameters:

source - The source to merge from.

target - The target to merge to.

See Also:

merge(IDataObject, IDataObject, int)

merge

public static void merge(IDataObject source,
                         IDataObject target,
                         int orMode)

Merge a source object into a target object. Recursively merges embedded IDataObject's.

Parameters:

source - The source to merge from.

target - The target to merge to.

orMode - A bitwise OR of TRANSIENT and/or OVERRIDE. These bits will be or'd with the default mode used in IDataObject.setValue(Object, Object, int).

See Also:

merge(IDataObject, IDataObject, int, boolean)

merge

public static void merge(IDataObject source,
                         IDataObject target,
                         int orMode,
                         boolean equalise)

Merge a source object into a target object. Recursively merges embedded IDataObject's.

NOTE: this has the potential to cause aliasing bugs if the source object continues to be used after merging with target. If the source object is going to continue to be used after merge, it is recommended to deepClone(IDataObject) a copy and pass the copy to this method.

Parameters:

source - The source to merge from.

target - The target to merge to.

orMode - A bitwise OR of TRANSIENT and/or OVERRIDE. These bits will be or'd with the default mode used in IDataObject.setValue(Object, Object, int).

equalise - If true then the property set of target is made equal to that of the source source by deleting any properties in target that are not in the source. i.e. the target becomes a logical copy of source. This can be used to generate the minimal number of changes needed to change target into source. If false, then target becomes a union of the property sets of source and target.

propertySet

public static Set<String> propertySet(IDataObject object)

Shorcut to create a copy of the current property set of a data object.

Parameters:

object - The data object

Returns:

A snapshot of the object's property set.

See Also:

IDataObject.propertyIterator(), IDataBean.getPropertyNames(), valueSet(IDataObject)

valueSet

public static Set valueSet(IDataObject object)

Shorcut to create a copy of the current set of values of a data object.

Parameters:

object - The data object

Returns:

A snapshot of the object's value set.

See Also:

IDataObject.propertyIterator(), IDataBean.getPropertyNames(), propertySet(IDataObject)

registerChildValue

public static void registerChildValue(IDataObjectChildListener parent,
                                      Object property,
                                      Object value)

Provides support for data object implementations in propagating child events. Registers a child property value for event propagation if it is an IDataBean (taking into account the semantics required by IDataObjectLink). When a child's property changes, the IDataObjectChildListener.childPropertyChanged(Object, PropertyEvent) method on the parent is called. Data object implementations usually call this when a new property value is added with setValue ().

Parameters:

parent - The parent data object.

property - The property name of the child.

value - The child property value.

See Also:

unregisterChildValue(IDataObjectChildListener, Object)

unregisterChildValue

public static void unregisterChildValue(IDataObjectChildListener parent,
                                        Object value)

Reverses the effect of registerChildValue(IDataObjectChildListener, Object, Object). Data object implementations usually call this when a a property value is removed.

Parameters:

parent - The parent data object.

value - The property value to remove.

See Also:

registerChildValue(IDataObjectChildListener, Object, Object)

isSoftLink

public static boolean isSoftLink(Object value)

Test if an object is a soft link (i.e. an IDataObjectLink with IDataObjectLink.isSoftLink() returns true).