uk.ac.vamsas.client
Interface IClient

All Known Implementing Classes:
SimpleClient

public interface IClient

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)


Method Summary
 void addDocumentUpdateHandler(java.beans.PropertyChangeListener evt)
          register handler for updates for the current session
 void addVorbaEventHandler(java.lang.String EventChain, java.beans.PropertyChangeListener evt)
          Add a listener to a particular event chain.
 void finalizeClient()
          Method called by client application on exit.
 java.lang.String getAbout()
          Self-documenting/describing info for the application to present to the user.
 IClientDocument getClientDocument()
          get vamsas document with user and app specific data IClientDocuments are not thread-safe.
 ClientHandle getClientHandle()
          Included for applications with several ClientHandle identities.
 IPickManager getPickManager()
          get the Vamsas Pick Manager for registering pick handlers and sending messages for the current session.
 SessionHandle getSessionHandle()
          Returns a valid URN for other applications to connect to the vamsas session.
 java.lang.String getSessionUrn()
          convenience method to get the SessionUrn as a string (for passing directly to a text box...).
 IObjectUpdate getUpdateHandler(java.lang.Class rootObject)
           
 IObjectUpdate[] getUpdateHandlers()
           
 UserHandle getUserHandle()
           
 void importDocument(java.io.File location)
          Any application may call importDocument to merge a stored vamsasDocument into the current session.
 void joinSession()
          Client application calls this after any pre-session initialization (registering of Handlers, etc) Exceptions are raised for any failures.
 void pollUpdate()
          client application calls this to force the Vorba client to check for updates immediately.
 void removeUpdateHandler(java.lang.Class rootObject)
           
 void setUpdateHandler(IObjectUpdate handler)
          Sets the update handler that will be called when any updates occur to objects of type rootObject.
 void storeDocument(java.io.File location)
          Any application may call storeDocument to save a local copy of the current vamsas document including all application specific entries.
 void updateDocument(IClientDocument newdoc)
          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
 

Method Detail

getAbout

public java.lang.String getAbout()
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.

Returns:
string like VamsasClient v.1.1.1 (GPL) and whatever

getSessionUrn

public java.lang.String getSessionUrn()
convenience method to get the SessionUrn as a string (for passing directly to a text box...).

Returns:
current SessionUrn

getSessionHandle

public SessionHandle getSessionHandle()
Returns a valid URN for other applications to connect to the vamsas session.

Returns:
session handle for this session.

getClientHandle

public ClientHandle getClientHandle()
Included for applications with several ClientHandle identities.

Returns:
ClientHandle used to interact with other Vamsas applications.

getUserHandle

public UserHandle getUserHandle()
Returns:
UserHandle used when interacting with other Vamsas applications.

finalizeClient

public void finalizeClient()
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 ?


addDocumentUpdateHandler

public void addDocumentUpdateHandler(java.beans.PropertyChangeListener evt)
register handler for updates for the current session


getClientDocument

public IClientDocument getClientDocument()
                                  throws java.io.IOException
get vamsas document with user and app specific data IClientDocuments are not thread-safe. TODO: New exception for failed document lock.

Throws:
java.io.IOException - if lock is not obtainable for the document in the session

updateDocument

public void updateDocument(IClientDocument newdoc)
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


storeDocument

public void storeDocument(java.io.File location)
Any application may call storeDocument to save a local copy of the current vamsas document including all application specific entries.

Parameters:
location - to write zip file

importDocument

public void importDocument(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'

Parameters:
location -

addVorbaEventHandler

public void addVorbaEventHandler(java.lang.String EventChain,
                                 java.beans.PropertyChangeListener evt)
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.

Parameters:
EventChain - Name of event. Blank/null registers handler for all events.
evt - - event handler function.

setUpdateHandler

public void setUpdateHandler(IObjectUpdate handler)
Sets the update handler that will be called when any updates occur to objects of type rootObject.

Parameters:
handler -

getUpdateHandler

public IObjectUpdate getUpdateHandler(java.lang.Class rootObject)

removeUpdateHandler

public void removeUpdateHandler(java.lang.Class rootObject)

getUpdateHandlers

public IObjectUpdate[] getUpdateHandlers()

pollUpdate

public void pollUpdate()
client application calls this to force the Vorba client to check for updates immediately.


joinSession

public void joinSession()
                 throws java.lang.Exception
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)

Throws:
java.lang.Exception

getPickManager

public IPickManager getPickManager()
get the Vamsas Pick Manager for registering pick handlers and sending messages for the current session.

Returns:
an object implementing IPickManager (which maybe the same as the IClient implementer)