org.hydrateframework
Class ObjectIndex

java.lang.Object
  org.hydrateframework.ObjectIndex

Direct Known Subclasses:

UniqueIndex

public abstract class ObjectIndex
extends java.lang.Object

This is the abstract base class for the indexes used to look up objects in the object context. It contains a lookup that uses keys of a particular class to look up one or more objects of another class.

Version:

@(#)$Revision: 1.3 $

Author:

David Chamberlin

Field Summary

protected java.lang.Class	m_cls The class that this object will be indexing.
protected ObjectContext	m_ctx
protected java.lang.Class	m_keyCls

Constructor Summary

protected	ObjectIndex(java.lang.Class cls) This constructor builds an index to hold objects of a particular class
protected	ObjectIndex(java.lang.Class clsToIndex, java.lang.Class keyClass) Create an index object

Method Summary

void	addObject(java.lang.Object obj) Add an object to this index.
abstract void	addObject(java.lang.Object obj, ObjectKey key) Add an object to the index with the given key.
abstract void	clear() Clear the index.
java.io.PrintStream	dump(java.io.PrintStream out) Output details of the index to a PrintStream.
boolean	equals(java.lang.Object o) Tests to see if two indexes are the same.
abstract java.lang.Object	findObject(ObjectKey key) This abstract method should be implemented to find an object given a key.
abstract ObjectCollection	findObjects(ObjectKey key) This method should be implemented to find a collection of business objects given a key.
java.lang.Class	getClassToIndex() Gets the class that will be indexed.
java.lang.Class	getKeyClass() Return the key class that is being used in the index
ObjectKey	keyFromObject(java.lang.Object obj) Get a key given a (hydrate) object.
abstract java.util.Iterator	keys() return an iterator that can enumerate the keys held in this index object.
abstract java.lang.Object	removeKey(ObjectKey key) Remove the entire contents of a particular key in this index.
void	removeObject(java.lang.Object obj) Remove an object from the index.
abstract void	removeObject(java.lang.Object obj, ObjectKey key) Remove an object from the index using the given key.
protected void	setObjectContext(ObjectContext ctx) Establish the object context for a particular index
abstract int	size()

Methods inherited from class java.lang.Object

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

Field Detail

m_cls

protected java.lang.Class m_cls

The class that this object will be indexing.

m_keyCls

protected java.lang.Class m_keyCls

m_ctx

protected ObjectContext m_ctx

Constructor Detail

ObjectIndex

protected ObjectIndex(java.lang.Class cls)

This constructor builds an index to hold objects of a particular class

Parameters:

cls - the class of object which should be the base interface in the object heirarchy. For example if you are indexing manager and staff objects, both derived from employee, use employee for this class. Note this means that there will be only one primary key index for all classes in a particular hierarchy.

ObjectIndex

protected ObjectIndex(java.lang.Class clsToIndex,
                      java.lang.Class keyClass)

Create an index object

Parameters:

clsToIndex - the class that should be indexed

keyClass - the key class to use

Method Detail

setObjectContext

protected void setObjectContext(ObjectContext ctx)

Establish the object context for a particular index

Parameters:

ctx - the new owning context

getClassToIndex

public java.lang.Class getClassToIndex()

Gets the class that will be indexed. This method gives an answer to the question: what kind of object does this index hold instances of. If the object being indexed is part of a hierarchy then this class will be the top level (least derived) class from that hierarchy. For example for a hierarchy in which manager and staff are both derived from employee, this method would return the employee class for indexes that index both manager and staff objects (in the case of the primary key there will be only one index to index both kinds of object)

Returns:

the class of the objects in the index

getKeyClass

public java.lang.Class getKeyClass()

Return the key class that is being used in the index

Returns:

the key class

equals

public boolean equals(java.lang.Object o)

Tests to see if two indexes are the same. They are deemed to be the same if the class to index is the same, the key class is the same and the index 'foreign key name' is the same. Note that this means that there is only one primary key index for all objects in a particular class hierarchy.

Overrides:

equals in class java.lang.Object

Parameters:

o - the BusObjIndex object against which to test equality

Returns:

true if the objects are equivalent

keyFromObject

public ObjectKey keyFromObject(java.lang.Object obj)

Get a key given a (hydrate) object.

Parameters:

obj - The object for which a key is required. This would normally be an HydrateObject

Returns:

the key value which could be used to index an object within this index.

dump

public java.io.PrintStream dump(java.io.PrintStream out)

Output details of the index to a PrintStream.

Parameters:

out - where to send the output

Returns:

the same output device

findObject

public abstract java.lang.Object findObject(ObjectKey key)

This abstract method should be implemented to find an object given a key. It always returns a single object.

Parameters:

key - the key to use on the index

Returns:

the business object found or null if there was object with the given key in the index.

findObjects

public abstract ObjectCollection findObjects(ObjectKey key)

This method should be implemented to find a collection of business objects given a key. It is not guaranteed to return anything if the index is a one-to-one index.

Parameters:

key - the key to use on the index

Returns:

the business object collection found or a new empty collection if none was found.

addObject

public void addObject(java.lang.Object obj)

Add an object to this index. For primary key indexes, the key to use is taken straight from the object. For alternate and foreign key indexes, the ForeignKey interface is used to find a key from the object. Note that this add method does not work for many-to-many relationships where the key to use cannot be read from the object being added.

Parameters:

obj - the object to add to the index

addObject

public abstract void addObject(java.lang.Object obj,
                               ObjectKey key)

Add an object to the index with the given key. This is the only way to add objects to indexes which represent one or other side of a many-to-many relationship.

Parameters:

obj - the object to add to the index

key - the key to use in adding the object

removeObject

public void removeObject(java.lang.Object obj)

Remove an object from the index.

Parameters:

obj - the object to be removed.

removeObject

public abstract void removeObject(java.lang.Object obj,
                                  ObjectKey key)

Remove an object from the index using the given key.

Parameters:

obj - the object to be removed

key - the key to be used to find the object

removeKey

public abstract java.lang.Object removeKey(ObjectKey key)

Remove the entire contents of a particular key in this index. For unique indexes, this will remove a business object, for mutiple indexes, this will remove a collection of business objects. This call is used when the key value of an object changes and it needs to be re-indexed.

Parameters:

key - the key to be removed

Returns:

the object associated with the given key or null if none was found.

keys

public abstract java.util.Iterator keys()

return an iterator that can enumerate the keys held in this index object. The objects returned by the Iterator will be of class ObjectKey.

Returns:

an iterator for keys.

size

public abstract int size()

Returns:

the number of items in this index

clear

public abstract void clear()

Clear the index.