com.sun.sgs.service.store
Interface DataStore

All Known Implementing Classes:

AbstractDataStore, DataStoreClient, DataStoreImpl, DataStoreProfileProducer

public interface DataStore

Defines the interface to the underlying persistence mechanism to store byte data.

Objects are identified by object IDs, which are positive longs. Names are mapped to object IDs.

Method Summary

long	createObject(Transaction txn) Reserves an object ID for a new object.
long	getBinding(Transaction txn, String name) Obtains the object ID bound to a name.
int	getClassId(Transaction txn, byte[] classInfo) Returns the class ID to represent classes with the specified class information.
byte[]	getClassInfo(Transaction txn, int classId) Returns the class information associated with the specified class ID.
long	getLocalNodeId() Returns the node ID for the local node.
byte[]	getObject(Transaction txn, long oid, boolean forUpdate) Obtains the data associated with an object ID.
void	markForUpdate(Transaction txn, long oid) Notifies the DataStore that an object is going to be modified.
String	nextBoundName(Transaction txn, String name) Returns the next name after the specified name that has a binding, or null if there are no more bound names.
long	nextObjectId(Transaction txn, long oid) Returns the object ID for the next object after the object with the specified ID, or -1 if there are no more objects.
void	ready() Notifies the data store that services associated with the application have been successfully created.
void	removeBinding(Transaction txn, String name) Removes the binding for a name.
void	removeObject(Transaction txn, long oid) Removes the object with the specified object ID.
void	setBinding(Transaction txn, String name, long oid) Binds an object ID to a name.
void	setBindingDescription(Transaction txn, String name, Object description) Associates a description with a bound name, for use in describing name accesses.
void	setObject(Transaction txn, long oid, byte[] data) Specifies data to associate with an object ID.
void	setObjectDescription(Transaction txn, long oid, Object description) Associates a description with an object ID, for use in describing object accesses.
void	setObjects(Transaction txn, long[] oids, byte[][] dataArray) Specifies data to associate with a series of object IDs.
void	shutdown() Shuts down this data store.

Method Detail

ready

void ready()
           throws Exception

Notifies the data store that services associated with the application have been successfully created. If the method throws an exception, then the application should be shutdown.

Throws:

Exception - if an error occurs

getLocalNodeId

long getLocalNodeId()

Returns the node ID for the local node.

Returns:

the node ID for the local node

createObject

long createObject(Transaction txn)

Reserves an object ID for a new object. Note that calling other operations using this ID are not required to find the object until setObject or setObjects is called. Aborting a transaction is also not required to unassign the ID so long as other operations treat it as a non-existent object.

Parameters:

txn - the transaction under which the operation should take place

Returns:

the new object ID

Throws:

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

markForUpdate

void markForUpdate(Transaction txn,
                   long oid)

Notifies the DataStore that an object is going to be modified. The implementation can use this information to obtain an exclusive lock on the object in order to avoid contention when the object is modified. This method does nothing if the object does not exist.

Parameters:

txn - the transaction under which the operation should take place

oid - the object ID

Throws:

IllegalArgumentException - if oid is negative

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

getObject

byte[] getObject(Transaction txn,
                 long oid,
                 boolean forUpdate)

Obtains the data associated with an object ID. If the forUpdate parameter is true, the caller is stating its intention to modify the object. The implementation can use that information to obtain an exclusive lock on the object in order avoid contention when the object is modified.

Parameters:

txn - the transaction under which the operation should take place

oid - the object ID

forUpdate - whether the caller intends to modify the object

Returns:

the data associated with the object ID

Throws:

IllegalArgumentException - if oid is negative

ObjectNotFoundException - if the object is not found

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

setObject

void setObject(Transaction txn,
               long oid,
               byte[] data)

Specifies data to associate with an object ID.

Parameters:

txn - the transaction under which the operation should take place

oid - the object ID

data - the data

Throws:

IllegalArgumentException - if oid is negative

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

setObjects

void setObjects(Transaction txn,
                long[] oids,
                byte[][] dataArray)

Specifies data to associate with a series of object IDs.

Parameters:

txn - the transaction under which the operation should take place

oids - the object IDs

