2 * This file is part of the Vamsas Client version 0.2.
3 * Copyright 2010 by Jim Procter, Iain Milne, Pierre Marguerite,
4 * Andrew Waterhouse and Dominik Lindner.
6 * Earlier versions have also been incorporated into Jalview version 2.4
7 * since 2008, and TOPALi version 2 since 2007.
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.
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.
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/>.
22 package uk.ac.vamsas.client;
24 import java.beans.PropertyChangeListener;
25 import java.io.IOException;
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)
37 public interface IClient {
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.
44 * @return string like VamsasClient v.1.1.1 (GPL) and whatever
46 public String getAbout();
49 * convenience method to get the SessionUrn as a string (for passing directly
52 * @return current SessionUrn
54 public String getSessionUrn();
57 * Returns a valid URN for other applications to connect to the vamsas
60 * @return session handle for this session.
62 public SessionHandle getSessionHandle();
65 * Included for applications with several ClientHandle identities.
67 * @return ClientHandle used to interact with other Vamsas applications.
69 public ClientHandle getClientHandle();
73 * @return UserHandle used when interacting with other Vamsas applications.
75 public UserHandle getUserHandle();
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 ?
84 public void finalizeClient();
87 * register handler for updates for the current session
89 public void addDocumentUpdateHandler(PropertyChangeListener evt);
92 * get vamsas document with user and app specific data IClientDocuments are
93 * not thread-safe. TODO: New exception for failed document lock.
96 * if lock is not obtainable for the document in the session
98 public IClientDocument getClientDocument() throws IOException;
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
109 public void updateDocument(IClientDocument newdoc);
112 * Any application may call storeDocument to save a local copy of the current
113 * vamsas document including all application specific entries.
118 public void storeDocument(java.io.File location);
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
130 public void importDocument(java.io.File location);
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.
139 * Name of event. Blank/null registers handler for all events.
141 * - event handler function.
143 public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
146 * Sets the update handler that will be called when any updates occur to
147 * objects of type rootObject.
152 public void setUpdateHandler(IObjectUpdate handler);
154 public IObjectUpdate getUpdateHandler(Class rootObject);
156 public void removeUpdateHandler(Class rootObject);
158 public IObjectUpdate[] getUpdateHandlers();
161 * client application calls this to force the Vorba client to check for
162 * updates immediately.
165 public void pollUpdate();
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)
175 public void joinSession() throws Exception;
178 * get the Vamsas Pick Manager for registering pick handlers and sending
179 * messages for the current session.
181 * @return an object implementing IPickManager (which maybe the same as the
182 * IClient implementer)
184 public uk.ac.vamsas.client.picking.IPickManager getPickManager();