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
   9 /**
  10  * Defines the methods availabable to a vamsas
  11  * application for interacting with its Vorba agent
  12  * created by an IClientFactory instance for a particular session,
  13  * user, and application handle.
  14  * (it's VORBA, not CORBA!)
  15  * TODO: add exceptions for timeouts raised when there are problems accessing session data (because another application is hogging it).
  16  * TODO: 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)
  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   public 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     public void finalizeClient();
  66     /**
  67      * register handler for updates for the current session
  68      */
  69     public void addDocumentUpdateHandler(PropertyChangeListener evt);
  70     /**
  71      * get vamsas document with
  72      * user and app specific data
  73      * IClientDocuments are not thread-safe.
  74      */
  75     public IClientDocument getClientDocument();
  76     /**
  77      * Queue new Vorba objects for storage and propagation
  78      * to other clients (via Event.DOCUMENT_UPDATE based
  79      * notification of document change)
  80      * New objects without provenance information will be
  81      * given a default entry using the IClient's application,
  82      * user (and session) handles
  83      */
  84     public void updateDocument(IClientDocument newdoc);
  85     /**
  86      * Any application may call storeDocument to
  87      * save a local copy of the current vamsas document
  88      * including all application specific entries.
  89      *
  90      * @param location to write zip file
  91      */
  92     public void storeDocument(java.io.File location);
  93     /**
  94      * Add a listener to a particular event chain.
  95      * See org.vamsas.client.Events for allowed
  96      * values for EventChain.
  97      * The EventChain value is passed as the
  98      * propertyName in the java.bean.PropertyChangeEvent
  99      * TODO: extend class to form own vamsas Event/Listener model.
 100      * @param EventChain Name of event. Blank/null registers handler for all events.
 101      * @param evt - event handler function.
 102      */
 103     public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
 104     /**
 105      * client application calls this to force the
 106      * Vorba client to check for updates immediately.
 107      *
 108      */
 109     public void pollUpdate();
 110
 111     /**
 112      * Client application calls this after any pre-session initialization
 113      * (registering of Handlers, etc)
 114      * Exceptions are raised for any failures. Any stateful calls to the session prior to
 115      * this will result in an implicit call to joinSession - if that results in an exception
 116      * then the VamsasClient should raise an Error.
 117      * TODO: create VAMSAS exception hierarchy (in a language agnostic manner)
 118      */
 119     public void joinSession() throws Exception;
 120 }