src/uk/ac/vamsas/client/IClient.java

   1 /**
   2  * uk.ac.vamsas.client.IClient
   3  *
   4  */
   5 package uk.ac.vamsas.client;
   6
   7 import java.beans.PropertyChangeListener;
   8 import java.io.IOException;
   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  * LATER: add exceptions for timeouts raised when there are problems accessing session data (because another application is hogging it).
  17  * 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)
  18  */
  19
  20 public interface IClient {
  21
  22   /**
  23    * Self-documenting/describing info for the application to present
  24    * to the user.
  25    * LATER: formalise this for describing VAMSAS system, a particular
  26    * Vorba client agent, and a particular session.
  27    * @return string like VamsasClient v.1.1.1 (GPL) and whatever
  28    */
  29   public String getAbout();
  30
  31   /**
  32    * convenience method to get the SessionUrn as a string (for passing directly to a text box...).
  33    * @return current SessionUrn
  34    */
  35     public String getSessionUrn();
  36     /**
  37      * Returns a valid URN for other applications to connect to
  38      * the vamsas session.
  39      * @return session handle for this session.
  40      */
  41     public SessionHandle getSessionHandle();
  42     /**
  43      * Included for applications with several ClientHandle
  44      * identities.
  45      * @return ClientHandle used to interact with
  46      * other Vamsas applications.
  47      */
  48     public ClientHandle getClientHandle();
  49     /**
  50      *
  51      * @return UserHandle used when interacting
  52      * with other Vamsas applications.
  53      */
  54     public UserHandle getUserHandle();
  55     /**
  56      * Method called by client application on exit.
  57      * Vorba will inform other clients if they exist.
  58      * If this is the last application in the session
  59      * then the session will be closed.
  60      * Note: The application should be ready to handle
  61      * 'RequestToCloseDocument' events from the Vorba
  62      * agent in the latter case and so prompt the user
  63      * to save the session locally.
  64      * LATER: pick a better name ?
  65      */
  66     public void finalizeClient();
  67     /**
  68      * register handler for updates for the current session
  69      */
  70     public void addDocumentUpdateHandler(PropertyChangeListener evt);
  71     /**
  72      * get vamsas document with
  73      * user and app specific data
  74      * IClientDocuments are not thread-safe.
  75      * TODO: New exception for failed document lock.
  76      * @throws IOException if lock is not obtainable for the document in the session
  77      */
  78     public IClientDocument getClientDocument() throws IOException;
  79     /**
  80      * Queue new Vorba objects for storage and propagation
  81      * to other clients (via Event.DOCUMENT_UPDATE based
  82      * notification of document change)
  83      * New objects without provenance information will be
  84      * given a default entry using the IClient's application,
  85      * user (and session) handles
  86      * Validity of IClientDocument object instances after this call is implementation dependent
  87      * TODO: consider refactoring to remove the redundant IClientDocument parameter for this method
  88      */
  89     public void updateDocument(IClientDocument newdoc);
  90     /**
  91      * Any application may call storeDocument to
  92      * save a local copy of the current vamsas document
  93      * including all application specific entries.
  94      *
  95      * @param location to write zip file
  96      */
  97     public void storeDocument(java.io.File location);
  98     /**
  99      * Any application may call importDocument to merge a stored
 100      * vamsasDocument into the current session.
 101      * Note: use a IClientFactory's implementation to make sessions out of vamsas documents
 102      * TODO: this is not currently implemented by SimpleClient - and may be dropped from the first version of the interface.
 103      * LATER: VAMSAS: The IClient implementation will handle all ID 'relocations'
 104      * @param location
 105      */
 106     public void importDocument(java.io.File location);
 107     /**
 108      * Add a listener to a particular event chain.
 109      * See uk.ac.vamsas.client.Events for allowed
 110      * values for EventChain.
 111      * The EventChain value is passed as the
 112      * propertyName in the java.bean.PropertyChangeEvent
 113      * LATER: extend class to form own vamsas Event/Listener model.
 114      * @param EventChain Name of event. Blank/null registers handler for all events.
 115      * @param evt - event handler function.
 116      */
 117     public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
 118     /**
 119      * Sets the update handler that will be called when any updates occur to objects of type rootObject.
 120      * @param rootObject
 121      * @param handler
 122      */
 123     public void setUpdateHandler(IObjectUpdate handler);
 124     public IObjectUpdate getUpdateHandler(Class rootObject);
 125     public void removeUpdateHandler(Class rootObject);
 126     public IObjectUpdate[] getUpdateHandlers();
 127     /**
 128      * client application calls this to force the
 129      * Vorba client to check for updates immediately.
 130      *
 131      */
 132     public void pollUpdate();
 133
 134     /**
 135      * Client application calls this after any pre-session initialization
 136      * (registering of Handlers, etc)
 137      * Exceptions are raised for any failures. Any stateful calls to the session prior to
 138      * this will result in an implicit call to joinSession - if that results in an exception
 139      * then the VamsasClient should raise an Error.
 140      * LATER: create VAMSAS exception hierarchy (in a language agnostic manner)
 141      */
 142     public void joinSession() throws Exception;
 143     /**
 144      * get the Vamsas Pick Manager for registering pick handlers and sending messages for the current session.
 145      * @return an object implementing IPickManager (which maybe the same as the IClient implementer)
 146      */
 147     public uk.ac.vamsas.client.picking.IPickManager getPickManager();
 148
 149 }