Class IndirectSet<E>

  • Type Parameters:
    E - the type of elements maintained by this set
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.Set<E>, ChangeTracker, CollectionChangeTracker, IndirectCollection, IndirectContainer

    public class IndirectSet<E>
    extends java.lang.Object
    implements CollectionChangeTracker, java.util.Set<E>, IndirectCollection, java.lang.Cloneable, java.io.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 Description
      IndirectSet()
      Construct an empty IndirectSet.
      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.
      IndirectSet​(java.util.Collection<? extends E> c)
      Construct an IndirectSet containing the elements of the specified collection.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.beans.PropertyChangeListener _persistence_getPropertyChangeListener()
      INTERNAL: Return the property change listener for change tracking.
      void _persistence_setPropertyChangeListener​(java.beans.PropertyChangeListener changeListener)
      INTERNAL: Set the property change listener for change tracking.
      boolean add​(E element)  
      boolean addAll​(java.util.Collection<? extends E> c)  
      void clear()  
      void clearDeferredChanges()
      INTERNAL: clear any changes that have been deferred to instantiation.
      java.lang.Object clone()  
      boolean contains​(java.lang.Object element)  
      boolean containsAll​(java.util.Collection<?> c)  
      boolean equals​(java.lang.Object o)  
      java.util.Collection getAddedElements()
      INTERNAL: Return the elements that have been added before instantiation.
      java.lang.Object getDelegateObject()
      INTERNAL: Return the real collection object.
      java.util.Collection getRemovedElements()
      INTERNAL: Return the elements that have been removed before instantiation.
      java.lang.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.
      java.util.Iterator<E> iterator()  
      boolean remove​(java.lang.Object element)  
      boolean removeAll​(java.util.Collection<?> c)  
      boolean retainAll​(java.util.Collection<?> c)  
      void setTrackedAttributeName​(java.lang.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()  
      java.lang.Object[] toArray()  
      <E> E[] toArray​(E[] a)  
      java.lang.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.Collection

        parallelStream, removeIf, stream, toArray
      • Methods inherited from interface java.lang.Iterable

        forEach
      • Methods inherited from interface java.util.Set

        spliterator
    • 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:
        java.lang.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:
        java.lang.IllegalArgumentException - if the specified initial capacity is negative
      • IndirectSet

        public IndirectSet​(java.util.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 java.util.Collection<E>
        Specified by:
        add in interface java.util.Set<E>
        See Also:
        Set.add(java.lang.Object)
      • addAll

        public boolean addAll​(java.util.Collection<? extends E> c)
        Specified by:
        addAll in interface java.util.Collection<E>
        Specified by:
        addAll in interface java.util.Set<E>
        See Also:
        Set.addAll(java.util.Collection)
      • clear

        public void clear()
        Specified by:
        clear in interface java.util.Collection<E>
        Specified by:
        clear in interface java.util.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 java.lang.Object clone()
        See Also:
        This will result in a database query if necessary.
      • contains

        public boolean contains​(java.lang.Object element)
        Specified by:
        contains in interface java.util.Collection<E>
        Specified by:
        contains in interface java.util.Set<E>
        See Also:
        Set.contains(java.lang.Object)
      • containsAll

        public boolean containsAll​(java.util.Collection<?> c)
        Specified by:
        containsAll in interface java.util.Collection<E>
        Specified by:
        containsAll in interface java.util.Set<E>
        See Also:
        Set.containsAll(java.util.Collection)
      • equals

        public boolean equals​(java.lang.Object o)
        Specified by:
        equals in interface java.util.Collection<E>
        Specified by:
        equals in interface java.util.Set<E>
        Overrides:
        equals in class java.lang.Object
        See Also:
        Set.equals(java.lang.Object)
      • getDelegateObject

        public java.lang.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 java.util.Collection<E>
        Specified by:
        hashCode in interface java.util.Set<E>
        Overrides:
        hashCode in class java.lang.Object
        See Also:
        Set.hashCode()
      • isEmpty

        public boolean isEmpty()
        Specified by:
        isEmpty in interface java.util.Collection<E>
        Specified by:
        isEmpty in interface java.util.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 java.util.Iterator<E> iterator()
        Specified by:
        iterator in interface java.util.Collection<E>
        Specified by:
        iterator in interface java.lang.Iterable<E>
        Specified by:
        iterator in interface java.util.Set<E>
        See Also:
        Set.iterator()
      • remove

        public boolean remove​(java.lang.Object element)
        Specified by:
        remove in interface java.util.Collection<E>
        Specified by:
        remove in interface java.util.Set<E>
        See Also:
        Set.remove(java.lang.Object)
      • removeAll

        public boolean removeAll​(java.util.Collection<?> c)
        Specified by:
        removeAll in interface java.util.Collection<E>
        Specified by:
        removeAll in interface java.util.Set<E>
        See Also:
        Set.removeAll(java.util.Collection)
      • retainAll

        public boolean retainAll​(java.util.Collection<?> c)
        Specified by:
        retainAll in interface java.util.Collection<E>
        Specified by:
        retainAll in interface java.util.Set<E>
        See Also:
        Set.retainAll(java.util.Collection)
      • 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 java.util.Collection<E>
        Specified by:
        size in interface java.util.Set<E>
        See Also:
        Set.size()
      • toArray

        public java.lang.Object[] toArray()
        Specified by:
        toArray in interface java.util.Collection<E>
        Specified by:
        toArray in interface java.util.Set<E>
        See Also:
        Set.toArray()
      • toArray

        public <E> E[] toArray​(E[] a)
        Specified by:
        toArray in interface java.util.Collection<E>
        Specified by:
        toArray in interface java.util.Set<E>
        See Also:
        Set.toArray(java.lang.Object[])
      • toString

        public java.lang.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 java.lang.Object
        See Also:
        AbstractCollection.toString()
      • _persistence_getPropertyChangeListener

        public java.beans.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​(java.beans.PropertyChangeListener changeListener)
        INTERNAL: Set the property change listener for change tracking.
        Specified by:
        _persistence_setPropertyChangeListener in interface ChangeTracker
      • setTrackedAttributeName

        public void setTrackedAttributeName​(java.lang.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 java.util.Collection getRemovedElements()
        INTERNAL: Return the elements that have been removed before instantiation.
        Specified by:
        getRemovedElements in interface IndirectCollection
      • getAddedElements

        public java.util.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