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

   1 /*
   2  * This file is part of the Vamsas Client version 0.1.
   3  * Copyright 2009 by Jim Procter, Iain Milne, Pierre Marguerite,
   4  *  Andrew Waterhouse and Dominik Lindner.
   5  *
   6  * Earlier versions have also been incorporated into Jalview version 2.4
   7  * since 2008, and TOPALi version 2 since 2007.
   8  *
   9  * The Vamsas Client is free software: you can redistribute it and/or modify
  10  * it under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation, either version 3 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * The Vamsas Client is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with the Vamsas Client.  If not, see <http://www.gnu.org/licenses/>.
  21  */
  22 package uk.ac.vamsas.client;
  23
  24 import java.beans.PropertyChangeListener;
  25 import java.io.IOException;
  26
  27 /**
  28  * Defines the methods availabable to a vamsas application for interacting with
  29  * its Vorba agent created by an IClientFactory instance for a particular
  30  * session, user, and application handle. (it's VORBA, not CORBA!) LATER: add
  31  * exceptions for timeouts raised when there are problems accessing session data
  32  * (because another application is hogging it). LATER: think about situations
  33  * when two applications both want a ClientDocument at the same time - can one
  34  * have read-only access (and be told that another is about to update)
  35  */
  36
  37 public interface IClient {
  38
  39   /**
  40    * Self-documenting/describing info for the application to present to the
  41    * user. LATER: formalise this for describing VAMSAS system, a particular
  42    * Vorba client agent, and a particular session.
  43    *
  44    * @return string like VamsasClient v.1.1.1 (GPL) and whatever
  45    */
  46   public String getAbout();
  47
  48   /**
  49    * convenience method to get the SessionUrn as a string (for passing directly
  50    * to a text box...).
  51    *
  52    * @return current SessionUrn
  53    */
  54   public String getSessionUrn();
  55
  56   /**
  57    * Returns a valid URN for other applications to connect to the vamsas
  58    * session.
  59    *
  60    * @return session handle for this session.
  61    */
  62   public SessionHandle getSessionHandle();
  63
  64   /**
  65    * Included for applications with several ClientHandle identities.
  66    *
  67    * @return ClientHandle used to interact with other Vamsas applications.
  68    */
  69   public ClientHandle getClientHandle();
  70
  71   /**
  72    *
  73    * @return UserHandle used when interacting with other Vamsas applications.
  74    */
  75   public UserHandle getUserHandle();
  76
  77   /**
  78    * Method called by client application on exit. Vorba will inform other
  79    * clients if they exist. If this is the last application in the session then
  80    * the session will be closed. Note: The application should be ready to handle
  81    * 'RequestToCloseDocument' events from the Vorba agent in the latter case and
  82    * so prompt the user to save the session locally. LATER: pick a better name ?
  83    */
  84   public void finalizeClient();
  85
  86   /**
  87    * register handler for updates for the current session
  88    */
  89   public void addDocumentUpdateHandler(PropertyChangeListener evt);
  90
  91   /**
  92    * get vamsas document with user and app specific data IClientDocuments are
  93    * not thread-safe. TODO: New exception for failed document lock.
  94    *
  95    * @throws IOException
  96    *           if lock is not obtainable for the document in the session
  97    */
  98   public IClientDocument getClientDocument() throws IOException;
  99
 100   /**
 101    * Queue new Vorba objects for storage and propagation to other clients (via
 102    * Event.DOCUMENT_UPDATE based notification of document change) New objects
 103    * without provenance information will be given a default entry using the
 104    * IClient's application, user (and session) handles Validity of
 105    * IClientDocument object instances after this call is implementation
 106    * dependent TODO: consider refactoring to remove the redundant
 107    * IClientDocument parameter for this method
 108    */
 109   public void updateDocument(IClientDocument newdoc);
 110
 111   /**
 112    * Any application may call storeDocument to save a local copy of the current
 113    * vamsas document including all application specific entries.
 114    *
 115    * @param location
 116    *          to write zip file
 117    */
 118   public void storeDocument(java.io.File location);
 119
 120   /**
 121    * Any application may call importDocument to merge a stored vamsasDocument
 122    * into the current session. Note: use a IClientFactory's implementation to
 123    * make sessions out of vamsas documents TODO: this is not currently
 124    * implemented by SimpleClient - and may be dropped from the first version of
 125    * the interface. LATER: VAMSAS: The IClient implementation will handle all ID
 126    * 'relocations'
 127    *
 128    * @param location
 129    */
 130   public void importDocument(java.io.File location);
 131
 132   /**
 133    * Add a listener to a particular event chain. See uk.ac.vamsas.client.Events
 134    * for allowed values for EventChain. The EventChain value is passed as the
 135    * propertyName in the java.bean.PropertyChangeEvent LATER: extend class to
 136    * form own vamsas Event/Listener model.
 137    *
 138    * @param EventChain
 139    *          Name of event. Blank/null registers handler for all events.
 140    * @param evt
 141    *          - event handler function.
 142    */
 143   public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
 144
 145   /**
 146    * Sets the update handler that will be called when any updates occur to
 147    * objects of type rootObject.
 148    *
 149    * @param rootObject
 150    * @param handler
 151    */
 152   public void setUpdateHandler(IObjectUpdate handler);
 153
 154   public IObjectUpdate getUpdateHandler(Class rootObject);
 155
 156   public void removeUpdateHandler(Class rootObject);
 157
 158   public IObjectUpdate[] getUpdateHandlers();
 159
 160   /**
 161    * client application calls this to force the Vorba client to check for
 162    * updates immediately.
 163    *
 164    */
 165   public void pollUpdate();
 166
 167   /**
 168    * Client application calls this after any pre-session initialization
 169    * (registering of Handlers, etc) Exceptions are raised for any failures. Any
 170    * stateful calls to the session prior to this will result in an implicit call
 171    * to joinSession - if that results in an exception then the VamsasClient
 172    * should raise an Error. LATER: create VAMSAS exception hierarchy (in a
 173    * language agnostic manner)
 174    */
 175   public void joinSession() throws Exception;
 176
 177   /**
 178    * get the Vamsas Pick Manager for registering pick handlers and sending
 179    * messages for the current session.
 180    *
 181    * @return an object implementing IPickManager (which maybe the same as the
 182    *         IClient implementer)
 183    */
 184   public uk.ac.vamsas.client.picking.IPickManager getPickManager();
 185
 186 }