first version sent out to Iain and Pierre

[vamsas.git] / src / org / vamsas / client / Iclient.java

diff --git a/src/org/vamsas/client/Iclient.java b/src/org/vamsas/client/Iclient.java
index 96a7711..d8ec50d 100644 (file)
--- a/src/org/vamsas/client/Iclient.java
+++ b/src/org/vamsas/client/Iclient.java
@@ -3,46 +3,96 @@
  * 
  */
 package org.vamsas.client;
-Interface Iclient {
+
+import java.beans.EventHandler;
+import java.beans.PropertyChangeListener;
+import java.util.EventListener;
+
+/**
+ * Defines the methods availabable to a vamsas
+ * application for interacting with its Vorba agent
+ * created by an IclientFactory instance for a particular session, 
+ * user, and application handle.
+ * (it's VORBA, not CORBA!)
+ */
+
+public interface Iclient {
+  
+  /**
+   * Self-documenting/describing info for the application to present 
+   * to the user.
+   * TODO: 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
+   */
+  String getAbout();
+
+  /**
+   * TODO: Is this not be the same as the SessionUrn ?
+   * @return current SessionUrn
+   */
+    public String getSessionUrn();
     /**
-     * Define the methods availabable to a vamsas
-     * application for interacting with the vamsas 
-     * object broker
-     * (it's VORBA, not CORBA!)
+     * Returns a valid URN for other applications to connect to 
+     * the vamsas session.
+     * @return session handle for this session.
      */
+    public SessionHandle getSessionHandle();
     /**
-     * static methods for returning a new instance 
-     * of vorba with or without a session urn. 
+     * Included for applications with several ClientHandle 
+     * identities.
+     * @return ClientHandle used to interact with 
+     * other Vamsas applications.
      */
-    Iclient getVorba(String ApplicationHandle);
-    Iclient getVorba(String ApplicationHandle, String SessionUrn);
+    public ClientHandle getClientHandle();
     /**
-     * Extend to multi-user. By default is to use current username
-     *
-     * Iclient getVorba(String ApplicationHandle, String UserUrn);
+     * 
+     * @return UserHandle used when interacting
+     * with other Vamsas applications.
      */
-
+    public UserHandle getUserHandle();
     /**
-     * Instance methods
+     * Method called by client application on exit. 
+     * Vorba will inform other clients if they exist. 
+     * If this is the last application in the session 
+     * then the session will be closed.
+     * Note: The application should be ready to handle 
+     * '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 ?
      */
+    void finalizeClient();
     /**
-     *  Return current SessionUrni
+     * register handler for updates for the current session
      */
-    String getSessionUrn();
+    void addDocumentUpdateHandler(EventListener evt);
     /**
-     * get vamsas document with app specific data
+     * get vamsas document with 
+     * user and app specific data
      */
-    VamsasClientDocument getDocument();
+    IClientDocument getClientDocument();
     /**
-     * register handler for updates for the current session
+     * Queue new Vorba objects for storage and propagation 
+     * to other clients (via Event.DOCUMENT_UPDATE based 
+     * notification of document change)
      */
-    void addDocumentUpdateHandler(java.util.EventHandler evt);
+    void updateDocument(IClientDocument newdoc);
     /**
-     * Self-documenting/describing info for presenting to user
-     * returns string like VamsasClient v.1.1.1 (GPL) and whatever
+     * Any application may call storeDocument to 
+     * save a local copy of the current vamsas document
+     * including all application specific entries.
+     * 
+     * @param location to write zip file
      */
-    String getAboutVamsasClient();
-
-    void closeVamsasDocument();
-
+    void storeDocument(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: build our own vamsas Event/Listener model.
+     * @param EventChain Name of event. Blank/null registers handler for all events.
+     * @param evt - event handler function.
+     */
+    void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
 }