new Selection message. This still needs work!
[vamsas.git] / 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 }