com.sun.sgs.impl.service.data
Class DataServiceImpl

java.lang.Object
  com.sun.sgs.impl.service.data.DataServiceImpl

All Implemented Interfaces:

DataManager, DataService, Service

public final class DataServiceImpl
extends Object
implements DataService

Provides an implementation of DataService based on DataStoreImpl.

The constructor requires the com.sun.sgs.app.name property, and supports both these public configuration properties and the following additional properties:

Property: "com.sun.sgs.impl.service.data.DataServiceImpl.data.store.class"
Default: com.sun.sgs.impl.service.data.store.net.DataStoreClient unless the com.sun.sgs.node.type property is singleNode, which defaults to com.sun.sgs.impl.service.data.store.DataStoreImpl

The name of the class that implements DataStore. The class should be public, not abstract, and should provide a public constructor with Properties, ComponentRegistry, and TransactionProxy parameters.

Property: "com.sun.sgs.impl.service.data.DataServiceImpl.detect.modifications"
Default: true

Whether to automatically detect modifications to managed objects. If set to something other than true, then applications need to call DataManager.markForUpdate or ManagedReference.getForUpdate for any modified objects to make sure that the modifications are recorded by the DataService.

Property: "com.sun.sgs.impl.service.data.DataServiceImpl.debug.check.interval"
Default: Integer.MAX_VALUE

The number of DataService operations to skip between checks of the consistency of the managed references table. Note that the number of operations is measured separately for each transaction. This property is intended for use in debugging.

Property: "com.sun.sgs.impl.service.data.DataServiceImpl.optimistic.write.locks"
Default: false

Whether to wait until commit time to obtain write locks. If false, which is the default, the service acquires write locks as soon as it knows that an object is being modified. If true, the service delays obtaining write locks until commit time, which may improve performance in some cases, typically when there is low contention. Note that setting this flag to true does not delay write locks when removing objects.

Property: "com.sun.sgs.impl.service.data.DataServiceImpl.track.stale.objects"
Default: false

Whether to track references to stale managed objects. If true, the DataService keeps track of persistent or removed objects from completed transactions and throws TransactionNotActiveException if the application refers to those objects from another transaction.

The constructor also passes the properties to the DataStoreImpl constructor, which supports additional properties.

This class uses the Logger named com.sun.sgs.impl.service.data.DataServiceImpl to log information at the following logging levels:

• SEVERE - Initialization failures
• CONFIG - Constructor properties, data service headers
• FINE - Task scheduling operations, managed reference table checks
• FINER - Transaction operations
• FINEST - Name, object, and reference operations

It also uses an additional Logger named com.sun.sgs.impl.service.data.DataServiceImpl.detect.modifications to log information about managed objects that are found to be modified but were not marked for update. Note that this logging output will only be performed if the com.sun.sgs.impl.service.data.DataServiceImpl.detect.modifications property is true.

• FINEST - Modified object was not marked for update

In addition, operations that throw a TransactionAbortedException will log the failure to the Logger named com.sun.sgs.impl.service.data.DataServiceImpl.abort, to make it easier to debug concurrency conflicts by just logging aborts.

Nested Class Summary

(package private) static class

DataServiceImpl.State The possible states of this instance.

Field Summary

static String	DATA_STORE_CLASS_PROPERTY The property that specifies the name of the class that implements DataStore.
static String	DEBUG_CHECK_INTERVAL_PROPERTY The property that specifies the number of operations to skip between checks of the consistency of the managed references table.
static String	DETECT_MODIFICATIONS_PROPERTY The property that specifies whether to automatically detect modifications to objects.
(package private) static LoggerWrapper	logger The logger for this class.
static String	OPTIMISTIC_WRITE_LOCKS The property that specifies to use optimistic write locking.
(package private) boolean	optimisticWriteLocks Whether to delay obtaining write locks.
static String	TRACK_STALE_OBJECTS_PROPERTY The property that specifies whether to track stale objects.

Constructor Summary

DataServiceImpl(Properties properties, ComponentRegistry systemRegistry, TransactionProxy txnProxy)
Creates an instance of this class configured with the specified properties and services.

Method Summary

