src/org/vamsas/client/Iclient.java

   1 /**
   2  * org.vamsas.client.Iclient
   3  *
   4  */
   5 package org.vamsas.client;
   6
   7 import java.beans.EventHandler;
   8 import java.beans.PropertyChangeListener;
   9 import java.util.EventListener;
  10
  11 /**
  12  * Defines the methods availabable to a vamsas
  13  * application for interacting with its Vorba agent
  14  * created by an IclientFactory instance for a particular session,
  15  * user, and application handle.
  16  * (it's VORBA, not CORBA!)
  17  */
  18
  19 public interface Iclient {
  20
  21   /**
  22    * Self-documenting/describing info for the application to present
  23    * to the user.
  24    * TODO: formalise this for describing VAMSAS system, a particular
  25    * Vorba client agent, and a particular session.
  26    * @returns string like VamsasClient v.1.1.1 (GPL) and whatever
  27    */
  28   String getAbout();
  29
  30   /**
  31    * TODO: Is this not be the same as the SessionUrn ?
  32    * @return current SessionUrn
  33    */
  34     public String getSessionUrn();
  35     /**
  36      * Returns a valid URN for other applications to connect to
  37      * the vamsas session.
  38      * @return session handle for this session.
  39      */
  40     public SessionHandle getSessionHandle();
  41     /**
  42      * Included for applications with several ClientHandle
  43      * identities.
  44      * @return ClientHandle used to interact with
  45      * other Vamsas applications.
  46      */
  47     public ClientHandle getClientHandle();
  48     /**
  49      *
  50      * @return UserHandle used when interacting
  51      * with other Vamsas applications.
  52      */
  53     public UserHandle getUserHandle();
  54     /**
  55      * Method called by client application on exit.
  56      * Vorba will inform other clients if they exist.
  57      * If this is the last application in the session
  58      * then the session will be closed.
  59      * Note: The application should be ready to handle
  60      * 'RequestToCloseDocument' events from the Vorba
  61      * agent in the latter case and so prompt the user
  62      * to save the session locally.
  63      * TODO: pick a better name ?
  64      */
  65     void finalizeClient();
  66     /**
  67      * register handler for updates for the current session
  68      */
  69     void addDocumentUpdateHandler(EventListener evt);
  70     /**
  71      * get vamsas document with
  72      * user and app specific data
  73      */
  74     IClientDocument getClientDocument();
  75     /**
  76      * Queue new Vorba objects for storage and propagation
  77      * to other clients (via Event.DOCUMENT_UPDATE based
  78      * notification of document change)
  79      */
  80     void updateDocument(IClientDocument newdoc);
  81     /**
  82      * Any application may call storeDocument to
  83      * save a local copy of the current vamsas document
  84      * including all application specific entries.
  85      *
  86      * @param location to write zip file
  87      */
  88     void storeDocument(java.io.File location);
  89     /**
  90      * Add a listener to a particular event chain.
  91      * See org.vamsas.client.Events for allowed values for EventChain.
  92      * The EventChain value is passed as the propertyName in the java.bean.PropertyChangeEvent
  93      * TODO: build our own vamsas Event/Listener model.
  94      * @param EventChain Name of event. Blank/null registers handler for all events.
  95      * @param evt - event handler function.
  96      */
  97     void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
  98 }