org.eclipse.persistence.indirection

Class IndirectSet<E>

java.lang.Object

org.eclipse.persistence.indirection.IndirectSet<E>

Type Parameters:

E - the type of elements maintained by this set

All Implemented Interfaces:

Serializable, Cloneable, Iterable<E>, Collection<E>, Set<E>, ChangeTracker, CollectionChangeTracker, IndirectCollection, IndirectContainer

Direct Known Subclasses:

IndirectSet

public class IndirectSet<E>
extends Object
implements CollectionChangeTracker, Set<E>, IndirectCollection, Cloneable, Serializable

IndirectSet is an example implementation of the Set protocol that allows a domain class to take advantage of TopLink Indirection without having to declare its instance variable as a ValueHolderInterface.

To use an IndirectSet:

• Declare the appropriate instance variable with type Set (or Collection).
• Send the message #useTransparentCollection() to the appropriate CollectionMapping.
• Send the message #useCollectionClass(IndirectSet.class) to the same CollectionMapping. (The order of these two message sends is significant.)

TopLink will place an IndirectSet in the instance variable when the containing domain object is read from the datatabase. With the first message sent to the IndirectSet, the contents are fetched from the database and normal Set behavior is resumed.

Implementation notes:

• The Set interface is implemented by delegating nearly every message to the Set held on to by the 'delegate' instance variable. (The 'delegate' will be either a HashSet or yet another IndirectSet.)
• The IndirectContainer interface is implemented in a straightforward fashion:
  • #get- and #setValueHolder() are implemented as simple accessors for the 'valueHolder' instance variable. (Note that #setValueHolder() clears out the 'delegate' instance variable, since its contents are invalidated by the arrival of a new value holder.)
  • #isInstantiated() is simply delegated to the value holder.
• TopLink requires that the Cloneable interface be implemented. The #clone() method must clone the 'delegate'. (The implementation here uses reflection to invoke the #clone() method because it is not included in the common interface shared by IndirectSet and its base delegate class, HashSet; namely, Set.)
• TopLink requires that the Serializable interface be implemented.
• The database read is ultimately triggered when one of the "delegated" methods makes the first call to #getDelegate(), which in turn calls #buildDelegate(), which sends the message #getValue() to the value holder. The value holder performs the database read.
• For debugging purposes, #toString() will not trigger a database read. This is not required behavior.

Since:

TOPLink/Java 3.0+

Author:

Big Country

See Also:

CollectionMapping, Serialized Form

Constructor Summary

Constructors

Constructor and Description
IndirectSet() Construct an empty IndirectSet.
IndirectSet(Collection<? extends E> c) Construct an IndirectSet containing the elements of the specified collection.
IndirectSet(int initialCapacity) Construct an empty IndirectSet with the specified initial capacity.
IndirectSet(int initialCapacity, float loadFactor) Construct an empty IndirectSet with the specified initial capacity and load factor.

Method Summary

Modifier and Type	Method and Description
PropertyChangeListener	_persistence_getPropertyChangeListener() INTERNAL: Return the property change listener for change tracking.
void	_persistence_setPropertyChangeListener(PropertyChangeListener changeListener) INTERNAL: Set the property change listener for change tracking.
boolean	add(E element)
boolean	addAll(Collection<? extends E> c)
void	clear()
void	clearDeferredChanges() INTERNAL: clear any changes that have been deferred to instantiation.
Object	clone()
boolean	contains(Object element)
boolean	containsAll(Collection<?> c)
boolean	equals(Object o)
Collection	getAddedElements() INTERNAL: Return the elements that have been added before instantiation.
Object	getDelegateObject() INTERNAL: Return the real collection object.
Collection	getRemovedElements() INTERNAL: Return the elements that have been removed before instantiation.
String	getTrackedAttributeName() INTERNAL: Return the mapping attribute name, used to raise change events.
ValueHolderInterface	getValueHolder() INTERNAL: Return the valueHolder.
boolean	hasAddedElements() INTERNAL: Return if any elements that have been added before instantiation.
boolean	hasBeenRegistered() INTERNAL: Return whether this IndirectSet has been registered in a UnitOfWork
boolean	hasDeferredChanges() INTERNAL: Return if any elements that have been added or removed before instantiation.
int	hashCode()
boolean	hasRemovedElements() INTERNAL: Return if any elements that have been removed before instantiation.
boolean	hasTrackedPropertyChangeListener() INTERNAL: Return if the collection has a property change listener for change tracking.
boolean	isEmpty()
boolean	isInstantiated() Return whether the contents have been read from the database.
Iterator<E>	iterator()
boolean	remove(Object element)
boolean	removeAll(Collection<?> c)
boolean	retainAll(Collection<?> c)
void	setTrackedAttributeName(String attributeName) INTERNAL: Set the mapping attribute name, used to raise change events.
void	setUseLazyInstantiation(boolean useLazyInstantiation) INTERNAL Set whether this collection should attempt do deal with adds and removes without retrieving the collection from the dB
void	setValueHolder(ValueHolderInterface valueHolder) INTERNAL: Set the value holder.
int	size()
Object[]	toArray()
<E> E[]	toArray(E[] a)
String	toString() Use the delegate's #toString(); but wrap it with braces to indicate there is a bit of indirection.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Set

