IndirectSet (EclipseLink 3.0.0, API Reference)

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<E,Set<E>>, IndirectContainer<Set<E>>
```
public class IndirectSet<E>
extends Object
implements CollectionChangeTracker, Set<E>, IndirectCollection<E,Set<E>>, 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 database. 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.
See Also:

CollectionMapping, Serialized Form

Author:

Big Country

Since:

TOPLink/Java 3.0+

Field Summary

Fields
Modifier and Type Field and Description

protected int initialCapacity
Store initial size for lazy init.

protected float loadFactor
Store load factor for lazy init.

Fields
Modifier and Type	Field and Description
`protected int`	`initialCapacity` Store initial size for lazy init.
`protected float`	`loadFactor` Store load factor for lazy init.

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

All Methods Instance Methods Concrete Methods
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)`
`protected Set<E>`	`buildDelegate()` INTERNAL: Return the freshly-built delegate.
`void`	`clear()`
`void`	`clearDeferredChanges()` INTERNAL: clear any changes that have been deferred to instantiation.
`Object`	`clone()`
`protected Set<E>`	`cloneDelegate()` INTERNAL: Clone the delegate.
`boolean`	`contains(Object element)`
`boolean`	`containsAll(Collection<?> c)`
`boolean`	`equals(Object o)`
`void`	`forEach(Consumer<? super E> action)`
`Collection<E>`	`getAddedElements()` INTERNAL: Return the elements that have been added before instantiation.
`protected Set<E>`	`getDelegate()` INTERNAL: Check whether the contents have been read from the database.
`Set<E>`	`getDelegateObject()` INTERNAL: Return the real collection object.
`Collection<E>`	`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<Set<E>>`	`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.
`protected boolean`	`isRelationshipMaintenanceRequired()`
`Iterator<E>`	`iterator()`
`Stream<E>`	`parallelStream()`
`protected void`	`raiseAddChangeEvent(Object element)` Raise the add change event and relationship maintainence.
`protected void`	`raiseRemoveChangeEvent(Object element)` Raise the remove change event.
`boolean`	`remove(Object element)`
`boolean`	`removeAll(Collection<?> c)`
`boolean`	`removeIf(Predicate<? super E> filter)`
`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<Set<E>> valueHolder)` INTERNAL: Set the value holder.
`protected boolean`	`shouldAvoidInstantiation()` INTERNAL: Return if add/remove should trigger instantiation or avoid.
`protected boolean`	`shouldUseLazyInstantiation()` Return whether this collection should attempt do deal with adds and removes without retrieving the collection from the dB
`int`	`size()`
`Spliterator<E>`	`spliterator()`
`Stream<E>`	`stream()`
`Object[]`	`toArray()`
`<T> T[]`	`toArray(T[] 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
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - initialCapacity
```
protected int initialCapacity
```
    Store initial size for lazy init.
  - loadFactor
```
protected float loadFactor
```
    Store load factor for lazy init.
- 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
  - isRelationshipMaintenanceRequired
```
protected boolean isRelationshipMaintenanceRequired()
```
  - 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)
  - buildDelegate
```
protected Set<E> buildDelegate()
```
    INTERNAL: Return the freshly-built delegate.
  - 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<E,Set<E>>
  - clone
```
public Object clone()
```
    Overrides:
    
    clone in class Object
    
    See Also:
    
    This will result in a database query if necessary.
  - cloneDelegate
```
protected Set<E> cloneDelegate()
```
    INTERNAL: Clone the delegate.
  - 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)
  - spliterator
```
public Spliterator<E> spliterator()
```
    Specified by:
    
    spliterator in interface Iterable<E>
    
    Specified by:
    
    spliterator in interface Collection<E>
    
    Specified by:
    
    spliterator in interface Set<E>
  - parallelStream
```
public Stream<E> parallelStream()
```
    Specified by:
    
    parallelStream in interface Collection<E>
  - stream