dataArray - the associated data values

Throws:

IllegalArgumentException - if oids and data are not the same length, or if oids contains a value that is negative

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

removeObject

void removeObject(Transaction txn,
                  long oid)

Removes the object with the specified object ID. The implementation will make an effort to flag subsequent references to the removed object by throwing ObjectNotFoundException, although this behavior is not guaranteed. The implementation is not required to check that the object is an externally visible object rather than one used internally by the implementation.

Parameters:

txn - the transaction under which the operation should take place

oid - the object ID

Throws:

IllegalArgumentException - if oid is negative

ObjectNotFoundException - if the object is not found

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

getBinding

long getBinding(Transaction txn,
                String name)

Obtains the object ID bound to a name.

Parameters:

txn - the transaction under which the operation should take place

name - the name

Returns:

the object ID

Throws:

NameNotBoundException - if no object ID is bound to the name

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

setBinding

void setBinding(Transaction txn,
                String name,
                long oid)

Binds an object ID to a name.

Parameters:

txn - the transaction under which the operation should take place

name - the name

oid - the object ID

Throws:

IllegalArgumentException - if oid is negative

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

removeBinding

void removeBinding(Transaction txn,
                   String name)

Removes the binding for a name.

Parameters:

txn - the transaction under which the operation should take place

name - the name

Throws:

NameNotBoundException - if the name is not bound

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

nextBoundName

String nextBoundName(Transaction txn,
                     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.

Parameters:

txn - the transaction under which the operation should take place

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:

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

shutdown

void shutdown()

Shuts down this data store. This method will block until the shutdown is complete.

getClassId

int getClassId(Transaction txn,
               byte[] classInfo)

Returns the class ID to represent classes with the specified class information. Obtains an existing ID for the class information if present; otherwise, stores the information and returns the new ID associated with it. Class IDs are always greater than 0. The class information is the serialized form of the ObjectStreamClass instance that serialization uses to represent the class.

Parameters:

txn - the transaction under which the operation should take place

classInfo - the class information

Returns:

the associated class ID

Throws:

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

TransactionNotActiveException - if the transaction is not active

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

getClassInfo

byte[] getClassInfo(Transaction txn,
                    int classId)
                    throws ClassInfoNotFoundException

Returns the class information associated with the specified class ID. The class information is the serialized form of the ObjectStreamClass instance that serialization uses to represent the class.

Parameters:

txn - the transaction under which the operation should take place

classId - the class ID

Returns:

the associated class information

Throws:

IllegalArgumentException - if classId is not greater than 0

ClassInfoNotFoundException - if the ID is not found

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

IllegalStateException - if the operation failed because of a problem with the transaction

nextObjectId

long nextObjectId(Transaction txn,
                  long oid)

Returns the object ID for the next object after the object with the specified ID, or -1 if there are no more objects. If objectId is -1, then returns the ID of the first object. The IDs returned by this method will not include ones for objects that have already been removed, and may not include identifiers for objects created after an iteration has begun. It is not an error for the object associated with the specified identifier to have already been removed.

Applications should not assume that objects associated with the IDs 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 store.

Parameters:

txn - the transaction under which the operation should take place

oid - the identifier of the object to search after, or -1 to request the first object

Returns:

the identifier of the next object following the object with identifier oid, or -1 if there are no more objects

Throws:

IllegalArgumentException - if the argument is less than -1

TransactionAbortedException - if the transaction was aborted due to a lock conflict or timeout

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

setObjectDescription

void setObjectDescription(Transaction txn,
                          long oid,
                          Object description)

Associates a description with an object ID, for use in describing object accesses. The description should provide a meaningful toString method.

Parameters:

txn - the transaction under which the operation should take place

oid - the object ID

description - the description

Throws:

IllegalArgumentException - if oid is negative

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

See Also:

AccessReporter.setObjectDescription

setBindingDescription

void setBindingDescription(Transaction txn,
                           String name,
                           Object description)

Associates a description with a bound name, for use in describing name accesses. The description should provide a meaningful toString method.

Parameters:

txn - the transaction under which the operation should take place

name - the name

description - the description

Throws:

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

See Also:

AccessReporter.setObjectDescription