com.sun.sgs.app
Interface DataManager


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.

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.

See Also:
AppContext.getDataManager(), ManagedObject, ManagedReference, Serializable

Method Summary
<T> ManagedReference<T>
createReference(T object)
          Creates a managed reference to an object.
 ManagedObject getBinding(String name)
          Obtains the object bound to a name.
 void markForUpdate(Object object)
          Notifies the system that an object is going to be modified.
 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.
 void setBinding(String name, Object object)
          Binds an object to a name, replacing any previous binding.
 

Method Detail

getBinding

ManagedObject getBinding(String name)
Obtains the object bound to a name. For implementations that need to be notified of object modifications, applications should call markForUpdate or ManagedReference.getForUpdate before modifying the returned object or any of the non-managed objects it refers to.

Parameters:
name - the name
Returns:
the object bound to the name
Throws:
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
See Also:
markForUpdate, ManagedReference.getForUpdate

setBinding

void setBinding(String name,
                Object object)
Binds an object to a name, replacing any previous binding. The object must implement 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.

Parameters:
name - the name
object - the object
Throws:
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

removeBinding

void removeBinding(String name)
Removes the binding for a name. Note that the object previously bound to the name, if any, is not removed; only the binding between the name and the object is removed. To remove the object, use the removeObject method.

Parameters:
name - the name
Throws:
NameNotBoundException - if the name is not bound
TransactionException - if the operation failed because of a problem with the current transaction
See Also:
removeObject

nextBoundName

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. 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.

Parameters:
name - the name to search after, or null to start at the beginning
Returns:
the next name with a binding following name, or null if there are no more bound names
Throws:
TransactionException - if the operation failed because of a problem with the current transaction

removeObject

void removeObject(Object object)
Removes an object from the DataManager. 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, 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.

Parameters:
object - the object
Throws:
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 exception
See Also:
ManagedObjectRemoval

markForUpdate

void markForUpdate(Object object)
Notifies the system that an object is going to be modified.

Parameters:
object - the object
Throws:
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
See Also:
ManagedReference.getForUpdate

createReference

<T> ManagedReference<T> createReference(T object)
Creates a managed reference to an object. Applications should use managed references when a managed object refers to another managed object, either directly or indirectly through non-managed objects.

Type Parameters:
T - the type of the object
Parameters:
object - the object
Returns:
the managed reference
Throws:
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

Project Darkstar, Version 0.9.9.6
2009-05-08 15:39:40

Copyright © 2007-2009 Sun Microsystems, Inc. All rights reserved