package org.vamsas.client;
import java.beans.PropertyChangeListener;
+import java.io.IOException;
/**
* Defines the methods availabable to a vamsas
* created by an IClientFactory instance for a particular session,
* user, and application handle.
* (it's VORBA, not CORBA!)
- * TODO: add exceptions for timeouts raised when there are problems accessing session data (because another application is hogging it).
- * TODO: 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)
+ * 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.
- * TODO: formalise this for describing VAMSAS system, a particular
+ * LATER: formalise this for describing VAMSAS system, a particular
* Vorba client agent, and a particular session.
- * @returns string like VamsasClient v.1.1.1 (GPL) and whatever
+ * @return string like VamsasClient v.1.1.1 (GPL) and whatever
*/
public String getAbout();
/**
- * TODO: Is this not be the same as the SessionUrn ?
+ * convenience method to get the SessionUrn as a string (for passing directly to a text box...).
* @return current SessionUrn
*/
public String getSessionUrn();
* 'RequestToCloseDocument' events from the Vorba
* agent in the latter case and so prompt the user
* to save the session locally.
- * TODO: pick a better name ?
+ * LATER: pick a better name ?
*/
public void finalizeClient();
/**
* 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();
+ public IClientDocument getClientDocument() throws IOException;
/**
* Queue new Vorba objects for storage and propagation
* to other clients (via Event.DOCUMENT_UPDATE based
* 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);
/**
*/
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 org.vamsas.client.Events for allowed
* values for EventChain.
* The EventChain value is passed as the
* propertyName in the java.bean.PropertyChangeEvent
- * TODO: extend class to form own vamsas Event/Listener model.
+ * 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.
*
* 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.
- * TODO: create VAMSAS exception hierarchy (in a language agnostic manner)
+ * LATER: create VAMSAS exception hierarchy (in a language agnostic manner)
*/
public void joinSession() throws Exception;
}