|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
public interface DataManager
Provides facilities for managing access to shared, persistent objects.
Managed objects are objects that implement the ManagedObject and
Serializable interfaces. Each managed object is stored separately
along with all of the serializable, non-managed objects it refers to. If a
managed object refers to another managed object, it must do so through an
instance of ManagedReference, created by the createReference method. Attempting to store a reference to a managed
object using a standard reference rather than an instance of
ManagedReference will typically result in an ObjectIOException being thrown when the current transaction commits.
Managed objects that are bound to names, and any managed objects they refer
to directly or indirectly, are stored by the DataManager. It
is up to the application to determine when managed objects are no longer
needed and to remove them explicitly from the DataManager using
the removeObject method.
Managed objects are in one of the following states with respect to the data manager:
setBinding, createReference, or
getObjectId. Transient objects are not known to
the data manager and are not stored persistently.
Passing a transient object to setBinding, createReference, or getObjectId creates a new entry for the
object in the data manager. Calling removeObject or markForUpdate on a transient object does not change the
state of the object. If a transient object implements ManagedObjectRemoval, though, then calling removeObject will
cause its removingObject
method to be called.
setBinding, createReference, or getObjectId in the current transaction, or
else retrieved from the data manager by calling getBinding, getBindingForUpdate, ManagedReference.get, or ManagedReference.getForUpdate.
Passing a persistent object to setBinding, createReference, markForUpdate, or getObjectId does not
create a new entry for that object in the data manager, but rather
reuses the existing one. Calling removeObject on a persistent
object removes it from the data manager, meaning it will no longer be
stored persistently, and changes its state to removed. Note that
a managed object made persistent in the current transaction is
automatically marked for update, so there is no need to call markForUpdate for such objects, in particular in their
constructors.
removeObject. Removed
objects are no longer stored persistently, although the data manager
makes an effort to track which managed objects have been removed.
Only persistent managed objects can become removed; calling removeObject on a transient managed object leaves it as a transient
object. Passing a removed managed object to setBinding, removeObject, markForUpdate, createReference, or getObjectId, as well as calling ManagedReference.get or ManagedReference.getForUpdate on a reference to the removed object,
will cause a ObjectNotFoundException to be thrown, if the system
has tracked the object's removed state.
Passing a stale object to setBinding, removeObject,
markForUpdate, createReference, or getObjectId,
as well as calling ManagedReference.get or ManagedReference.getForUpdate on a reference to the stale object, will
cause a TransactionNotActiveException to be thrown, if the
system has tracked the object's stale state.
Because storing a managed object in a name binding or creating a managed
reference to it causes the object to be stored in data manager, applications
should insure that they remove such objects if they end up not referring to
them persistently. The removeObject method does not throw
exceptions when called on a transient object, so applications should call
removeObject whenever there is an object that may have become
persistent and they are sure is no longer used.
Some implementations may need to be notified when managed objects and the objects they refer to are modified, while other implementations may be configurable to detect these modifications automatically. Applications are always permitted to mark objects that have been modified, and doing so may produce performance improvements regardless of whether modifications are detected automatically.
AppContext.getDataManager(),
ManagedObject,
ManagedReference,
Serializable| Method Summary | ||
|---|---|---|
|
createReference(T object)
Creates a managed reference to an object, storing the object in the data manager if it is transient. |
|
ManagedObject |
getBinding(String name)
Obtains the object bound to a name. |
|
ManagedObject |
getBindingForUpdate(String name)
Obtains the object bound to a name, and notifies the system that the object is going to be modified. |
|
BigInteger |
getObjectId(Object object)
Returns a unique identifier for the object, storing the object in the data manager if it is transient. |
|
void |
markForUpdate(Object object)
Notifies the system that an object is going to be modified, doing nothing if the object is transient. |
|
String |
nextBoundName(String name)
Returns the next name after the specified name that has a binding, or null if there are no more bound names. |
|
void |
removeBinding(String name)
Removes the binding for a name. |
|
void |
removeObject(Object object)
Removes an object from the DataManager, if the object is persistent. |
|
void |
setBinding(String name,
Object object)
Binds an object to a name, replacing any previous binding, and storing the object in the data manager if it is transient. |
|
| Method Detail |
|---|
ManagedObject getBinding(String name)
markForUpdate or ManagedReference.getForUpdate before modifying the returned object or
any of the non-managed objects it refers to.
name - the name
NameNotBoundException - if no object is bound to the name
ObjectNotFoundException - if the object bound to the name is not
found
TransactionException - if the operation failed because of a
problem with the current transactionmarkForUpdate,
ManagedReference.getForUpdate,
getBindingForUpdateManagedObject getBindingForUpdate(String name)
name - the name
NameNotBoundException - if no object is bound to the name
ObjectNotFoundException - if the object bound to the name is not
found
TransactionException - if the operation failed because of a
problem with the current transaction
void setBinding(String name,
Object object)
ManagedObject, and both the object and any objects it refers to must
implement Serializable. Note that this method will throw IllegalArgumentException if object does not implement
Serializable, but is not guaranteed to check that all
referred to objects implement Serializable. Any instances
of ManagedObject that object refers to directly, or
indirectly through non-managed objects, need to be referred to through
instances of ManagedReference.
name - the nameobject - the object
IllegalArgumentException - if object does not
implement both ManagedObject and Serializable
ObjectNotFoundException - if the object has been removed
TransactionException - if the operation failed because of a
problem with the current transactionvoid removeBinding(String name)
removeObject method.
name - the name
NameNotBoundException - if the name is not bound
TransactionException - if the operation failed because of a
problem with the current transactionremoveObjectString nextBoundName(String name)
null if there are no more bound names. If
name is null, then the search starts at the
beginning.
The order of the names corresponds to the ordering of the UTF-8 encoding
of the names. To provide flexibility to the implementation, the UTF-8
encoding used can be either standard UTF-8, as defined by the
IETF in RFC 3629, or
modified UTF-8, as used by serialization and defined by the
DataInput interface.
name - the name to search after, or null to start at
the beginning
name, or
null if there are no more bound names
TransactionException - if the operation failed because of a
problem with the current transactionvoid removeObject(Object object)
DataManager, if the object is persistent. The system will make an effort to
flag subsequent references to the removed object through getBinding or ManagedReference by throwing ObjectNotFoundException, although this behavior is not guaranteed.
If object implements ManagedObjectRemoval, even if it is
transient, then this method first calls the
ManagedObjectRemoval.removingObject method on the object, to notify it
that it is being removed. If the call to removingObject throws
a RuntimeException, then this method will throw that exception
without removing the object. A call to removingObject that
causes removeObject to be called recursively on the same object
will result in an IllegalStateException being thrown.
object - the object
IllegalArgumentException - if object does not implement
both ManagedObject and Serializable
IllegalStateException - if object implements ManagedObjectRemoval and removeObject is called
recursively on the object through a call to ManagedObjectRemoval.removingObject
ObjectNotFoundException - if the object has already been removed
TransactionException - if the operation failed because of a
problem with the current transaction
RuntimeException - if object implements ManagedObjectRemoval and calling ManagedObjectRemoval.removingObject on the object throws a
runtime exceptionManagedObjectRemovalvoid markForUpdate(Object object)
object - the object
IllegalArgumentException - if object does not
implement both ManagedObject and Serializable
ObjectNotFoundException - if the object has been removed
TransactionException - if the operation failed because of a
problem with the current transactionManagedReference.getForUpdate<T> ManagedReference<T> createReference(T object)
T - the type of the objectobject - the object
IllegalArgumentException - if object does not
implement both ManagedObject and Serializable
ObjectNotFoundException - if the object has been removed
TransactionException - if the operation failed because of a
problem with the current transactionBigInteger getObjectId(Object object)
ManagedReference.getId on a
managed reference associated with the object produced by createReference.
object - the object
IllegalArgumentException - if object does not
implement both ManagedObject and Serializable
ObjectNotFoundException - if the object has been removed
TransactionException - if the operation failed because of a
problem with the current transaction
|
RedDwarf, Version 0.10.1 2010-03-14 10:56:12 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||