1 package org.sourceforge.jemm.database;
2
3 import org.sourceforge.jemm.JEMMInternalException;
4 import org.sourceforge.jemm.lifecycle.TypeRequest;
5 import org.sourceforge.jemm.lifecycle.TypeResponse;
6 import org.sourceforge.jemm.types.ID;
7
8 /**
9 * Database is the abstract interface defining the storage subsystem. The subsystem is fully responsible
10 * for all persistence and garbage collection.
11 *
12 * @author Rory Graves
13 */
14 public interface Database {
15 /**
16 * Register a user class.
17 * @param clientId The registering client.
18 * @param classInfo The information about the loaded user class (name/fields).
19 * @return The class id of the registered class.
20 * @throws StructureModifiedException if the class has been modified
21 * and the Database does not accept the change
22 */
23 ClassId registerClass(ClientId clientId,ClassInfo classInfo) throws StructureModifiedException;
24
25 /**
26 * Register an enumerated type.
27 * @param clientId The identity of the registering client.
28 * @param enumInfo The EnumInfo describing the enumerated type.
29 * @return Returns the id of the registered enum type.
30 * @throws StructureModifiedException If a modification to the enum is detected.
31 */
32 EnumId registerEnum(ClientId clientId,EnumInfo enumInfo) throws StructureModifiedException;
33
34 /**
35 * Asynchronous request to acquire a lock. This method will return immediately,
36 * but the caller should wait until notified by the LockAcquiredListener callback.
37 * @param threadId The requesting thread.
38 * @param jemmId The id of the object to lock.
39 */
40 void acquireLock(ClientThreadId threadId,ID jemmId);
41
42 /**
43 * Register a lock listener
44 * @param clientId The id of the client registering for lock notifications.
45 * @param listener The listener to register.
46 */
47 void setClientLockAcquiredListener(ClientId clientId,LockAcquiredListener listener);
48
49 /**
50 * Remove a lock listener
51 * @param clientId The lock listener to remove.
52 */
53 void removeLockAcquiredListener(ClientId clientId);
54
55 /**
56 * Release the given lock held by the thread.
57 * @param threadId The thread currently holding the lock.
58 * @param jemmId The id of the object to release.
59 */
60 void releaseLock(ClientThreadId threadId,ID jemmId);
61
62 /**
63 * Retrieves an object's information from the database.
64 * @param clientId The id of the requesting client.
65 * @param jemmId The id of the object to retrieve.
66 * @return The object information (class type, field values etc.).
67 */
68 GetObjectResp getObject(ClientId clientId,ID jemmId);
69
70 /**
71 * Returns the object stored in the persistent root called 'rootName'
72 * @param clientId The id of the requesting client.
73 * @param rootName The name of the persistent root.
74 * @return The ID of the object stored in the persistent root, or null if none.
75 */
76 ID getRoot(ClientId clientId,String rootName);
77
78 /**
79 * Set the persistent root reference to the given object.
80 * @param clientId The id of the requesting client.
81 * @param rootName The name of the persistent root.
82 * @param newValue The new value of the root.
83 */
84 void setRoot(ClientId clientId,String rootName,ID newValue);
85
86 /**
87 * Sets the persistent root reference to the given object, if the root is currently null.
88 * This is an atomic operation.
89 * @param clientId The id of the requesting client.
90 * @param rootName The name of the persistent root.
91 * @param newValue The new value of the root.
92 * @return The old value if it was not null, or the recently set value.
93 */
94 ID setRootIfNull(ClientId clientId,String rootName,ID newValue);
95
96 /**
97 * Notification of a new user object creation by the client.
98 * @param clientId The id of the requesting client.
99 * @param classId The class id of the new object (must be previously registered).
100 * @return The ID assigned to the new object.
101 */
102 ID newObject(ClientId clientId,ClassId classId);
103
104 /**
105 * Synchronise a client held object with the server. Passing in the current client version and
106 * any updated fields this method returns the new version number of the object and any fields updated
107 * remotely (by another client).
108 * @param clientId The id of the requesting client.
109 * @param jemmId The id of the object.
110 * @param syncData The object synchronisation data (client version, updated fields)
111 * @return Returned synchronisation information, (new version number and updated fields).
112 */
113 ObjectSyncResp synchroniseObject(ClientId clientId,ID jemmId,ObjectSyncData syncData);
114
115 /**
116 * Asynchronous notification that the client has de-referenced the given id.
117 * @param clientId The client who is no longer referencing 'id'
118 * @param id The ID that has been de-referenced.
119 */
120 void referenceCleared(ClientId clientId,ID... id);
121
122 /**
123 * Returns the class information for the given class id.
124 * @param clientId The id of the requesting client.
125 * @param classId The id of the held class.
126 * @return The class information for the held class.
127 */
128 ClassInfo getClassInfo(ClientId clientId,ClassId classId);
129
130 /**
131 * Returns the information about the given enumeration.
132 * @param clientId The id of the requesting client.
133 * @param enumId The id of the enumerated type.
134 * @return The classname of the registered enum type.
135 * @throws JEMMInternalException If the enum type is not found.
136 */
137 EnumInfo getEnumInfo(ClientId clientId,EnumId enumId);
138
139 /**
140 * Returns a debug interface for this database, or null if not available.
141 * @return The debug interface for this database, or null if not available.
142 */
143 DatabaseDebugIF getDebugInterface();
144
145 /**
146 * Notification that the given client has disconnected, this call
147 * is only used on multi-client servers, allowing the server to
148 * free up resources associated with the client.
149 * @param clientId The id of the client that has disconnected.
150 */
151 void clientDisconnect(ClientId clientId);
152
153 /**
154 * Process a request from a jemm type implementation. This is a generic call where
155 * a package of data is passed to database the type handler and a response is returned.
156 *
157 * @param clientId The id of the requesting client.
158 * @param classId The id of the class making the request.
159 * @param objId The target object.
160 * @param request The request data.
161 * @return The response data supplied by the type handler.
162 */
163 TypeResponse<?> processTypeRequest(ClientId clientId,ClassId classId,ID objId,TypeRequest<?> request);
164 }