Package org.eclipse.persistence.indirection

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 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 Description
      protected int initialCapacity
      Store initial size for lazy init.
      protected float loadFactor
      Store load factor for lazy init.

    • 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)  
      protected java.util.Set<E> buildDelegate()
      INTERNAL: Return the freshly-built delegate.
      void clear()  
      void clearDeferredChanges()
      INTERNAL: clear any changes that have been deferred to instantiation.
      java.lang.Object clone()  
      protected java.util.Set<E> cloneDelegate()
      INTERNAL: Clone the delegate.
      boolean contains​(java.lang.Object element)  
      boolean containsAll​(java.util.Collection<?> c)  
      boolean equals​(java.lang.Object o)  
      void forEach​(java.util.function.Consumer<? super E> action)  
      java.util.Collection<E> getAddedElements()
      INTERNAL: Return the elements that have been added before instantiation.
      protected java.util.Set<E> getDelegate()
      INTERNAL: Check whether the contents have been read from the database.
      java.lang.Object getDelegateObject()
      INTERNAL: Return the real collection object.
      java.util.Collection<E> 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.
      protected boolean isRelationshipMaintenanceRequired()  
      java.util.Iterator<E> iterator()  
      java.util.stream.Stream<E> parallelStream()  
      protected void raiseAddChangeEvent​(java.lang.Object element)
      Raise the add change event and relationship maintainence.
      protected void raiseRemoveChangeEvent​(java.lang.Object element)
      Raise the remove change event.
      boolean remove​(java.lang.Object element)  
      boolean removeAll​(java.util.Collection<?> c)  
      boolean removeIf​(java.util.function.Predicate<? super E> filter)  
      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.
      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()  
      java.util.Spliterator<E> spliterator()  
      java.util.stream.Stream<E> stream()  
      java.lang.Object[] toArray()  
      <T> T[] toArray​(T[] 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

        finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.util.Collection

        toArray

    • 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:
        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

      • isRelationshipMaintenanceRequired

        protected boolean isRelationshipMaintenanceRequired()

      • 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)

      • buildDelegate

        protected java.util.Set<E> buildDelegate()
        INTERNAL: Return the freshly-built delegate.

      • 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()
        Overrides:
        clone in class java.lang.Object
        See Also:
        This will result in a database query if necessary.

      • cloneDelegate

        protected java.util.Set<E> cloneDelegate()
        INTERNAL: Clone the delegate.

      • 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)

      • spliterator

        public java.util.Spliterator<E> spliterator()
        Specified by:
        spliterator in interface java.util.Collection<E>
        Specified by:
        spliterator in interface java.lang.Iterable<E>
        Specified by:
        spliterator in interface java.util.Set<E>

      • parallelStream

        public java.util.stream.Stream<E> parallelStream()
        Specified by:
        parallelStream in interface java.util.Collection<E>

      • stream

        public java.util.stream.Stream<E> stream()
        Specified by:
        stream in interface java.util.Collection<E>

      • removeIf

        public boolean removeIf​(java.util.function.Predicate<? super E> filter)
        Specified by:
        removeIf in interface java.util.Collection<E>

      • forEach

        public void forEach​(java.util.function.Consumer<? super E> action)
        Specified by:
        forEach in interface java.lang.Iterable<E>

      • getDelegate

        protected java.util.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 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()

      • 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 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 <T> T[] toArray​(T[] 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()

      • raiseAddChangeEvent

        protected void raiseAddChangeEvent​(java.lang.Object element)
        Raise the add change event and relationship maintainence.

      • raiseRemoveChangeEvent

        protected void raiseRemoveChangeEvent​(java.lang.Object element)
        Raise the remove change event.

      • _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<E> getRemovedElements()
        INTERNAL: Return the elements that have been removed before instantiation.
        Specified by:
        getRemovedElements in interface IndirectCollection

      • getAddedElements

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

      • shouldAvoidInstantiation

        protected boolean shouldAvoidInstantiation()
        INTERNAL: Return if add/remove should trigger instantiation or avoid. Current instantiation is avoided is using change tracking.