uk.ac.vamsas.client.simpleclient
Class SimpleClient

java.lang.Object
  extended byuk.ac.vamsas.client.simpleclient.SimpleClient
All Implemented Interfaces:
IClient

public class SimpleClient
extends java.lang.Object
implements IClient

Author:
jimp

Field Summary
protected  VamsasSession _session
           
protected  ClientDocument cdocument
           
protected  ClientHandle client
           
protected  EventGeneratorThread evgen
           
protected  java.util.Hashtable extantobjects
          object hash table that persists in each client holding vorbaIds and hash values after a document write
protected  SessionUrn session
           
protected  UserHandle user
           
 
Constructor Summary
protected SimpleClient(UserHandle user, ClientHandle client, VamsasSession sess)
          construct SimpleClient for user, client and VamsasSession directory use the SimpleClientFactory rather than this constructor directly.
 
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.
protected  void createActiveClientFile()
           
 void finalizeClient()
          Method called by client application on exit.
protected  VamsasSession get_session()
          retrieves the current VamsasSession to which belong the client
 java.lang.String getAbout()
          construct new SimpleClientsession by importing objects from an existing vamsas document
 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.
protected  Lock getClientLock()
           
protected  java.io.File getClientlockFile()
           
 IPickManager getPickManager()
          get the Vamsas Pick Manager for registering pick handlers and sending messages for the current session.
protected  Entry getProvenanceEntry(java.lang.String action)
          construct a provenance entry for this client with the specified action string.
protected  java.lang.String getProvenanceUser()
           
 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...).
 SimpleClientConfig getSimpleClientConfig()
           
 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.
protected  void releaseActiveClientFile()
           
 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.
protected  void tidyAwaySessionDocumentState()
          garbage collect the ClientDocument instance and re-enable watchers.
 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
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

user

protected UserHandle user

session

protected SessionUrn session

_session

protected VamsasSession _session

client

protected ClientHandle client

evgen

protected EventGeneratorThread evgen

cdocument

protected ClientDocument cdocument

extantobjects

protected java.util.Hashtable extantobjects
object hash table that persists in each client holding vorbaIds and hash values after a document write

Constructor Detail

SimpleClient

protected SimpleClient(UserHandle user,
                       ClientHandle client,
                       VamsasSession sess)
                throws InvalidSessionUrnException
construct SimpleClient for user, client and VamsasSession directory use the SimpleClientFactory rather than this constructor directly.

Parameters:
user -
client -
sess -
Method Detail

getAbout

public java.lang.String getAbout()
construct new SimpleClientsession by importing objects from an existing vamsas document

Specified by:
getAbout in interface IClient
Returns:
string like VamsasClient v.1.1.1 (GPL) and whatever
Throws:
java.lang.Exception - IOExceptions for Session IO problems, and general Exception if importing document is invalid. protected SimpleClient(UserHandle user, ClientHandle client, VamsasSession sess, File importingArchive) throws Exception { this(user, client, sess); if (log.isDebugEnabled()) { log.debug("Attempting to overwrite session document with file: " +importingArchive); } // TODO: write provenance entry for new session indicating the import. }

getSessionUrn

public java.lang.String getSessionUrn()
Description copied from interface: IClient
convenience method to get the SessionUrn as a string (for passing directly to a text box...).

Specified by:
getSessionUrn in interface IClient
Returns:
current SessionUrn

getSessionHandle

public SessionHandle getSessionHandle()
Description copied from interface: IClient
Returns a valid URN for other applications to connect to the vamsas session.

Specified by:
getSessionHandle in interface IClient
Returns:
session handle for this session.

getClientHandle

public ClientHandle getClientHandle()
Description copied from interface: IClient
Included for applications with several ClientHandle identities.

Specified by:
getClientHandle in interface IClient
Returns:
ClientHandle used to interact with other Vamsas applications.

getUserHandle

public UserHandle getUserHandle()
Specified by:
getUserHandle in interface IClient
Returns:
UserHandle used when interacting with other Vamsas applications.

getProvenanceUser

protected java.lang.String getProvenanceUser()
Returns:
user field for a provenance entry

getProvenanceEntry

protected Entry getProvenanceEntry(java.lang.String action)
construct a provenance entry for this client with the specified action string.

Parameters:
action -
Returns:
properly completed provenance entry

addDocumentUpdateHandler

public void addDocumentUpdateHandler(java.beans.PropertyChangeListener evt)
Description copied from interface: IClient
register handler for updates for the current session

Specified by:
addDocumentUpdateHandler in interface IClient

finalizeClient

public void finalizeClient()
Description copied from interface: IClient
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 ?

Specified by:
finalizeClient in interface IClient

getClientDocument

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

Specified by:
getClientDocument in interface IClient
Throws:
java.io.IOException - if lock is not obtainable for the document in the session

updateDocument

public void updateDocument(IClientDocument newdoc)
Description copied from interface: IClient
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

Specified by:
updateDocument in interface IClient

tidyAwaySessionDocumentState

protected void tidyAwaySessionDocumentState()
garbage collect the ClientDocument instance and re-enable watchers.


storeDocument

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

Specified by:
storeDocument in interface IClient
Parameters:
location - to write zip file

addVorbaEventHandler

public void addVorbaEventHandler(java.lang.String EventChain,
                                 java.beans.PropertyChangeListener evt)
Description copied from interface: IClient
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.

Specified by:
addVorbaEventHandler in interface IClient
Parameters:
EventChain - Name of event. Blank/null registers handler for all events.
evt - - event handler function.

pollUpdate

public void pollUpdate()
Description copied from interface: IClient
client application calls this to force the Vorba client to check for updates immediately.

Specified by:
pollUpdate in interface IClient

joinSession

public void joinSession()
                 throws java.lang.Exception
Description copied from interface: IClient
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)

Specified by:
joinSession in interface IClient
Throws:
java.lang.Exception

importDocument

public void importDocument(java.io.File location)
Description copied from interface: IClient
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'

Specified by:
importDocument in interface IClient
Parameters:
location -

getUpdateHandler

public IObjectUpdate getUpdateHandler(java.lang.Class rootObject)
Specified by:
getUpdateHandler in interface IClient

getUpdateHandlers

public IObjectUpdate[] getUpdateHandlers()
Specified by:
getUpdateHandlers in interface IClient

removeUpdateHandler

public void removeUpdateHandler(java.lang.Class rootObject)
Specified by:
removeUpdateHandler in interface IClient

setUpdateHandler

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

Specified by:
setUpdateHandler in interface IClient
Parameters:
handler -

get_session

protected VamsasSession get_session()
retrieves the current VamsasSession to which belong the client

Returns:
the _session

getPickManager

public IPickManager getPickManager()
Description copied from interface: IClient
get the Vamsas Pick Manager for registering pick handlers and sending messages for the current session.

Specified by:
getPickManager in interface IClient
Returns:
an object implementing IPickManager (which maybe the same as the IClient implementer)

releaseActiveClientFile

protected void releaseActiveClientFile()
                                throws java.io.IOException
Throws:
java.io.IOException

createActiveClientFile

protected void createActiveClientFile()
                               throws java.io.IOException
Throws:
java.io.IOException

getClientlockFile

protected java.io.File getClientlockFile()
Returns:
the clientlockFile

getClientLock

protected Lock getClientLock()
Returns:
the lock for the client in the session

getSimpleClientConfig

public SimpleClientConfig getSimpleClientConfig()