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 }