T
- Type of the shared object.public abstract class SharedObject<T extends SharedObject<T>>
extends java.lang.Object
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.
Modifier | Constructor and Description |
---|---|
protected |
SharedObject()
Constructs a new shared object.
|
protected |
SharedObject(SharedObject<T> other)
Constructs a copy of a shared object.
|
Modifier and Type | Method and Description |
---|---|
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>> |
sharedCopyAll(java.util.List<T> objects)
Returns a list that stores shared copies of objects in the specified list.
|
protected SharedObject()
No shared copies are published until an object is copied.
protected SharedObject(SharedObject<T> other)
This constructor must be called by the owner in order to publish a shared copy of the object.
other
- Object to be copied.java.lang.IllegalArgumentException
- if the argument is null
.public static void freeSharedCopies()
public final T sharedCopy()
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.
java.lang.IllegalArgumentException
- if no shared copy is available yet.public static <T extends SharedObject<T>> java.util.List<T> sharedCopyAll(java.util.List<T> objects)
T
- Type of objects to be copied.objects
- List of objects to be copied.java.lang.IllegalArgumentException
- if any of the objects has no shared copy.public final T getCopy()
java.lang.IllegalArgumentException
- if the newly created shared copy was not published.public abstract T newCopy()
SharedObject(SharedObject)
copy constructor in order to publish a shared copy.protected static void publishSharedCopy(java.lang.Object original, java.lang.Object copy)
original
- Original object.copy
- Copy of the original object to be shared.java.lang.IllegalArgumentException
- if any of the arguments is null
.