2 * org.vamsas.client.IClient
5 package org.vamsas.client;
7 import java.beans.PropertyChangeListener;
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!)
17 public interface IClient {
20 * Self-documenting/describing info for the application to present
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
26 public String getAbout();
29 * TODO: Is this not be the same as the SessionUrn ?
30 * @return current SessionUrn
32 public String getSessionUrn();
34 * Returns a valid URN for other applications to connect to
36 * @return session handle for this session.
38 public SessionHandle getSessionHandle();
40 * Included for applications with several ClientHandle
42 * @return ClientHandle used to interact with
43 * other Vamsas applications.
45 public ClientHandle getClientHandle();
48 * @return UserHandle used when interacting
49 * with other Vamsas applications.
51 public UserHandle getUserHandle();
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 ?
63 public void finalizeClient();
65 * register handler for updates for the current session
67 public void addDocumentUpdateHandler(PropertyChangeListener evt);
69 * get vamsas document with
70 * user and app specific data
72 public IClientDocument getClientDocument();
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
81 public void updateDocument(IClientDocument newdoc);
83 * Any application may call storeDocument to
84 * save a local copy of the current vamsas document
85 * including all application specific entries.
87 * @param location to write zip file
89 public void storeDocument(java.io.File location);
91 * Add a listener to a particular event chain.
92 * See org.vamsas.client.Events for allowed
93 * values for EventChain.
94 * The EventChain value is passed as the
95 * propertyName in the java.bean.PropertyChangeEvent
96 * TODO: extend class to form own vamsas Event/Listener model.
97 * @param EventChain Name of event. Blank/null registers handler for all events.
98 * @param evt - event handler function.
100 public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt);
102 * client application calls this to force the
103 * Vorba client to check for updates immediately.
106 public void pollUpdate();
109 * Client application calls this after any pre-session initialization
110 * (registering of Handlers, etc)
111 * Exceptions are raised for any failures. Any stateful calls to the session prior to
112 * this will result in an implicit call to joinSession - if that results in an exception
113 * then the VamsasClient should raise an Error.
114 * TODO: create VAMSAS exception hierarchy (in a language agnostic manner)
116 public void joinSession() throws Exception;