1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28 package zeus.agents;
29
30 import java.util.*;
31 import zeus.util.*;
32 import zeus.concepts.Performative;
33
34 /***
35 * <P> This abstract class provides an interface to storage platforms so
36 * that messaging data (i.e. communication sessions among agents) may be
37 * stored for future playback and manipulation.
38 * It acts a bridge between a ZEUS database proxy (i.e. DbProxy) and
39 * and a persistent storage mechanism (e.g. a flat file or a database such
40 * as Oracle). Typically a ZEUS Visualiser agent talks to a DbProxy which
41 * in turn forwards the requests to subclasses of this abstract class. A
42 * class that extends this abstract class should provide implementations
43 * for following methods:
44 * <pre>
45 * public abstract void createSession(String replyKey, String agent,
46 * String sessionType, String sessionId, String accessKey);
47 * public abstract void deleteSession(String replyKey, String agent,
48 * String sessionType, String sessionId);
49 * public abstract void getAllSessions(String replyKey, String agent,
50 * String sessionType);
51 * public abstract void deleteSessionType(String replyKey, String agent,
52 * String sessionType);
53 * public abstract void openSession(String replyKey, String agent,
54 * String sessionType, String sessionId, String accessKey);
55 *
56 * public abstract void saveRecord(String replyKey, String agent,
57 * String accessKey, String record);
58 * public void closeSession(String replyKey,String agent,String accessKey);
59 * public abstract void nextRecord(String replyKey,String agent,String accessKey);
60 * public abstract void priorRecord(String replyKey,String agent,String accessKey);
61 * public abstract void beginSession(String replyKey,String agent,String accessKey);
62 * public abstract void endSession(String replyKey,String agent,String accessKey);
63 * public abstract void getAgents(String replyKey,String agent,String accessKey);
64 * public abstract void countRecords(String replyKey,String agent,String accessKey);
65 *
66 * </pre>
67 * <br>
68 * The methods have all or some of the following arguments:
69 * <br> String <B> replyKey </B><I> Recipient's (i.e.the ZEUS Visualiser
70 * agent) conversation key.</I>
71 * <br> String <B> agent </B> <I> The name of the ZEUS Visualiser agent who
72 * wants the communication sessions saved for future playback. </I>
73 * <br> String <B> sessionType </B> <I> The type of information being saved
74 * for
75 * future playback (i.e. the tool within which the communication session is
76 * taken place. Tools can be one of the following: Society
77 * Viewer, Report Viewer, Statistics Viewer, Remote Viewer and Control Tool
78 * Viewer. </I>
79 * <br> String <B>sessionId</B> <I> A unique identifier (typically the name
80 * of the persistent storage i.e. flat file or database) representing a
81 * communication session.</I>
82 * <br> String <B> accessKey </B><I> A handle representing an agent
83 * and session id used by subclasses of this abstract class to
84 * access the persistent storage. </I>
85 *<br>
86 * Each implemented method should return a Zeus Performative object (<I>
87 * using proxy.sendMsg(msg) where msg is a Performative object </I> ) by
88 * specifying whether the operation failed or succeeds. If the operation
89 * succeeds then instantiate a Performative class with <I> "inform" </I>
90 * or <I> "failure" </I> if it failed. Instantiating a Performative class
91 * should follow this format:
92 * <br> Performative msg = new Performative("failure");
93 * <br> msg.setReceiver(agent);
94 * <br> msg.setInReplyTo(replyKey);
95 * <br> msg.setContent("reason for failure or success");
96 * <br> proxy.sendMsg(msg);
97 */
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129 public abstract class PersistentStore {
130 protected DbProxy proxy = null;
131 private boolean verifyAccess = true;
132 private OrderedHashtable knownAgents = new OrderedHashtable();
133
134
135
136 /***
137 * Sets the proxy.
138 */
139 public void setProxy(DbProxy proxy) {
140 this.proxy = proxy;
141 }
142
143 /***
144 * Sets access level.
145 */
146 public void setAccess(boolean access){
147 verifyAccess = access;
148 }
149
150
151
152 /***
153 * Its purpose is to create a new session (i.e. a flat file or database
154 * table).
155 * Returns <I> done </I> as the content of a Performative object if the
156 * operation succeeds else return reasons for failure to the specified
157 * agent with the replyKey as agent's conversation key.
158 * <br> If the session exists open it for appending and return <I> done.
159 * </I> <br> If the session doesn't exit create it for writing and return
160 * <I> done.</I>
161 * <br> If aforementioned operations fails return <I> failure. </I>
162 */
163
164
165
166 public abstract void createSession(String replyKey, String agent,
167 String sessionType, String sessionId, String accessKey);
168
169
170 /***
171 * Given a session type, delete the session type with the name
172 * <I> sessionId.</I>
173 * Returns <I> done </I> as the content of a Performative object if the
174 * operation succeeds else return reasons for failure to the specified
175 * agent with the replyKey as agent's conversation key.
176 */
177 public abstract void deleteSession(String replyKey, String agent,
178 String sessionType, String sessionId);
179
180
181 /***
182 * Given a session type, list all sessions (tables) associated with
183 * that type.
184 * Returns <I> done </I> as the content of a Performative object if the
185 * operation succeeds else return reasons for failure to the specified
186 * agent with the replyKey as agent's conversation key.
187 */
188 public abstract void getAllSessions(String replyKey, String agent,
189 String sessionType);
190
191
192 /***
193 * Delete a session type with its associated sessions (i.e. tables).
194 * Returns <I> done </I> as the content of a Performative object if the
195 * operation succeeds else return reasons for failure to the specified
196 * agent with the replyKey as agent's conversation key.
197 */
198 public abstract void deleteSessionType(String replyKey, String agent,
199 String sessionType);
200
201
202 /***
203 * Given a session type, open the session with name <I> sessionId. </I>
204 * Returns <I> done </I> as the content of a Performative object if the
205 * operation succeeds else return reasons for failure to the specified
206 * agent with the replyKey as agent's conversation key.
207 */
208 public abstract void openSession(String replyKey, String agent,
209 String sessionType, String sessionId, String accessKey);
210
211 /***
212 * Save the record in a session identified by <I> accessKey. </I>
213 * Returns <I> done </I> as the content of a Performative object if the
214 * operation succeeds else return reasons for failure to the specified
215 * agent with the replyKey as agent's conversation key.
216 */
217 public abstract void saveRecord(String replyKey, String agent,
218 String accessKey, String record);
219
220
221 /***
222 * Close a session identified by <I> accessKey. </I>
223 * Returns <I> done </I> as the content of a Performative object if the
224 * operation succeeds else return reasons for failure to the specified
225 * agent with the replyKey as agent's conversation key.
226 */
227 public abstract void closeSession(String replyKey,String agent,String accessKey);
228
229
230 /***
231 * Returns the next record in a session identified by <I> accessKey.</I>
232 * Returns <I> done </I> as the content of a Performative object if the
233 * operation succeeds else return reasons for failure to the specified
234 * agent with the replyKey as agent's conversation key.
235 */
236
237 public abstract void nextRecord(String replyKey,String agent,String accessKey);
238
239
240 /***
241 * Returns the previous record in a session identified by <I> accessKey.
242 * </I>
243 * Returns <I> done </I> as the content of a Performative object if the
244 * operation succeeds else return reasons for failure to the specified
245 * agent with the replyKey as agent's conversation key.
246 */
247
248 public abstract void priorRecord(String replyKey,String agent,String accessKey);
249
250
251 /***
252 * Go to the beginning of a session identified by <I> accessKey.
253 * </I>
254 * Returns <I> done </I> as the content of a Performative object if the
255 * operation succeeds else return reasons for failure to the specified
256 * agent with the replyKey as agent's conversation key.
257 */
258 public abstract void beginSession(String replyKey,String agent,String accessKey);
259
260
261 /***
262 * Go to the end of a session identified by <I> accessKey.
263 * </I>
264 * Returns <I> done </I> as the content of a Performative object if the
265 * operation succeeds else return reasons for failure to the specified
266 * agent with the replyKey as agent's conversation key.
267 */
268 public abstract void endSession(String replyKey,String agent,String accessKey);
269
270
271 /***
272 * Returns all known agents associated with a given session identified by
273 * <I> accessKey. </I>
274 * Returns <I> done </I> as the content of a Performative object if the
275 * operation succeeds else return reasons for failure to the specified
276 * agent with the replyKey as agent's conversation key.
277 */
278 public abstract void getAgents(String replyKey,String agent,String accessKey);
279
280
281 /***
282 * Returns the number of records in a session identified by <I>
283 * accessKey. </I>
284 * Returns <I> done </I> as the content of a Performative object if the
285 * operation succeeds else return reasons for failure to the specified
286 * agent with the replyKey as agent's conversation key.
287 */
288 public abstract void countRecords(String replyKey,String agent,String accessKey);
289
290 protected boolean isAccessible(){
291 return verifyAccess;
292 }
293
294 }