X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Forg%2Fvamsas%2Fclient%2FIClient.java;h=c73aaa4395ca419946a95f3e0d1dbc9ddb21923a;hb=d4199f5cfea3a90baeb956c4beaa2f3e8c0597c6;hp=cebed2a0d705db5b67954f1d400387c4d7563724;hpb=074762e534ccb9623b6b67e5670644afb651aa7a;p=vamsas.git

diff --git a/src/org/vamsas/client/IClient.java b/src/org/vamsas/client/IClient.java
index cebed2a..c73aaa4 100644
--- a/src/org/vamsas/client/IClient.java
+++ b/src/org/vamsas/client/IClient.java
@@ -5,6 +5,7 @@
 package org.vamsas.client;
 
 import java.beans.PropertyChangeListener;
+import java.io.IOException;
 
 /**
  * Defines the methods availabable to a vamsas
@@ -12,6 +13,8 @@ import java.beans.PropertyChangeListener;
  * created by an IClientFactory instance for a particular session, 
  * user, and application handle.
  * (it's VORBA, not CORBA!)
+ * LATER: add exceptions for timeouts raised when there are problems accessing session data (because another application is hogging it).
+ * LATER: think about situations when two applications both want a ClientDocument at the same time - can one have read-only access (and be told that another is about to update)
  */
 
 public interface IClient {
@@ -19,14 +22,14 @@ public interface IClient {
   /**
    * Self-documenting/describing info for the application to present 
    * to the user.
-   * TODO: formalise this for describing VAMSAS system, a particular 
+   * LATER: formalise this for describing VAMSAS system, a particular 
    * Vorba client agent, and a particular session.
-   * @returns string like VamsasClient v.1.1.1 (GPL) and whatever
+   * @return string like VamsasClient v.1.1.1 (GPL) and whatever
    */
   public String getAbout();
   
   /**
-   * TODO: Is this not be the same as the SessionUrn ?
+   * convenience method to get the SessionUrn as a string (for passing directly to a text box...).
    * @return current SessionUrn
    */
     public String getSessionUrn();
@@ -58,7 +61,7 @@ public interface IClient {
      * 'RequestToCloseDocument' events from the Vorba 
      * agent in the latter case and so prompt the user 
      * to save the session locally.
-     * TODO: pick a better name ?
+     * LATER: pick a better name ?
      */
     public void finalizeClient();
     /**
@@ -68,8 +71,11 @@ public interface IClient {
     /**
      * get vamsas document with 
      * user and app specific data
+     * IClientDocuments are not thread-safe.
+     * TODO: New exception for failed document lock.
+     * @throws IOException if lock is not obtainable for the document in the session
      */
-    public IClientDocument getClientDocument();
+    public IClientDocument getClientDocument() throws IOException;
     /**
      * Queue new Vorba objects for storage and propagation 
      * to other clients (via Event.DOCUMENT_UPDATE based 
@@ -77,6 +83,8 @@ public interface IClient {
      * New objects without provenance information will be 
      * given a default entry using the IClient's application, 
      * user (and session) handles
+     * Validity of IClientDocument object instances after this call is implementation dependent
+     * TODO: consider refactoring to remove the redundant IClientDocument parameter for this method
      */
     public void updateDocument(IClientDocument newdoc);
     /**
@@ -88,12 +96,20 @@ public interface IClient {
      */
     public void storeDocument(java.io.File location);
     /**
+     * Any application may call importDocument to merge a stored
+     * vamsasDocument into the current session.
+     * Note: use a IClientFactory's implementation to make sessions out of vamsas documnts
+     * LATER: VAMSAS: The IClient implementation will handle all ID 'relocations'
+     * @param location
+     */
+    public void importDocument(java.io.File location);
+    /**
      * Add a listener to a particular event chain.
      * See org.vamsas.client.Events for allowed 
      * values for EventChain.
      * The EventChain value is passed as the 
      * propertyName in the java.bean.PropertyChangeEvent
-     * TODO: extend class to form own vamsas Event/Listener model.
+     * LATER: extend class to form own vamsas Event/Listener model.
      * @param EventChain Name of event. Blank/null registers handler for all events.
      * @param evt - event handler function.
      */
@@ -104,4 +120,14 @@ public interface IClient {
      *
      */
     public void pollUpdate();
+    
+    /**
+     * Client application calls this after any pre-session initialization 
+     * (registering of Handlers, etc)
+     * Exceptions are raised for any failures. Any stateful calls to the session prior to
+     * this will result in an implicit call to joinSession - if that results in an exception
+     * then the VamsasClient should raise an Error.
+     * LATER: create VAMSAS exception hierarchy (in a language agnostic manner)
+     */
+    public void joinSession() throws Exception;
 }