Class SharedObject<T extends SharedObject<T>>

  • Type Parameters:
    T - Type of the shared object.
    Direct Known Subclasses:
    AbstractCall, BranchEntry, LabelValue, LazyValue, RandomValue, UnknownImmediateValue

    public abstract class SharedObject<T extends SharedObject<T>>
    extends java.lang.Object
    The SharedObject class implements a protocol of copying shared objects.

    An object is shared when it is referenced by several other objects. When these objects are copied, the shared object must be copied only once and all objects must use a reference to the same new copy.

    The protocol is implemented in the following way: The owner of the shared object creates a new copy using the copy constructor. A reference to the new copy is saved in the table of shared objects. Other clients must use the sharedCopy() method to get the reference to the new copy. It is important what all clients get the shared copy before a newer copy is created otherwise they will refer to different instances.

    In situations when it is not obvious which object is the owner, the getCopy() method can be used. It returns an existing shared copy if it is available or creates a new shared copy otherwise. To free existing shared copies, the freeSharedCopies() must be used.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected SharedObject()
      Constructs a new shared object.
      protected SharedObject​(SharedObject<T> other)
      Constructs a copy of a shared object.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      static <T extends SharedObject<T>>
      java.util.List<T>
      copyAll​(java.util.List<T> objects)
      Creates a copy of the specified list with copying stored objects.
      static void freeSharedCopies()
      Frees all shared objects.
      T getCopy()
      Returns a shared copy of the object if it is available.
      abstract T newCopy()
      Creates a new full copy of the object.
      protected static void publishSharedCopy​(java.lang.Object original, java.lang.Object copy)
      Publishes a shared copy of an object.
      T sharedCopy()
      Returns a shared copy of the object made by its owner.
      static <T extends SharedObject<T>>
      java.util.List<T>
      sharedCopyAll​(java.util.List<T> objects)
      Returns a list that stores shared copies of objects in the specified list.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • SharedObject

        protected SharedObject()
        Constructs a new shared object.

        No shared copies are published until an object is copied.

      • SharedObject

        protected SharedObject​(SharedObject<T> other)
        Constructs a copy of a shared object.

        This constructor must be called by the owner in order to publish a shared copy of the object.

        Parameters:
        other - Object to be copied.
        Throws:
        java.lang.IllegalArgumentException - if the argument is null.
    • Method Detail

      • freeSharedCopies

        public static void freeSharedCopies()
        Frees all shared objects.
      • sharedCopy

        public final T sharedCopy()
        Returns a shared copy of the object made by its owner.

        This method must be used by objects that keep a reference to the object and do not own it to update the reference when they are copied.

        Returns:
        Shared copy of the object.
        Throws:
        java.lang.IllegalArgumentException - if no shared copy is available yet.
      • sharedCopyAll

        public static <T extends SharedObject<T>> java.util.List<T> sharedCopyAll​(java.util.List<T> objects)
        Returns a list that stores shared copies of objects in the specified list.
        Type Parameters:
        T - Type of objects to be copied.
        Parameters:
        objects - List of objects to be copied.
        Returns:
        List that stores shared copies of the specified objects.
        Throws:
        java.lang.IllegalArgumentException - if the argument is null; if any of the objects has no shared copy.
      • copyAll

        public static <T extends SharedObject<T>> java.util.List<T> copyAll​(java.util.List<T> objects)
        Creates a copy of the specified list with copying stored objects. If an object in the list has a shared copy, the shared copy is used. Otherwise, the object is copied and its shared copy is published. In the end, all shared copies are cleaned up.
        Type Parameters:
        T - Type of objects to be copied.
        Parameters:
        objects - List of objects to be copied.
        Returns:
        List that stores shared copies of the specified objects.
        Throws:
        java.lang.IllegalArgumentException - if the argument is null.
      • getCopy

        public final T getCopy()
        Returns a shared copy of the object if it is available. Otherwise, creates and returns a new shared copy.
        Returns:
        Copy of the object.
        Throws:
        java.lang.IllegalArgumentException - if the newly created shared copy was not published.
      • newCopy

        public abstract T newCopy()
        Creates a new full copy of the object. This method must call the SharedObject(SharedObject) copy constructor in order to publish a shared copy.
        Returns:
        New full copy of the object.
      • publishSharedCopy

        protected static void publishSharedCopy​(java.lang.Object original,
                                                java.lang.Object copy)
        Publishes a shared copy of an object. If a shared copy of the object has already been published, it is replaced with the new one.
        Parameters:
        original - Original object.
        copy - Copy of the original object to be shared.
        Throws:
        java.lang.IllegalArgumentException - if any of the arguments is null.