javadoc todo
[vamsas.git] / src / uk / ac / vamsas / client / Events.java
1 package uk.ac.vamsas.client;
2
3 /**
4  * Enumerates the event types generated during the lifecycle of a Vamsas
5  * session.
6  * See the excel spreadsheet in VamsasClient/docs/VamsasSessionEventAnalysis.xls for
7  * some more information about when these are generated and how they should be
8  * handled.
9  * 
10  */
11
12 public class Events {
13   /**
14    * Generated when a client has finished updating the document. 
15    * Client which has completed an update should
16    * not receive the event.
17    * NewValue: uk.ac.vamsas.client.IClient for session.
18    */
19   public static final String DOCUMENT_UPDATE = "uk.ac.vamsas.client.events.documentUpdateEvent";
20
21   /**
22    * Generated when a new vamsas document is created (perhaps from some existing
23    * Vamsas data) so an application may do its own data space initialization.
24    * Raised for a new application connecting to a vamsas document 
25    * NewValue: uk.ac.vamsas.client.IClient for session.
26    * LATER: DOCUMENT_CREATE event may be redundant
27    */
28   public static final String DOCUMENT_CREATE = "uk.ac.vamsas.client.events.documentCreateEvent";
29
30   /**
31    * Generated when a new vamsas client is attached to a session (Handle is
32    * passed) Note: the newly created client does not receive the event.
33    */
34   public static final String CLIENT_CREATION = "uk.ac.vamsas.client.events.clientCreateEvent";
35
36   /**
37    * Generated when a vamsas client leaves a session (Handle is passed to all
38    * others).
39    */
40   public static final String CLIENT_FINALIZATION = "uk.ac.vamsas.client.events.clientFinalizationEvent";
41
42   /**
43    * Generated prior to session Shutdown, after the last participating vamsas
44    * client has finalized.
45    * Probably only useful to IClientFactory implementations.
46    * NewValue: <Vamsas-session URN>
47    */
48   public static final String SESSION_SHUTDOWN = "uk.ac.vamsas.client.events.SessionShutdownEvent";
49
50   /**
51    * Generated for all clients when any client calls IClient.storeDocument() to
52    * allow them to store any updates before an offline copy of the session is
53    * created. 
54    * Any client that handles this should call the
55    * IClient.getDocument(), update and then IClient.updateDocument in the same
56    * handler thread (the lock on the document is held until the handler exits).
57    * EventName: <Vamsas-session URN>
58    * NewValue: uk.ac.vamsas.client.IClient for session.
59    */
60   public static final String DOCUMENT_FINALIZEAPPDATA = "uk.ac.vamsas.client.events.DocumentFinalizeAppData";
61
62   /**
63    * Generated by Vorba stub for the sole remaining client instance in a session, 
64    * when it makes a call to finalizeClient(). 
65    * It is only raised if the session has been modified since the 
66    * last call to storeDocument() by any application.
67    * LATER: copies of a document should be on a per-user basis for multi-user sessions. 
68    *  Sequence is as follows : 1. All other vamsas clients have
69    * called finalizeClient() 2. Final living client monitors closures, and
70    * realises that it is last. 3. Final client generates event to prompt
71    * associated application to inquire if the user wishes to save the document
72    * for future reference.
73    *  * Any call to finalizeClient in a thread other than the registered
74    * EventListener will block until the RequestToClose handler has exited.
75    * NewValue: uk.ac.vamsas.client.IClient for session.
76    */
77   public static final String DOCUMENT_REQUESTTOCLOSE = "uk.ac.vamas.client.DocumentRequestToCloseEvent";
78
79   public static java.util.Vector EventList = initList();
80
81   private static java.util.Vector initList() {
82     java.util.Vector vec = new java.util.Vector();
83     vec.add((Object) DOCUMENT_UPDATE);
84     vec.add((Object) DOCUMENT_CREATE);
85     vec.add((Object) CLIENT_CREATION);
86     vec.add((Object) CLIENT_FINALIZATION);
87     vec.add((Object) SESSION_SHUTDOWN);
88     vec.add((Object) DOCUMENT_REQUESTTOCLOSE);
89     vec.add((Object) DOCUMENT_FINALIZEAPPDATA);
90     return vec;
91   }
92 }