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