src/org/vamsas/client/IClient.java

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