X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Forg%2Fvamsas%2Fclient%2FEvents.java;h=4a91f5ada499bfdbf0d7840560980dc91a211678;hb=ea8b10ee787a2b1e2b35f2acb4dccaf12fd2a6fd;hp=babd39cd1962284f0d4a867273aa61b8ca4731af;hpb=3b046648062b93ab88457cc7cb93b0f5faa2f8d3;p=vamsas.git

diff --git a/src/org/vamsas/client/Events.java b/src/org/vamsas/client/Events.java
index babd39c..4a91f5a 100644
--- a/src/org/vamsas/client/Events.java
+++ b/src/org/vamsas/client/Events.java
@@ -3,21 +3,27 @@ package org.vamsas.client;
 /**
  * Enumerates the event types generated during the lifecycle of a Vamsas
  * session.
+ * See the excel spreadsheet in VamsasClient/docs/VamsasSessionEventAnalysis.xls for
+ * some more information about when these are generated and how they should be
+ * handled.
+ * 
  */
 
 public class Events {
   /**
-   * Generated when a client has finished updating the document. Passes
-   * applicationHandle of client so the updating client can recognise its own
-   * updates.
+   * Generated when a client has finished updating the document. 
+   * Client which has completed an update should
+   * not receive the event.
+   * NewValue: org.vamsas.client.IClient for session.
    */
   public static final String DOCUMENT_UPDATE = "org.vamsas.client.events.documentUpdateEvent";
 
   /**
    * Generated when a new vamsas document is created (perhaps from some existing
    * Vamsas data) so an application may do its own data space initialization.
-   * TODO: decide if this is called when an app is connected to a stored
-   * session...
+   * Raised for a new application connecting to a vamsas document 
+   * NewValue: org.vamsas.client.IClient for session.
+   * LATER: DOCUMENT_CREATE event may be redundant
    */
   public static final String DOCUMENT_CREATE = "org.vamsas.client.events.documentCreateEvent";
 
@@ -36,13 +42,16 @@ public class Events {
   /**
    * Generated prior to session Shutdown, after the last participating vamsas
    * client has finalized.
+   * Probably only useful to IClientFactory implementations.
+   * NewValue: <Vamsas-session URN>
    */
   public static final String SESSION_SHUTDOWN = "org.vamsas.client.events.SessionShutdownEvent";
 
   /**
    * Generated for all clients when any client calls IClient.storeDocument() to
    * allow them to store any updates before an offline copy of the session is
-   * created. Any client that handles this should call the
+   * created. 
+   * Any client that handles this should call the
    * IClient.getDocument(), update and then IClient.updateDocument in the same
    * handler thread (the lock on the document is held until the handler exits).
    * EventName: <Vamsas-session URN>
@@ -51,10 +60,11 @@ public class Events {
   public static final String DOCUMENT_FINALIZEAPPDATA = "org.vamsas.client.events.DocumentFinalizeAppData";
 
   /**
-   * Generated by Vorba stub for the sole remaining client, after the penultimate 
-   * client makes a call to finalizeClient(). It is only raised if the session has been modifies since the 
+   * Generated by Vorba stub for the sole remaining client instance in a session, 
+   * when it makes a call to finalizeClient(). 
+   * It is only raised if the session has been modified since the 
    * last call to storeDocument() by any application.
-   * TODO: LATER: copies of a document should be on a per-user basis for multi-user sessions. 
+   * LATER: copies of a document should be on a per-user basis for multi-user sessions. 
    *  Sequence is as follows : 1. All other vamsas clients have
    * called finalizeClient() 2. Final living client monitors closures, and
    * realises that it is last. 3. Final client generates event to prompt
@@ -62,7 +72,7 @@ public class Events {
    * for future reference.
    *  * Any call to finalizeClient in a thread other than the registered
    * EventListener will block until the RequestToClose handler has exited.
-   * 
+   * NewValue: org.vamsas.client.IClient for session.
    */
   public static final String DOCUMENT_REQUESTTOCLOSE = "org.vamas.client.DocumentRequestToCloseEvent";