(package private) static void	checkContext(Context context) Checks that the specified context is currently active.
(package private) void	checkState() Checks that the current state is RUNNING or SHUTTING_DOWN.
<T> ManagedReference<T>	createReference(T object) Creates a managed reference to an object, storing the object in the data manager if it is transient.
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.
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.
(package private) static Context	getContextNoJoin() Obtains the currently active context, throwing TransactionNotActiveException if none is active.
(package private) static LoggerWrapper	getExceptionLogger(RuntimeException exception) Returns the logger that should be used to log the specified exception.
long	getLocalNodeId() Returns the node ID for the local node.
String	getName() Returns the name used to identify this service.
BigInteger	getObjectId(Object object) Returns a unique identifier for the object, storing the object in the data manager if it is transient.
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.
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.
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	ready() Notifies this Service that the application is fully configured and ready to start running.
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	removeServiceBinding(String name) Removes the service binding for a name.
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.
void	setDebugCheckInterval(int debugCheckInterval) Specifies the number of operations to skip between checks of the consistency of the managed references table.
void	setDetectModifications(boolean detectModifications) Specifies whether to automatically detect modifications to objects.
void	setServiceBinding(String name, Object object) Specifies an object for the service binding of a name, replacing any previous binding.
void	shutdown() Shuts down this service.
String	toString() Returns a string representation of this instance.
(package private) static String	typeName(Object object) Returns the type name of the object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEBUG_CHECK_INTERVAL_PROPERTY

public static final String DEBUG_CHECK_INTERVAL_PROPERTY

The property that specifies the number of operations to skip between checks of the consistency of the managed references table.

See Also:

Constant Field Values

DETECT_MODIFICATIONS_PROPERTY

public static final String DETECT_MODIFICATIONS_PROPERTY

The property that specifies whether to automatically detect modifications to objects.

See Also:

Constant Field Values

DATA_STORE_CLASS_PROPERTY

public static final String DATA_STORE_CLASS_PROPERTY

The property that specifies the name of the class that implements DataStore.

See Also:

Constant Field Values

OPTIMISTIC_WRITE_LOCKS

public static final String OPTIMISTIC_WRITE_LOCKS

The property that specifies to use optimistic write locking.

See Also:

Constant Field Values

TRACK_STALE_OBJECTS_PROPERTY

public static final String TRACK_STALE_OBJECTS_PROPERTY

The property that specifies whether to track stale objects.

See Also:

Constant Field Values

logger

static final LoggerWrapper logger

The logger for this class.

optimisticWriteLocks

final boolean optimisticWriteLocks

Whether to delay obtaining write locks.

Constructor Detail

DataServiceImpl

public DataServiceImpl(Properties properties,
                       ComponentRegistry systemRegistry,
                       TransactionProxy txnProxy)
                throws Exception

Creates an instance of this class configured with the specified properties and services. See the class documentation for the list of supported properties.

Parameters:

properties - the properties for configuring this service

systemRegistry - the registry of available system components

txnProxy - the transaction proxy

Throws:

IllegalArgumentException - if the com.sun.sgs.app.name property is not specified, if the value of the com.sun.sgs.impl.service.data.DataServiceImpl.debug.check.interval property is not a valid integer, or if the data store constructor detects an illegal property value

Exception - if a problem occurs creating the service

Method Detail

getName

public String getName()

Returns the name used to identify this service.

Specified by:

getName in interface Service

Returns:

the service's name

ready

public void ready()
           throws Exception

Notifies this Service that the application is fully configured and ready to start running. This means that all other Services associated with this application have been successfully created. If the method throws an exception, then the application will be shutdown.

Specified by:

ready in interface Service

Throws:

Exception - if an error occurs

getBinding

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

Specified by:

getBinding in interface DataManager

Parameters:

name - the name

Returns:

the object bound to the name

See Also:

markForUpdate, ManagedReference.getForUpdate, getBindingForUpdate

getBindingForUpdate

public ManagedObject getBindingForUpdate(String name)

Obtains the object bound to a name, and notifies the system that the object is going to be modified.

Specified by:

getBindingForUpdate in interface DataManager

Parameters:

name - the name

Returns:

the object bound to the name

setBinding

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

Specified by:

setBinding in interface DataManager

Parameters:

name - the name

object - the object

