org.hydrateframework
Class ObjectCollection<E extends HydrateObject>

java.lang.Object
  org.hydrateframework.ObjectCollection<E>

All Implemented Interfaces:

java.lang.Iterable<E>, java.util.Collection<E>, java.util.Set<E>

public abstract class ObjectCollection<E extends HydrateObject>
extends java.lang.Object
implements java.util.Set<E>

This class is used to represent a collection of hydrate objects. The class implements the Collection interface for objects of class HydrateObject. The class is abstract and each '-to-many' reference defined in the class definition which is represented by a collection in the generated code will have its own concrete implementation of this class to support it. The implementation of this collection is always a set, and it uses two strategies for guaranteeing uniqueness. For small lists with a number of attributes less than or equal to a threshold value (=16), the set is held as a dynamically resizing array which doubles in size each time the limit is hit. This is an efficient way of storing the data in the set, but requires the array to be scanned each time a new element is added to ensure it is not in the set already. Beyond this size, the set automatically reconfigures itself into a HashSet, which is more expensive to create, and uses more memory, but avoids the scan when adding new elements.

Version:

@(#)$Revision: 1.8 $

Author:

David Chamberlin

Nested Class Summary

class	ObjectCollection.Iter This nested class implements an iterator that can be used to scan a business object collection.
class	ObjectCollection.IterHs This nested class implements an iterator that can be used to scan an object collection.

Field Summary

protected java.lang.Class	m_cls The type of object held by this collection
protected java.lang.Object	m_list The array or hashset holding the list of business objects.
protected static org.apache.commons.logging.Log	m_log
protected java.lang.String	m_nm The name of the collection.
protected static int	SIZETHRESH The threshold above which a hash map is used to store this collection.

Constructor Summary

protected

ObjectCollection(java.lang.Class cls, java.lang.String nm) The constructor is called by derived versions of this abstract class

Method Summary

boolean	addAll(java.util.Collection<? extends E> c) This implements the addAll method of the Collection interface.
boolean	addInit(E o) This call adds an object to this collection without worrying about reverse links etc.
boolean	addMTM(E o, boolean reverse) Add an object to this collection that is part of a many-to-many relationship.
void	clear() This implements the clear method of the Collection interface.
boolean	contains(java.lang.Object o) This implements the contains method of the Collection interface.
boolean	containsAll(java.util.Collection<?> c) This implements the containsAll method of the Collection interface.
boolean	equals(java.lang.Object o) This implements the equals method of the Collection interface.
protected java.util.Set<ObjectRelationshipFactory.RelationshipMap>	getMTM(ObjectContext ctx) Return the list of changes to the many-to-many relationship table.
java.lang.String	getName()
protected abstract E	getOwner() Collections are owned by the object in which they exist.
boolean	isEmpty()
java.util.Iterator<E>	iterator()
boolean	remove(java.lang.Object o) This implements the remove method of the Collection interface.
boolean	removeAll(java.util.Collection<?> c) This implements the removeAll method of the Collection interface.
java.lang.Object	removeInit(java.lang.Object o) Remove a business object from this collection.
boolean	removeMTM(HydrateObject o, boolean reverse) Remove an object from the collection which forms part of a many to many relationship.
protected abstract void	removeRefs(E o) The implementation of the removeRefs method will fix up any reverse references that may exist for this object.
boolean	retainAll(java.util.Collection<?> c) This implements the retainAll method of the Collection interface.
void	save(SaveContext sc)
int	size() This implements the size method of the Collection interface
java.lang.Object[]	toArray() This implements the toArray method of the Collection interface.
<T> T[]	toArray(T[] a) This implements the toArray(Object[]) method of the Collection interface

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Set

add, hashCode

Field Detail

m_log

protected static final org.apache.commons.logging.Log m_log

SIZETHRESH

protected static final int SIZETHRESH

The threshold above which a hash map is used to store this collection.

See Also:

Constant Field Values

m_list

protected java.lang.Object m_list

The array or hashset holding the list of business objects. Objects are not necessarily stored sequentially since when an object is removed, its slot in the array is simply set to null.

m_nm

protected java.lang.String m_nm

The name of the collection. This is important because it matces the name of the one-to-many index that uses this collection.

m_cls

protected java.lang.Class m_cls

The type of object held by this collection

Constructor Detail

ObjectCollection

protected ObjectCollection(java.lang.Class cls,
                           java.lang.String nm)

The constructor is called by derived versions of this abstract class

Parameters:

cls - the interface representing the business object that the collection will hold.

nm - the name of the collection is usually a short version of the name of the business object relationship that requires it.

Method Detail

removeRefs

protected abstract void removeRefs(E o)

The implementation of the removeRefs method will fix up any reverse references that may exist for this object. For example if an employee is in one department, and a department has many employees, the department will have a getEmployeeColl member that will return an ObjectCollection and the employee will have an initDepartment method that takes a Department object. When an employee is removed from the department, this method is called on the collection returned by getEmployeeColl and it must also call initDepartment(null) on the employee being added In the case of many-to-many relationships, the implementation code must also worry about calling removeMTM to ensure that the many-to-many relationship table is kept up-to-date.

Parameters:

o - the object to be removed from the collection.

getOwner

protected abstract E getOwner()

Collections are owned by the object in which they exist. This call should return that object. For example, a department has many employees so the Collection that holds the list of employees for a particular department is owned by that department object.

Returns:

the owning business object

getMTM

protected java.util.Set<ObjectRelationshipFactory.RelationshipMap> getMTM(ObjectContext ctx)

Return the list of changes to the many-to-many relationship table. This call will only be used where the collection represents one side of a many-to-many relationship.

Returns:

the list of ManyToManyMap objects that represent the changes to be made to the relationship table that have not been committed to the database.

addMTM

public boolean addMTM(E o,
                      boolean reverse)

Add an object to this collection that is part of a many-to-many relationship. This call is very similar to addInit(E) except that it also adds a request to add a row to the many-to-many relationship table. This request will be executed when this collection is saved in the database.

Parameters:

o - the object that is being added to this collection

reverse - true if the relationship is being populated 'right to left' or false if it is being populated 'left to right'

Returns:

true if added successfully

removeMTM

public boolean removeMTM(HydrateObject o,
                         boolean reverse)

Remove an object from the collection which forms part of a many to many relationship. This call is similar to removeInit(java.lang.Object) except that it also adds a requires to remove a row to the many-to-many relationship table. It also checks the current list of requests to see if the remove request cancels an unexecuted add request. outstanding requests will be executed when this collection is saved in the database.

Parameters:

o - the object to be removed.

reverse - true if the relationship is being populated 'right to left' or false if it is being populated 'left to right'

Returns:

true if removed successfully

addInit

public boolean addInit(E o)

This call adds an object to this collection without worrying about reverse links etc.

Parameters:

o - the object to be added

Returns:

true if the object was added. If false is returned, it may be because the object was null, or the set already contained this object

getName

public java.lang.String getName()

save

public void save(SaveContext sc)
          throws SaveException

Throws:

SaveException

removeInit

public java.lang.Object removeInit(java.lang.Object o)

Remove a business object from this collection. Unlike the remove call, this does not attempt to maintain the integrity of any reverse links. It is used internally for managing indexes, and is called by the remove call which does maintain integrity.

Parameters:

o - the business object to be removed (or an object with a matching key)

Returns:

the business object actually removed or null if none was found

addAll

public boolean addAll(java.util.Collection<? extends E> c)

This implements the addAll method of the Collection interface.

Specified by:

addAll in interface java.util.Collection<E extends HydrateObject>

Specified by:

addAll in interface java.util.Set<E extends HydrateObject>

Parameters:

c - the collection of objects to add which must all be BusObject objects.

Returns:

true if successful.

clear

public void clear()

This implements the clear method of the Collection interface.

Specified by:

clear in interface java.util.Collection<E extends HydrateObject>

Specified by:

clear in interface java.util.Set<E extends HydrateObject>

contains

public boolean contains(java.lang.Object o)

This implements the contains method of the Collection interface.

Specified by:

contains in interface java.util.Collection<E extends HydrateObject>

Specified by:

contains in interface java.util.Set<E extends HydrateObject>

Parameters:

o - the object to search for

Returns:

true if the collection contains this object. Two business objects are deemed to be equal if they share the same key value.

containsAll

public boolean containsAll(java.util.Collection<?> c)

This implements the containsAll method of the Collection interface.

Specified by:

containsAll in interface java.util.Collection<E extends HydrateObject>

Specified by:

containsAll in interface java.util.Set<E extends HydrateObject>

Parameters:

c - the collection containing objects to search for

Returns:

true if the collection contains all the objects in the given collection. Two business objects are deemed to be equal if they share the same key value.

equals

public boolean equals(java.lang.Object o)

This implements the equals method of the Collection interface.

Specified by:

equals in interface java.util.Collection<E extends HydrateObject>

Specified by:

equals in interface java.util.Set<E extends HydrateObject>

Overrides:

equals in class java.lang.Object

Parameters:

o - A collection against which equlity is tested.

Returns:

true if the collection contains all the objects and only the objects in the given collection. Two business objects are deemed to be equal if they share the same key value.

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Collection<E extends HydrateObject>

Specified by:

isEmpty in interface java.util.Set<E extends HydrateObject>

Returns:

true if the collection has no elements

iterator

public java.util.Iterator<E> iterator()

Specified by:

iterator in interface java.lang.Iterable<E extends HydrateObject>

Specified by:

iterator in interface java.util.Collection<E extends HydrateObject>

Specified by:

iterator in interface java.util.Set<E extends HydrateObject>

Returns:

an Iterator that can be used to scan the objects in this collection.

remove

public boolean remove(java.lang.Object o)

This implements the remove method of the Collection interface. It finds the given business object and calls removeRefs(E)

Specified by:

remove in interface java.util.Collection<E extends HydrateObject>

Specified by:

remove in interface java.util.Set<E extends HydrateObject>

Parameters:

o - the object to remove

Returns:

true if successful, false is not found.

removeAll

public boolean removeAll(java.util.Collection<?> c)

This implements the removeAll method of the Collection interface. It removes all objects in the given collection

Specified by:

removeAll in interface java.util.Collection<E extends HydrateObject>

Specified by:

removeAll in interface java.util.Set<E extends HydrateObject>

Parameters:

c - the list of objects to remove

Returns:

true if at least one object was successfully.

retainAll

public boolean retainAll(java.util.Collection<?> c)

This implements the retainAll method of the Collection interface.

Specified by:

retainAll in interface java.util.Collection<E extends HydrateObject>

Specified by:

retainAll in interface java.util.Set<E extends HydrateObject>

Parameters:

c - the list of objects to retain

Returns:

true

size

public int size()

This implements the size method of the Collection interface

Specified by:

size in interface java.util.Collection<E extends HydrateObject>

Specified by:

size in interface java.util.Set<E extends HydrateObject>

Returns:

the number of objects in the collection.

toArray

public java.lang.Object[] toArray()

This implements the toArray method of the Collection interface.

Specified by:

toArray in interface java.util.Collection<E extends HydrateObject>

Specified by:

toArray in interface java.util.Set<E extends HydrateObject>

Returns:

the list of objects as an array

toArray

public <T> T[] toArray(T[] a)

This implements the toArray(Object[]) method of the Collection interface

Specified by:

toArray in interface java.util.Collection<E extends HydrateObject>

Specified by:

toArray in interface java.util.Set<E extends HydrateObject>

Parameters:

a - a template for the type of array to return (which is used as the return value if there is enough space in it).

Returns:

the list of objects as an array of the same type as a