simplification of some events and clarification.

git-svn-id: https://svn.lifesci.dundee.ac.uk/svn/repository/trunk@184 be28352e-c001-0410-b1a7-c7978e42abec

diff --git a/docs/VamsasSessionEventAnalysis.xls b/docs/VamsasSessionEventAnalysis.xls
index dbc3c6d..87bdc46 100644 (file)
Binary files a/docs/VamsasSessionEventAnalysis.xls and b/docs/VamsasSessionEventAnalysis.xls differ

diff --git a/src/org/vamsas/client/Events.java b/src/org/vamsas/client/Events.java
index c1b80e0..4a91f5a 100644 (file)
--- a/src/org/vamsas/client/Events.java
+++ b/src/org/vamsas/client/Events.java
@@ -3,13 +3,18 @@ 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";
 
@@ -17,7 +22,8 @@ public class Events {
    * Generated when a new vamsas document is created (perhaps from some existing
    * Vamsas data) so an application may do its own data space initialization.
    * Raised for a new application connecting to a vamsas document 
-   * which contains no existing data for that application.
+   * 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,8 +60,9 @@ 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 modified 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.
    * 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
@@ -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";