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    * convenience method to get the SessionUrn as a string (for passing directly to a text box...).
  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      * Any application may call importDocument to merge a stored
  95      * vamsasDocument into the current session.
  96      * Note: use a IClientFactory's implementation to make sessions out of vamsas documnts
  97      * TODO: LATER: VAMSAS: The IClient implementation will handle all ID 'relocations'
  98      * @param location
  99      */
 100     public void importDocument(java.io.File location);
 101     /**
 102      * Add a listener to a particular event chain.
 103      * See org.vamsas.client.Events for allowed
 104      * values for EventChain.
 105      * The EventChain value is passed as the
 106      * propertyName in the java.bean.PropertyChangeEvent
 107      * TODO: extend class to form own vamsas Event/Listener model.
 108      * @param EventChain Name of event. Blank/null registers handler for all events.
 109      * @param evt - event handler function.
 110      */
 111     public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
 112     /**
 113      * client application calls this to force the
 114      * Vorba client to check for updates immediately.
 115      *
 116      */
 117     public void pollUpdate();
 118
 119     /**
 120      * Client application calls this after any pre-session initialization
 121      * (registering of Handlers, etc)
 122      * Exceptions are raised for any failures. Any stateful calls to the session prior to
 123      * this will result in an implicit call to joinSession - if that results in an exception
 124      * then the VamsasClient should raise an Error.
 125      * TODO: create VAMSAS exception hierarchy (in a language agnostic manner)
 126      */
 127     public void joinSession() throws Exception;
 128 }