1 package org.sourceforge.jemm.client;
2
3 import org.sourceforge.jemm.database.ClassId;
4 import org.sourceforge.jemm.database.ClassInfo;
5 import org.sourceforge.jemm.database.ClientId;
6 import org.sourceforge.jemm.database.ClientThreadId;
7 import org.sourceforge.jemm.database.EnumId;
8 import org.sourceforge.jemm.database.EnumInfo;
9 import org.sourceforge.jemm.database.LockAcquiredListener;
10 import org.sourceforge.jemm.database.StructureModifiedException;
11 import org.sourceforge.jemm.types.ID;
12 import org.sourceforge.jemm.util.JEMMObject;
13
14 /**
15 * An ObjectDatabase is similar to a Database but instead of working with
16 * Field values it works on the constructed Objects. This is only used Internally
17 * by the client for a number of pieces of functionality that benefit from
18 * pre-created objects such as reference tracking for GC purposes and caching.
19 *
20 * @author Paul Keeble
21 *
22 */
23 public interface ObjectDatabase extends ObjectSource,TypeRequestHandler {
24 /**
25 * Retrieves an object's information from the database or a local
26 * cache if the object has already been retrieved and still in memory.
27 *
28 * @param jemmId The id of the object to retrieve.
29 * @return The object information (class type, field values etc.).
30 */
31 JEMMObject getObject(ID jemmId);
32
33 /**
34 * Retrieves an object's information from the database but
35 * always calls the underlying database, updating the cache.
36 *
37 * @param jemmId The id of the object to retrieve.
38 * @return The object information (class type, field values etc.).
39 */
40 JEMMObject getRefreshedObject(ID jemmId);
41
42 /**
43 * Retrieves the fields of the object again from the store and updates
44 * the passed object with all the values.
45 *
46 * This call may never be cached as its intention is to make sure
47 * everything is up to date in a locked scenario.
48 *
49 * @param obj The object to retrieve and update
50 */
51 void refreshObject(JEMMObject obj);
52
53 /**
54 * Synchronise a client held object with the server. Passing in the current client version and
55 * any updated fields this method returns the new version number of the object and any fields updated
56 * remotely (by another client).
57 * @param syncObject The object being synchronized.
58 */
59 void synchroniseObject(JEMMObject syncObject);
60
61 /**
62 * Set the persistent root reference to the given object.
63 * @param rootName The name of the persistent root.
64 * @param newValue The new value of the root.
65 */
66 void setRoot(String rootName,JEMMObject newValue);
67
68 /**
69 * Sets the persistent root reference to the given object, if the root is currently null.
70 * This is an atomic operation.
71 * @param rootName The name of the persistent root.
72 * @param newValue The new value of the root.
73 * @return The old value if it was not null, or the recently set value.
74 */
75 JEMMObject setRootIfNull(String rootName,JEMMObject newValue);
76
77 /**
78 * Returns the object stored in the persistent root called 'rootName'
79 * @param rootName The name of the persistent root.
80 * @return The ID of the object stored in the persistent root, or null if none.
81 */
82 JEMMObject getRoot(String rootName);
83
84 /**
85 * Register a user class.
86 * @param classInfo The information about the loaded user class (name/fields).
87 * @return The class id of the registered class.
88 * @throws StructureModifiedException if the class has been modified
89 * and the Database does not accept the change
90 */
91 ClassId registerClass(ClassInfo classInfo) throws StructureModifiedException;
92
93 /**
94 * Register an enumerated type.
95 * @param enumInfo The enumeration type information
96 * @return Returns the id of the registered enum type.
97 * @throws StructureModifiedException If a modification to the enum is detected.
98 */
99 EnumId registerEnum(EnumInfo enumInfo) throws StructureModifiedException;
100
101 /**
102 * Asynchronous request to acquire a lock. This method will return immediately,
103 * but the caller should wait until notified by the LockAcquiredListener callback.
104 * @param threadId The requesting thread.
105 * @param jemmId The id of the object to lock.
106 */
107 void acquireLock(ClientThreadId threadId,ID jemmId);
108
109 /**
110 * Register a lock listener
111 * @param clientId The client who is interested in their lock event notifications.
112 * @param listener The listener to register.
113 */
114 void setClientLockAcquiredListener(ClientId clientId,LockAcquiredListener listener);
115
116 /**
117 * Remove a lock listener
118 * @param clientId The id the the client who is no longer interested in lock events.
119 */
120 void removeLockAcquiredListener(ClientId clientId);
121
122 /**
123 * Release the given lock held by the thread.
124 * @param threadId The thread currently holding the lock.
125 * @param jemmId The id of the object to release.
126 */
127 void releaseLock(ClientThreadId threadId,ID jemmId);
128
129 /**
130 * Notification of a new user object creation by the client.
131 * @param classId The class id of the new object (must be previously registered).
132 * @return The ID assigned to the new object.
133 */
134 ID newObject(ClassId classId,JEMMObject obj);
135
136 /**
137 * Returns the class information for the given class id.
138 * @param classId The id of the held class.
139 * @return The class information for the held class.
140 */
141 ClassInfo getClassInfo(ClassId classId);
142
143 /**
144 * Returns the classname for the given enum type id.
145 * @param enumId The enum type id.
146 * @return The classname of the registered enum type.
147 */
148 EnumInfo getEnumInfo(EnumId enumId);
149 }