org.sourceforge.jemm.client
Class TrackingDatabase

java.lang.Object
  org.sourceforge.jemm.client.DelegatingDatabase
      org.sourceforge.jemm.client.TrackingDatabase

All Implemented Interfaces:

Database

public class TrackingDatabase
extends DelegatingDatabase

This Database implementation tracks maps any ids from the delegated database into singleton tracked ids (i.e. for any given object, there will be one singleton instance of a tracked id. All down calls to the delegate will have the tracked ids mapped back to regular ids.

It is responsible for detecting live use of the ids within the client code, once a client has finished using a tracked id, it will be garbage collected and the database will inform the underlying database that the id is no longer referenced.

To avoid a race condition between marking an id as unused and it being passed back in another call, the database users locking

N.b. This is heavily based upon the original ReferenceCleaner implementation and effectively is moving that code down into the Database rather than ObjectDatabase layer.

Author:

Paul Keeble, Rory Graves

Field Summary

static long

SLEEP_TIME Sleep time between reference cleaning cycles (in ms)

Constructor Summary

TrackingDatabase(Database delegate, TrackedIDFactory idFactory)

Method Summary

void	acquireLock(ClientThreadId threadId, ID jemmId) Asynchronous request to acquire a lock.
GetObjectResp	getObject(ClientId clientId, ID jemmId) Retrieves an object's information from the database.
ID	getRoot(ClientId clientId, java.lang.String rootName) Returns the object stored in the persistent root called 'rootName'
void	internalClearRererence(ID[] toClear)
ID	newObject(ClientId clientId, ClassId classId) Notification of a new user object creation by the client.
TypeResponse<?>	processTypeRequest(ClientId clientId, ClassId classId, ID objId, TypeRequest<?> request) Process a request from a jemm type implementation.
void	referenceCleared(ClientId clientId, ID... ids) Asynchronous notification that the client has de-referenced the given id.
void	releaseLock(ClientThreadId threadId, ID jemmId) Release the given lock held by the thread.
void	removeLockAcquiredListener(ClientId clientId) Remove a lock listener
void	setClientLockAcquiredListener(ClientId clientId, LockAcquiredListener listener) Register a lock listener
void	setRoot(ClientId clientId, java.lang.String rootName, ID newValue) Set the persistent root reference to the given object.
ID	setRootIfNull(ClientId clientId, java.lang.String rootName, ID newValue) Sets the persistent root reference to the given object, if the root is currently null.
void	shutdown() TrackingDatabase uses a separate thread to pass ID information for cleaning, shutdown must be called to recover that native resource to avoid leaks.
ObjectSyncResp	synchroniseObject(ClientId clientId, ID jemmId, ObjectSyncData syncData) Synchronise a client held object with the server.

Methods inherited from class org.sourceforge.jemm.client.DelegatingDatabase

clientDisconnect, getClassInfo, getDebugInterface, getEnumInfo, registerClass, registerEnum

Methods inherited from class java.lang.Object

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

Field Detail

SLEEP_TIME

public static final long SLEEP_TIME

Sleep time between reference cleaning cycles (in ms)

See Also:

Constant Field Values

Constructor Detail

TrackingDatabase

public TrackingDatabase(Database delegate,
                        TrackedIDFactory idFactory)

Method Detail

acquireLock

public void acquireLock(ClientThreadId threadId,
                        ID jemmId)

Description copied from interface: Database

Asynchronous request to acquire a lock. This method will return immediately, but the caller should wait until notified by the LockAcquiredListener callback.

Specified by:

acquireLock in interface Database

Overrides:

acquireLock in class DelegatingDatabase

Parameters:

threadId - The requesting thread.

jemmId - The id of the object to lock.

getObject

public GetObjectResp getObject(ClientId clientId,
                               ID jemmId)

Description copied from interface: Database

Retrieves an object's information from the database.

Specified by:

getObject in interface Database

Overrides:

getObject in class DelegatingDatabase

Parameters:

clientId - The id of the requesting client.

jemmId - The id of the object to retrieve.

Returns:

The object information (class type, field values etc.).

getRoot

public ID getRoot(ClientId clientId,
                  java.lang.String rootName)

Description copied from interface: Database

Returns the object stored in the persistent root called 'rootName'

Specified by:

getRoot in interface Database

Overrides:

getRoot in class DelegatingDatabase

Parameters:

clientId - The id of the requesting client.

rootName - The name of the persistent root.

Returns:

The ID of the object stored in the persistent root, or null if none.

newObject

public ID newObject(ClientId clientId,
                    ClassId classId)

Description copied from interface: Database

Notification of a new user object creation by the client.

Specified by:

newObject in interface Database

Overrides:

newObject in class DelegatingDatabase

Parameters:

clientId - The id of the requesting client.

classId - The class id of the new object (must be previously registered).

Returns:

The ID assigned to the new object.

referenceCleared

public void referenceCleared(ClientId clientId,
                             ID... ids)

Description copied from interface: Database

Asynchronous notification that the client has de-referenced the given id.

Specified by:

referenceCleared in interface Database

Overrides:

referenceCleared in class DelegatingDatabase

Parameters:

clientId - The client who is no longer referencing 'id'

ids - The ID that has been de-referenced.

releaseLock

public void releaseLock(ClientThreadId threadId,
                        ID jemmId)

Description copied from interface: Database

Release the given lock held by the thread.

Specified by:

releaseLock in interface Database

Overrides:

releaseLock in class DelegatingDatabase

Parameters:

threadId - The thread currently holding the lock.

jemmId - The id of the object to release.

setRoot

public void setRoot(ClientId clientId,
                    java.lang.String rootName,
                    ID newValue)

Description copied from interface: Database

Set the persistent root reference to the given object.

Specified by:

setRoot in interface Database

Overrides:

setRoot in class DelegatingDatabase

Parameters:

clientId - The id of the requesting client.

rootName - The name of the persistent root.

newValue - The new value of the root.

setRootIfNull

public ID setRootIfNull(ClientId clientId,
                        java.lang.String rootName,
                        ID newValue)

Description copied from interface: Database

Sets the persistent root reference to the given object, if the root is currently null. This is an atomic operation.

Specified by:

setRootIfNull in interface Database

Overrides:

setRootIfNull in class DelegatingDatabase

Parameters:

clientId - The id of the requesting client.

rootName - The name of the persistent root.

newValue - The new value of the root.

Returns:

The old value if it was not null, or the recently set value.

synchroniseObject

public ObjectSyncResp synchroniseObject(ClientId clientId,
                                        ID jemmId,
                                        ObjectSyncData syncData)

Description copied from interface: Database

Synchronise a client held object with the server. Passing in the current client version and any updated fields this method returns the new version number of the object and any fields updated remotely (by another client).

Specified by:

synchroniseObject in interface Database

Overrides:

synchroniseObject in class DelegatingDatabase

Parameters:

clientId - The id of the requesting client.

jemmId - The id of the object.

syncData - The object synchronisation data (client version, updated fields)

Returns:

Returned synchronisation information, (new version number and updated fields).

processTypeRequest

public TypeResponse<?> processTypeRequest(ClientId clientId,
                                          ClassId classId,
                                          ID objId,
                                          TypeRequest<?> request)

Description copied from interface: Database

Process a request from a jemm type implementation. This is a generic call where a package of data is passed to database the type handler and a response is returned.

Specified by:

processTypeRequest in interface Database

Overrides:

processTypeRequest in class DelegatingDatabase

Parameters:

clientId - The id of the requesting client.

classId - The id of the class making the request.

objId - The target object.

request - The request data.

Returns:

The response data supplied by the type handler.

removeLockAcquiredListener

public void removeLockAcquiredListener(ClientId clientId)

Description copied from interface: Database

Remove a lock listener

Specified by:

removeLockAcquiredListener in interface Database

Overrides:

removeLockAcquiredListener in class DelegatingDatabase

Parameters:

clientId - The lock listener to remove.

setClientLockAcquiredListener

public void setClientLockAcquiredListener(ClientId clientId,
                                          LockAcquiredListener listener)

Description copied from interface: Database

Register a lock listener

Specified by:

setClientLockAcquiredListener in interface Database

Overrides:

setClientLockAcquiredListener in class DelegatingDatabase

Parameters:

clientId - The id of the client registering for lock notifications.

listener - The listener to register.

internalClearRererence

public void internalClearRererence(ID[] toClear)

shutdown

public void shutdown()

TrackingDatabase uses a separate thread to pass ID information for cleaning, shutdown must be called to recover that native resource to avoid leaks.