com.sun.sgs.service
Interface DataService

All Superinterfaces:

DataManager, Service

All Known Implementing Classes:

DataServiceImpl

public interface DataService
extends DataManager, Service

Provides facilities for services to manage access to shared, persistent objects. In addition to the methods provided by DataManager, this interface includes methods for an additional set of service bindings. These service bindings are intended to by used by services to support their needs to store objects persistently. The objects associated with service bindings are independent of the objects bound through methods defined on DataManager. Services should insure that they use unique names for service bindings by using their class or package name as the prefix for the name.

Method Summary

ManagedReference<?>	createReferenceForId(BigInteger id) Creates a managed reference for the object with the specified identifier, which should have been obtained from a call to ManagedReference.getId.
long	getLocalNodeId() Returns the node ID for the local node.
ManagedObject	getServiceBinding(String name) Obtains the object associated with the service binding of a name.
ManagedObject	getServiceBindingForUpdate(String name) Obtains the object associated with the service binding of a name, and notifies the system that the object is going to be modified.
BigInteger	nextObjectId(BigInteger objectId) Returns a unique identifier for the next object after the object with the specified identifier, or null if there are no more objects.
String	nextServiceBoundName(String name) Returns the next name after the specified name that has a service binding, or null if there are no more bound names.
void	removeServiceBinding(String name) Removes the service binding for a name.
void	setServiceBinding(String name, Object object) Specifies an object for the service binding of a name, replacing any previous binding.

Methods inherited from interface com.sun.sgs.app.DataManager

createReference, getBinding, getBindingForUpdate, getObjectId, markForUpdate, nextBoundName, removeBinding, removeObject, setBinding

Methods inherited from interface com.sun.sgs.service.Service

getName, ready, shutdown

Method Detail

getLocalNodeId

long getLocalNodeId()

Returns the node ID for the local node. The node ID for a node remains fixed for the lifetime of the node (i.e., until it fails). The return value may be passed to WatchdogService.getNode to obtain the Node object for the local node.

This method may be invoked any time after this service is initialized, whether or not the calling context is inside or outside of a transaction.

Returns:

the node ID for the local node

getServiceBinding

ManagedObject getServiceBinding(String name)

Obtains the object associated with the service binding of a name. Callers need to notify the system before modifying the object or any of the non-managed objects it refers to by calling markForUpdate or ManagedReference.getForUpdate before making the modifications.

Parameters:

name - the name

Returns:

the object associated with the service binding of 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:

getServiceBindingForUpdate

getServiceBindingForUpdate

ManagedObject getServiceBindingForUpdate(String name)

Obtains the object associated with the service binding of a name, and notifies the system that the object is going to be modified.

Parameters:

name - the name

Returns:

the object associated with the service binding of 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

setServiceBinding

void setServiceBinding(String name,
                       Object object)

Specifies an object for the service binding of 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 associated with the service binding of the name

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

removeServiceBinding

void removeServiceBinding(String name)

Removes the service 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

nextServiceBoundName

String nextServiceBoundName(String name)

Returns the next name after the specified name that has a service 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 service 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

createReferenceForId

ManagedReference<?> createReferenceForId(BigInteger id)

Creates a managed reference for the object with the specified identifier, which should have been obtained from a call to ManagedReference.getId. Callers should make sure that the associated object is reachable from an existing name binding. This method does not check to see whether the associated object has been removed.

Parameters:

id - the identifier

Returns:

the managed reference

Throws:

IllegalArgumentException - if the implementation is able to determine that id was not returned by a call to ManagedReference.getId

TransactionException - if the operation failed because of a problem with the current transaction

nextObjectId

BigInteger nextObjectId(BigInteger objectId)

Returns a unique identifier for the next object after the object with the specified identifier, or null if there are no more objects. If objectId is null, then returns the identifier of the first object. This method will not return identifiers for objects that have already been removed, and may not include identifiers for newly created objects. It is not an error for the object associated with objectId to have already been removed.

The object identifiers accepted and returned by this method are the same as those returned by the ManagedReference.getId method.

Callers should not assume that objects associated with the identifiers returned by this method, but which cannot be reached by traversing object field references starting with an object associated with a name binding, will continue to be retained by the data service.

Parameters:

objectId - the identifier of the object to search after, or null to request the first object

Returns:

the identifier of the next object following the object with identifier objectId, or null if there are no more objects

Throws:

IllegalArgumentException - if the implementation can determine that objectId is not a valid object identifier

TransactionException - if the operation failed because of a problem with the current transaction