spliterator

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Constructor Detail

IndirectSet

public IndirectSet()

Construct an empty IndirectSet.

IndirectSet

public IndirectSet(int initialCapacity)

Construct an empty IndirectSet with the specified initial capacity.

Parameters:

initialCapacity - the initial capacity of the set

Throws:

IllegalArgumentException - if the specified initial capacity is negative

IndirectSet

public IndirectSet(int initialCapacity,
                   float loadFactor)

Construct an empty IndirectSet with the specified initial capacity and load factor.

Parameters:

initialCapacity - the initial capacity of the set

loadFactor - the load factor of the set

Throws:

IllegalArgumentException - if the specified initial capacity is negative

IndirectSet

public IndirectSet(Collection<? extends E> c)

Construct an IndirectSet containing the elements of the specified collection.

Parameters:

c - the initial elements of the set

Method Detail

add

public boolean add(E element)

Specified by:

add in interface Collection<E>

Specified by:

add in interface Set<E>

See Also:

Set.add(java.lang.Object)

addAll

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

Specified by:

addAll in interface Collection<E>

Specified by:

addAll in interface Set<E>

See Also:

Set.addAll(java.util.Collection)

clear

public void clear()

Specified by:

clear in interface Collection<E>

Specified by:

clear in interface Set<E>

See Also:

Set.clear()

clearDeferredChanges

public void clearDeferredChanges()

INTERNAL: clear any changes that have been deferred to instantiation. Indirect collections with change tracking avoid instantiation on add/remove.

Specified by:

clearDeferredChanges in interface IndirectCollection

clone

public Object clone()

Overrides:

clone in class Object

See Also:

This will result in a database query if necessary.

contains

public boolean contains(Object element)

Specified by:

contains in interface Collection<E>

Specified by:

contains in interface Set<E>

See Also:

Set.contains(java.lang.Object)

containsAll

public boolean containsAll(Collection<?> c)

Specified by:

containsAll in interface Collection<E>

Specified by:

containsAll in interface Set<E>

See Also:

Set.containsAll(java.util.Collection)

equals

public boolean equals(Object o)

Specified by:

equals in interface Collection<E>

Specified by:

equals in interface Set<E>

Overrides:

equals in class Object

See Also:

Set.equals(java.lang.Object)

getDelegateObject

public Object getDelegateObject()

INTERNAL: Return the real collection object. This will force instantiation.

Specified by:

getDelegateObject in interface IndirectCollection

getValueHolder

public ValueHolderInterface getValueHolder()

INTERNAL: Return the valueHolder.

Specified by:

getValueHolder in interface IndirectContainer

Returns:

org.eclipse.persistence.indirection.ValueHolderInterface A representation of the valueholder * which this container uses

hasBeenRegistered

public boolean hasBeenRegistered()

INTERNAL: Return whether this IndirectSet has been registered in a UnitOfWork

hashCode

public int hashCode()

Specified by:

hashCode in interface Collection<E>

Specified by:

hashCode in interface Set<E>

Overrides:

hashCode in class Object

See Also:

Set.hashCode()

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Collection<E>

Specified by:

isEmpty in interface Set<E>

See Also:

Set.isEmpty()

isInstantiated

public boolean isInstantiated()

Return whether the contents have been read from the database.

Specified by:

isInstantiated in interface IndirectContainer

iterator

public Iterator<E> iterator()

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface Collection<E>

Specified by:

iterator in interface Set<E>

See Also:

Set.iterator()

remove

public boolean remove(Object element)

Specified by:

remove in interface Collection<E>

Specified by:

remove in interface Set<E>

See Also:

Set.remove(java.lang.Object)

removeAll

public boolean removeAll(Collection<?> c)

Specified by:

removeAll in interface Collection<E>

Specified by:

removeAll in interface Set<E>

See Also:

Set.removeAll(java.util.Collection)

retainAll

public boolean retainAll(Collection<?> c)

Specified by:

retainAll in interface Collection<E>

Specified by:

retainAll in interface Set<E>

See Also:

Set.retainAll(java.util.Collection)

setValueHolder

public void setValueHolder(ValueHolderInterface valueHolder)

INTERNAL: Set the value holder. Note that the delegate must be cleared out.

Specified by:

setValueHolder in interface IndirectContainer

setUseLazyInstantiation

public void setUseLazyInstantiation(boolean useLazyInstantiation)

INTERNAL Set whether this collection should attempt do deal with adds and removes without retrieving the collection from the dB

Specified by:

setUseLazyInstantiation in interface IndirectCollection

size

public int size()

Specified by:

size in interface Collection<E>

Specified by:

size in interface Set<E>

See Also:

Set.size()

toArray

public Object[] toArray()

Specified by:

toArray in interface Collection<E>

Specified by:

toArray in interface Set<E>

See Also:

Set.toArray()

toArray

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

Specified by:

toArray in interface Collection<E>

Specified by:

toArray in interface Set<E>

See Also:

Set.toArray(java.lang.Object[])

toString

public String toString()

Use the delegate's #toString(); but wrap it with braces to indicate there is a bit of indirection. Don't allow this method to trigger a database read.

Overrides:

toString in class Object

See Also:

AbstractCollection.toString()

_persistence_getPropertyChangeListener

public PropertyChangeListener _persistence_getPropertyChangeListener()

INTERNAL: Return the property change listener for change tracking.

Specified by:

_persistence_getPropertyChangeListener in interface ChangeTracker

hasTrackedPropertyChangeListener

public boolean hasTrackedPropertyChangeListener()

INTERNAL: Return if the collection has a property change listener for change tracking.

_persistence_setPropertyChangeListener

public void _persistence_setPropertyChangeListener(PropertyChangeListener changeListener)

INTERNAL: Set the property change listener for change tracking.

Specified by:

_persistence_setPropertyChangeListener in interface ChangeTracker

getTrackedAttributeName

public String getTrackedAttributeName()

INTERNAL: Return the mapping attribute name, used to raise change events.

Specified by:

getTrackedAttributeName in interface CollectionChangeTracker

setTrackedAttributeName

public void setTrackedAttributeName(String attributeName)

INTERNAL: Set the mapping attribute name, used to raise change events. This is required if the change listener is set.

Specified by:

setTrackedAttributeName in interface CollectionChangeTracker

getRemovedElements

public Collection getRemovedElements()

INTERNAL: Return the elements that have been removed before instantiation.

Specified by:

getRemovedElements in interface IndirectCollection

getAddedElements

public Collection getAddedElements()

INTERNAL: Return the elements that have been added before instantiation.

Specified by:

getAddedElements in interface IndirectCollection

hasAddedElements

public boolean hasAddedElements()

INTERNAL: Return if any elements that have been added before instantiation.

hasRemovedElements

public boolean hasRemovedElements()

INTERNAL: Return if any elements that have been removed before instantiation.

hasDeferredChanges

public boolean hasDeferredChanges()

INTERNAL: Return if any elements that have been added or removed before instantiation.

Specified by:

hasDeferredChanges in interface IndirectCollection