org.sourceforge.jemm.database
Interface Database

All Known Implementing Classes:

BaseDatabase, BDbDatabase, DebugDatabase, DelegatingDatabase, MemoryDatabase, RegistrationCache, RemoteDatabase, TrackingDatabase

public interface Database

Database is the abstract interface defining the storage subsystem. The subsystem is fully responsible for all persistence and garbage collection.

Author:

Rory Graves

Method Summary

void	acquireLock(ClientThreadId threadId, ID jemmId) Asynchronous request to acquire a lock.
void	clientDisconnect(ClientId clientId) Notification that the given client has disconnected, this call is only used on multi-client servers, allowing the server to free up resources associated with the client.
ClassInfo	getClassInfo(ClientId clientId, ClassId classId) Returns the class information for the given class id.
DatabaseDebugIF	getDebugInterface() Returns a debug interface for this database, or null if not available.
EnumInfo	getEnumInfo(ClientId clientId, EnumId enumId) Returns the information about the given enumeration.
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'
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... id) Asynchronous notification that the client has de-referenced the given id.
ClassId	registerClass(ClientId clientId, ClassInfo classInfo) Register a user class.
EnumId	registerEnum(ClientId clientId, EnumInfo enumInfo) Register an enumerated type.
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.
ObjectSyncResp	synchroniseObject(ClientId clientId, ID jemmId, ObjectSyncData syncData) Synchronise a client held object with the server.

Method Detail

registerClass

ClassId registerClass(ClientId clientId,
                      ClassInfo classInfo)
                      throws StructureModifiedException

Register a user class.

Parameters:

clientId - The registering client.

classInfo - The information about the loaded user class (name/fields).

Returns:

The class id of the registered class.

Throws:

StructureModifiedException - if the class has been modified and the Database does not accept the change

registerEnum

EnumId registerEnum(ClientId clientId,
                    EnumInfo enumInfo)
                    throws StructureModifiedException

Register an enumerated type.

Parameters:

clientId - The identity of the registering client.

enumInfo - The EnumInfo describing the enumerated type.

Returns:

Returns the id of the registered enum type.

Throws:

StructureModifiedException - If a modification to the enum is detected.

acquireLock

void acquireLock(ClientThreadId threadId,
                 ID jemmId)

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

Parameters:

threadId - The requesting thread.

jemmId - The id of the object to lock.

setClientLockAcquiredListener

void setClientLockAcquiredListener(ClientId clientId,
                                   LockAcquiredListener listener)

Register a lock listener

Parameters:

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

listener - The listener to register.

removeLockAcquiredListener

void removeLockAcquiredListener(ClientId clientId)

Remove a lock listener

Parameters:

clientId - The lock listener to remove.

releaseLock

void releaseLock(ClientThreadId threadId,
                 ID jemmId)

Release the given lock held by the thread.

Parameters:

threadId - The thread currently holding the lock.

jemmId - The id of the object to release.

getObject

GetObjectResp getObject(ClientId clientId,
                        ID jemmId)

Retrieves an object's information from the database.

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

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

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

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.

setRoot

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

Set the persistent root reference to the given object.

Parameters:

clientId - The id of the requesting client.

rootName - The name of the persistent root.

newValue - The new value of the root.

setRootIfNull

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. This is an atomic operation.

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.

newObject

ID newObject(ClientId clientId,
             ClassId classId)

Notification of a new user object creation by the client.

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.

synchroniseObject

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

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

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

referenceCleared

void referenceCleared(ClientId clientId,
                      ID... id)

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

Parameters:

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

id - The ID that has been de-referenced.

getClassInfo

ClassInfo getClassInfo(ClientId clientId,
                       ClassId classId)

Returns the class information for the given class id.

Parameters:

clientId - The id of the requesting client.

classId - The id of the held class.

Returns:

The class information for the held class.

getEnumInfo

EnumInfo getEnumInfo(ClientId clientId,
                     EnumId enumId)

Returns the information about the given enumeration.

Parameters:

clientId - The id of the requesting client.

enumId - The id of the enumerated type.

Returns:

The classname of the registered enum type.

Throws:

JEMMInternalException - If the enum type is not found.

getDebugInterface

DatabaseDebugIF getDebugInterface()

Returns a debug interface for this database, or null if not available.

Returns:

The debug interface for this database, or null if not available.

clientDisconnect

void clientDisconnect(ClientId clientId)

Notification that the given client has disconnected, this call is only used on multi-client servers, allowing the server to free up resources associated with the client.

Parameters:

clientId - The id of the client that has disconnected.

processTypeRequest

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

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.

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.