```
public Stream<E> stream()
```
    Specified by:
    
    stream in interface Collection<E>
  - removeIf
```
public boolean removeIf(Predicate<? super E> filter)
```
    Specified by:
    
    removeIf in interface Collection<E>
  - forEach
```
public void forEach(Consumer<? super E> action)
```
    Specified by:
    
    forEach in interface Iterable<E>
  - getDelegate
```
protected Set<E> getDelegate()
```
    INTERNAL: Check whether the contents have been read from the database. If they have not, read them and set the delegate.
  - getDelegateObject
```
public Set<E> getDelegateObject()
```
    INTERNAL: Return the real collection object. This will force instantiation.
    
    Specified by:
    
    getDelegateObject in interface IndirectCollection<E,Set<E>>
  - getValueHolder
```
public ValueHolderInterface<Set<E>> getValueHolder()
```
    INTERNAL: Return the valueHolder.
    
    Specified by:
    
    getValueHolder in interface IndirectContainer<Set<E>>
    
    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<Set<E>>
  - 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<Set<E>> valueHolder)
```
    INTERNAL: Set the value holder. Note that the delegate must be cleared out.
    
    Specified by:
    
    setValueHolder in interface IndirectContainer<Set<E>>
  - 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<E,Set<E>>
  - size
```
public int size()
```
    Specified by:
    
    size in interface Collection<E>
    
    Specified by:
    
    size in interface Set<E>
    
    See Also:
    
    Set.size()
  - shouldUseLazyInstantiation
```
protected boolean shouldUseLazyInstantiation()
```
    Return whether this collection should attempt do deal with adds and removes without retrieving the collection from the dB
    
    Returns:
  - toArray
```
public Object[] toArray()
```
    Specified by:
    
    toArray in interface Collection<E>
    
    Specified by:
    
    toArray in interface Set<E>
    
    See Also:
    
    Set.toArray()
  - toArray
```
public <T> T[] toArray(T[] 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()
  - raiseAddChangeEvent
```
protected void raiseAddChangeEvent(Object element)
```
    Raise the add change event and relationship maintainence.
  - raiseRemoveChangeEvent
```
protected void raiseRemoveChangeEvent(Object element)
```
    Raise the remove change event.
  - _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<E> getRemovedElements()
```
    INTERNAL: Return the elements that have been removed before instantiation.
    
    Specified by:
    
    getRemovedElements in interface IndirectCollection<E,Set<E>>
  - getAddedElements
```
public Collection<E> getAddedElements()
```
    INTERNAL: Return the elements that have been added before instantiation.
    
    Specified by:
    
    getAddedElements in interface IndirectCollection<E,Set<E>>
  - 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<E,Set<E>>
  - shouldAvoidInstantiation
```
protected boolean shouldAvoidInstantiation()
```
    INTERNAL: Return if add/remove should trigger instantiation or avoid. Current instantiation is avoided is using change tracking.

Class IndirectSet<E>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

initialCapacity

loadFactor

Constructor Detail

IndirectSet

IndirectSet

IndirectSet

IndirectSet

Method Detail

isRelationshipMaintenanceRequired

add

addAll

buildDelegate

clear

clearDeferredChanges

clone

cloneDelegate

contains

containsAll

equals

spliterator

parallelStream

stream

removeIf

forEach

getDelegate

getDelegateObject

getValueHolder

hasBeenRegistered

hashCode

isEmpty

isInstantiated

iterator

remove

removeAll

retainAll

setValueHolder

setUseLazyInstantiation

size

shouldUseLazyInstantiation

toArray

toArray

toString

raiseAddChangeEvent

raiseRemoveChangeEvent

_persistence_getPropertyChangeListener

hasTrackedPropertyChangeListener

_persistence_setPropertyChangeListener

getTrackedAttributeName

setTrackedAttributeName

getRemovedElements

getAddedElements

hasAddedElements

hasRemovedElements

hasDeferredChanges

shouldAvoidInstantiation