X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fuk%2Fac%2Fvamsas%2Fclient%2FIClient.java;h=c59a26c7aefa1435caa33a428fc07c02ef8bb16a;hb=844ccad5a3fcbedec17b2af66d460f31abc7cff1;hp=5df2f205205fc8fb1924f1928986b9bd1916ad18;hpb=ea8b10ee787a2b1e2b35f2acb4dccaf12fd2a6fd;p=vamsas.git diff --git a/src/uk/ac/vamsas/client/IClient.java b/src/uk/ac/vamsas/client/IClient.java index 5df2f20..c59a26c 100644 --- a/src/uk/ac/vamsas/client/IClient.java +++ b/src/uk/ac/vamsas/client/IClient.java @@ -1,6 +1,23 @@ -/** - * uk.ac.vamsas.client.IClient +/* + * This file is part of the Vamsas Client version 0.1. + * Copyright 2009 by Jim Procter, Iain Milne, Pierre Marguerite, + * Andrew Waterhouse and Dominik Lindner. + * + * Earlier versions have also been incorporated into Jalview version 2.4 + * since 2008, and TOPALi version 2 since 2007. * + * The Vamsas Client is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * The Vamsas Client is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with the Vamsas Client. If not, see . */ package uk.ac.vamsas.client; @@ -8,135 +25,162 @@ import java.beans.PropertyChangeListener; import java.io.IOException; /** - * Defines the methods availabable to a vamsas - * application for interacting with its Vorba agent - * created by an IClientFactory instance for a particular session, - * user, and application handle. - * (it's VORBA, not CORBA!) - * LATER: add exceptions for timeouts raised when there are problems accessing session data (because another application is hogging it). - * 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) + * Defines the methods availabable to a vamsas application for interacting with + * its Vorba agent created by an IClientFactory instance for a particular + * session, user, and application handle. (it's VORBA, not CORBA!) LATER: add + * exceptions for timeouts raised when there are problems accessing session data + * (because another application is hogging it). 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) */ public interface IClient { - + /** - * Self-documenting/describing info for the application to present - * to the user. - * LATER: formalise this for describing VAMSAS system, a particular + * Self-documenting/describing info for the application to present to the + * user. LATER: formalise this for describing VAMSAS system, a particular * Vorba client agent, and a particular session. + * * @return string like VamsasClient v.1.1.1 (GPL) and whatever */ public String getAbout(); - + /** - * convenience method to get the SessionUrn as a string (for passing directly to a text box...). + * convenience method to get the SessionUrn as a string (for passing directly + * to a text box...). + * * @return current SessionUrn */ - public String getSessionUrn(); - /** - * Returns a valid URN for other applications to connect to - * the vamsas session. - * @return session handle for this session. - */ - public SessionHandle getSessionHandle(); - /** - * Included for applications with several ClientHandle - * identities. - * @return ClientHandle used to interact with - * other Vamsas applications. - */ - public ClientHandle getClientHandle(); - /** - * - * @return UserHandle used when interacting - * with other Vamsas applications. - */ - public UserHandle getUserHandle(); - /** - * Method called by client application on exit. - * Vorba will inform other clients if they exist. - * If this is the last application in the session - * then the session will be closed. - * Note: The application should be ready to handle - * 'RequestToCloseDocument' events from the Vorba - * agent in the latter case and so prompt the user - * to save the session locally. - * LATER: pick a better name ? - */ - public void finalizeClient(); - /** - * register handler for updates for the current session - */ - public void addDocumentUpdateHandler(PropertyChangeListener evt); - /** - * get vamsas document with - * user and app specific data - * IClientDocuments are not thread-safe. - * TODO: New exception for failed document lock. - * @throws IOException if lock is not obtainable for the document in the session - */ - public IClientDocument getClientDocument() throws IOException; - /** - * Queue new Vorba objects for storage and propagation - * to other clients (via Event.DOCUMENT_UPDATE based - * notification of document change) - * New objects without provenance information will be - * given a default entry using the IClient's application, - * user (and session) handles - * Validity of IClientDocument object instances after this call is implementation dependent - * TODO: consider refactoring to remove the redundant IClientDocument parameter for this method - */ - public void updateDocument(IClientDocument newdoc); - /** - * Any application may call storeDocument to - * save a local copy of the current vamsas document - * including all application specific entries. - * - * @param location to write zip file - */ - public void storeDocument(java.io.File location); - /** - * Any application may call importDocument to merge a stored - * vamsasDocument into the current session. - * Note: use a IClientFactory's implementation to make sessions out of vamsas documnts - * LATER: VAMSAS: The IClient implementation will handle all ID 'relocations' - * @param location - */ - public void importDocument(java.io.File location); - /** - * Add a listener to a particular event chain. - * See uk.ac.vamsas.client.Events for allowed - * values for EventChain. - * The EventChain value is passed as the - * propertyName in the java.bean.PropertyChangeEvent - * LATER: extend class to form own vamsas Event/Listener model. - * @param EventChain Name of event. Blank/null registers handler for all events. - * @param evt - event handler function. - */ - public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt); - /** - * Sets the update handler that will be called when any updates occur to objects of type rootObject. - * @param rootObject - * @param handler - */ - public void setUpdateHandler(IObjectUpdate handler); - public IObjectUpdate getUpdateHandler(Class rootObject); - public void removeUpdateHandler(Class rootObject); - public IObjectUpdate[] getUpdateHandlers(); - /** - * client application calls this to force the - * Vorba client to check for updates immediately. - * - */ - public void pollUpdate(); - - /** - * Client application calls this after any pre-session initialization - * (registering of Handlers, etc) - * Exceptions are raised for any failures. Any stateful calls to the session prior to - * this will result in an implicit call to joinSession - if that results in an exception - * then the VamsasClient should raise an Error. - * LATER: create VAMSAS exception hierarchy (in a language agnostic manner) - */ - public void joinSession() throws Exception; + public String getSessionUrn(); + + /** + * Returns a valid URN for other applications to connect to the vamsas + * session. + * + * @return session handle for this session. + */ + public SessionHandle getSessionHandle(); + + /** + * Included for applications with several ClientHandle identities. + * + * @return ClientHandle used to interact with other Vamsas applications. + */ + public ClientHandle getClientHandle(); + + /** + * + * @return UserHandle used when interacting with other Vamsas applications. + */ + public UserHandle getUserHandle(); + + /** + * Method called by client application on exit. Vorba will inform other + * clients if they exist. If this is the last application in the session then + * the session will be closed. Note: The application should be ready to handle + * 'RequestToCloseDocument' events from the Vorba agent in the latter case and + * so prompt the user to save the session locally. LATER: pick a better name ? + */ + public void finalizeClient(); + + /** + * register handler for updates for the current session + */ + public void addDocumentUpdateHandler(PropertyChangeListener evt); + + /** + * get vamsas document with user and app specific data IClientDocuments are + * not thread-safe. TODO: New exception for failed document lock. + * + * @throws IOException + * if lock is not obtainable for the document in the session + */ + public IClientDocument getClientDocument() throws IOException; + + /** + * Queue new Vorba objects for storage and propagation to other clients (via + * Event.DOCUMENT_UPDATE based notification of document change) New objects + * without provenance information will be given a default entry using the + * IClient's application, user (and session) handles Validity of + * IClientDocument object instances after this call is implementation + * dependent TODO: consider refactoring to remove the redundant + * IClientDocument parameter for this method + */ + public void updateDocument(IClientDocument newdoc); + + /** + * Any application may call storeDocument to save a local copy of the current + * vamsas document including all application specific entries. + * + * @param location + * to write zip file + */ + public void storeDocument(java.io.File location); + + /** + * Any application may call importDocument to merge a stored vamsasDocument + * into the current session. Note: use a IClientFactory's implementation to + * make sessions out of vamsas documents TODO: this is not currently + * implemented by SimpleClient - and may be dropped from the first version of + * the interface. LATER: VAMSAS: The IClient implementation will handle all ID + * 'relocations' + * + * @param location + */ + public void importDocument(java.io.File location); + + /** + * Add a listener to a particular event chain. See uk.ac.vamsas.client.Events + * for allowed values for EventChain. The EventChain value is passed as the + * propertyName in the java.bean.PropertyChangeEvent LATER: extend class to + * form own vamsas Event/Listener model. + * + * @param EventChain + * Name of event. Blank/null registers handler for all events. + * @param evt + * - event handler function. + */ + public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt); + + /** + * Sets the update handler that will be called when any updates occur to + * objects of type rootObject. + * + * @param rootObject + * @param handler + */ + public void setUpdateHandler(IObjectUpdate handler); + + public IObjectUpdate getUpdateHandler(Class rootObject); + + public void removeUpdateHandler(Class rootObject); + + public IObjectUpdate[] getUpdateHandlers(); + + /** + * client application calls this to force the Vorba client to check for + * updates immediately. + * + */ + public void pollUpdate(); + + /** + * Client application calls this after any pre-session initialization + * (registering of Handlers, etc) Exceptions are raised for any failures. Any + * stateful calls to the session prior to this will result in an implicit call + * to joinSession - if that results in an exception then the VamsasClient + * should raise an Error. LATER: create VAMSAS exception hierarchy (in a + * language agnostic manner) + */ + public void joinSession() throws Exception; + + /** + * get the Vamsas Pick Manager for registering pick handlers and sending + * messages for the current session. + * + * @return an object implementing IPickManager (which maybe the same as the + * IClient implementer) + */ + public uk.ac.vamsas.client.picking.IPickManager getPickManager(); + }