removeBinding

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

Specified by:

removeBinding in interface DataManager

Parameters:

name - the name

See Also:

removeObject

nextBoundName

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

Specified by:

nextBoundName in interface DataManager

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

removeObject

public void removeObject(Object object)

Removes an object from the 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.

Specified by:

removeObject in interface DataManager

Parameters:

object - the object

See Also:

ManagedObjectRemoval

markForUpdate

public void markForUpdate(Object object)

Notifies the system that an object is going to be modified, doing nothing if the object is transient.

Specified by:

markForUpdate in interface DataManager

Parameters:

object - the object

See Also:

ManagedReference.getForUpdate

createReference

public <T> ManagedReference<T> createReference(T object)

Creates a managed reference to an object, storing the object in the data manager if it is transient. Applications should use managed references when a managed object refers to another managed object, either directly or indirectly through non-managed objects.

Specified by:

createReference in interface DataManager

Type Parameters:

T - the type of the object

Parameters:

object - the object

Returns:

the managed reference

getObjectId

public BigInteger getObjectId(Object object)

Returns a unique identifier for the object, storing the object in the data manager if it is transient. The value returned by this method is the same as the one that would be obtained by calling ManagedReference.getId on a managed reference associated with the object produced by createReference.

Specified by:

getObjectId in interface DataManager

Parameters:

object - the object

Returns:

a unique identifier for the object

getLocalNodeId

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

Specified by:

getLocalNodeId in interface DataService

Returns:

the node ID for the local node

getServiceBinding

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

Specified by:

getServiceBinding in interface DataService

Parameters:

name - the name

Returns:

the object associated with the service binding of the name

See Also:

getServiceBindingForUpdate

getServiceBindingForUpdate

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

Specified by:

getServiceBindingForUpdate in interface DataService

Parameters:

name - the name

Returns:

the object associated with the service binding of the name

setServiceBinding

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

Specified by:

setServiceBinding in interface DataService

Parameters:

name - the name

object - the object associated with the service binding of the name

removeServiceBinding

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

Specified by:

removeServiceBinding in interface DataService

Parameters:

name - the name

See Also:

removeObject

nextServiceBoundName

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

Specified by:

nextServiceBoundName in interface DataService

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

createReferenceForId

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

Specified by:

createReferenceForId in interface DataService

Parameters:

id - the identifier

Returns:

the managed reference

nextObjectId

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

Specified by:

nextObjectId in interface DataService

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

toString

public String toString()

Returns a string representation of this instance.

Overrides:

toString in class Object

Returns:

a string representation of this instance

setDebugCheckInterval

public void setDebugCheckInterval(int debugCheckInterval)

Specifies the number of operations to skip between checks of the consistency of the managed references table.

Parameters:

debugCheckInterval - the number of operations to skip between checks of the consistency of the managed references table

setDetectModifications

public void setDetectModifications(boolean detectModifications)

Specifies whether to automatically detect modifications to objects.

Parameters:

detectModifications - whether to detect modifications

shutdown

public void shutdown()

Shuts down this service. Any call to this method will block until the shutdown has completed. If a shutdown has been completed already, this method will return immediately.

This method does not require a transaction, and should not be called from one because this method will typically not succeed if there are outstanding transactions.

When this method returns, it is assumed that the service has been shutdown.

Callers should assume that, in a worst case, this method may block indefinitely, and so should arrange to take other action (for example, calling System.exit) if the call fails to complete successfully in a certain amount of time.

Specified by:

shutdown in interface Service

checkState

void checkState()

Checks that the current state is RUNNING or SHUTTING_DOWN.

checkContext

static void checkContext(Context context)

Checks that the specified context is currently active. Throws TransactionNotActiveException if there is no current transaction or if the current transaction doesn't match the context.

getContextNoJoin

static Context getContextNoJoin()

Obtains the currently active context, throwing TransactionNotActiveException if none is active. Does not join the transaction.

typeName

static String typeName(Object object)

Returns the type name of the object.

getExceptionLogger

static LoggerWrapper getExceptionLogger(RuntimeException exception)

Returns the logger that should be used to log the specified exception. In particular, use the abortLogger for TransactionAbortedException, and the class logger for other runtime exceptions.