uk.ac.vamsas.client.simpleclient
Class VamsasSession

java.lang.Object
  extended byuk.ac.vamsas.client.simpleclient.VamsasSession

public class VamsasSession
extends java.lang.Object

Does all the IO operations for a SimpleClient instance accessing a SimpleClient vamsas session. Basically, it defines the various standard names for the files in the session directory (that maps to the sessionUrn), provides constructors for the file handlers and watchers of those file entities, and some higher level methods to check and change the state flags for the session. TODO: move the stuff below to the SimpleClientFactory documentation. much may not be valid now : Vamsas client is intialised with a path to create live session directories. This path may contain a vamsas.properties file that sets additional parameters (otherwise client just uses the one on the classpath). A vamsas session consists of : SessionDir - translates to urn of a live session. Contains: Vamsas Document (as a jar), Session client list file, both of which may be locked, and additional temporary versions of these files when write operations are taking place. Zip file entries - vamsasdocument.xml : core info one or more: - .version.sessionnumber.raw (string given in vamsasdocument.xml applicationData entry) Lockfile - filename given in the vamsasdocument.xml. Should be checked for validity by any client and rewritten if necessary. The lockfile can point to the jar itself. Mode of operation. Initially - documentHandler either: - creates a zip for a new session for the client - connect to an existing session zip 1. reads session urn file 2. waits for lock 3. examines session - decide whether to create new application data slice or connect to one stored in session. 4. writes info into session file 5. releases lock and generates local client events. 6. Creates Watcher thread to generate events. During the session - Update watcher checks for file change - Procedures for file based session message exchange - session document modification flag


Field Summary
static java.lang.String CLIENT_LIST
           
protected  java.lang.String clientFileDirectory
           
static java.lang.String CLOSEANDSAVE_FILE
          indicator file for informing other processes that they should finalise their vamsas datasets for storing into a vamsas archive.
static java.lang.String MODIFIEDDOC_FILE
          session file storing the last_stored_stat data
static java.lang.String SESSION_LOG
          log file location
protected  java.io.File sessionDir
          the sessionDir is given as the session location for new clients.
protected  org.apache.log4j.Logger slog
           
 ClientsFile storedocfile
           
static java.lang.String VAMSAS_OBJ
           
 int WATCH_SLEEP
          time between checking
 
Constructor Summary
protected VamsasSession(java.io.File sessionDir1)
          sets up the vamsas session files and watchers in sessionDir1
protected VamsasSession(java.io.File sessionDir1, java.io.File extVamDoc)
          sets up the vamsas session files and watchers in sessionDir1
 
Method Summary
protected  void addClient(SimpleClient client)
          add a IClient to the session add the client to the client list file
 void addStoreDocumentRequest(ClientHandle client, UserHandle user)
          write to the StoreWatcher file to indicate that a storeDocumentRequest has been made.
protected  void clearUnsavedFlag()
          called to clear update flag after a successful offline storage event
 FileWatcher getClientWatcher()
          make a new watcher object for the clientFile
 ClientSessionFileWatcherElement getClientWatcherElement()
          get or create a watcher on clist.
 FileWatcher getDocWatcher()
          make a new watcher object for the vamsas Document
protected  SimpleSessionManager getSessionManager()
           
 ClientsFile getStoreDocFile()
           
 FileWatcher getStoreWatcher()
          make a new watcher object for the messages file
protected  SessionFile getTempSessionFile(java.lang.String pref, java.lang.String suff)
          create a uniquely named uk.ac.vamsas.client.simpleclient.ClientsFile.addClient(ClientHandle)ile in the session Directory
protected  boolean getUnsavedFlag()
           
protected  VamsasArchive getVamsasDocument()
          Creates a VamsasArchive Vobject for accessing and updating document Note: this will lock the Vamsas Document for exclusive access to the client.
protected  void removeClient(SimpleClient client)
          removes a client from the current session removes the client from the session client list if the client is the last one from the session (ClientList), the current session is removed from active session list.
protected  void setSessionManager(SimpleSessionManager sessionManager)
           
protected  void setUnsavedFlag()
          called to indicate session document has been modified.
 void setVamsasDocument(java.io.File archive)
          create a new session with an existing vamsas Document - by copying it into the session.
protected  void unlockVamsasDocument()
          Unlocks the vamsas archive session document after it has been closed.
protected  void writeVamsasDocument(java.io.File destarchive, Lock extlock)
          write session as a new vamsas Document (this will overwrite any existing file without warning) TODO: test TODO: verify that lock should be released for vamsas document.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLOSEANDSAVE_FILE

public static final java.lang.String CLOSEANDSAVE_FILE
indicator file for informing other processes that they should finalise their vamsas datasets for storing into a vamsas archive.

See Also:
Constant Field Values

MODIFIEDDOC_FILE

public static final java.lang.String MODIFIEDDOC_FILE
session file storing the last_stored_stat data

See Also:
Constant Field Values

WATCH_SLEEP

public int WATCH_SLEEP
time between checking


clientFileDirectory

protected java.lang.String clientFileDirectory

SESSION_LOG

public static final java.lang.String SESSION_LOG
log file location

See Also:
Constant Field Values

slog

protected org.apache.log4j.Logger slog

sessionDir

protected java.io.File sessionDir
the sessionDir is given as the session location for new clients.


CLIENT_LIST

public static final java.lang.String CLIENT_LIST
See Also:
Constant Field Values

VAMSAS_OBJ

public static final java.lang.String VAMSAS_OBJ
See Also:
Constant Field Values

storedocfile

public ClientsFile storedocfile
Constructor Detail

VamsasSession

protected VamsasSession(java.io.File sessionDir1)
                 throws java.io.IOException
sets up the vamsas session files and watchers in sessionDir1

Parameters:
sessionDir1 -

VamsasSession

protected VamsasSession(java.io.File sessionDir1,
                        java.io.File extVamDoc)
                 throws java.io.IOException
sets up the vamsas session files and watchers in sessionDir1

Parameters:
sessionDir1 -
extVamDoc - null or an existing archive to initialise the session with
Throws:
any - IOExceptions from creating session directory and files.
error - if both extVamDoc and sessionDir1 already exist (cannot import new data into session in this way)
java.io.IOException
Method Detail

clearUnsavedFlag

protected void clearUnsavedFlag()
called to clear update flag after a successful offline storage event


setUnsavedFlag

protected void setUnsavedFlag()
called to indicate session document has been modified.


getUnsavedFlag

protected boolean getUnsavedFlag()
Returns:
true if session document has been modified since last offline storage event

getClientWatcher

public FileWatcher getClientWatcher()
make a new watcher object for the clientFile

Returns:
new ClientFile watcher instance

getDocWatcher

public FileWatcher getDocWatcher()
make a new watcher object for the vamsas Document

Returns:
new ClientFile watcher instance

getStoreWatcher

public FileWatcher getStoreWatcher()
make a new watcher object for the messages file

Returns:
new watcher instance

addStoreDocumentRequest

public void addStoreDocumentRequest(ClientHandle client,
                                    UserHandle user)
                             throws java.io.IOException
write to the StoreWatcher file to indicate that a storeDocumentRequest has been made. The local client's storeWatcher FileWatcher object is updated so the initial change is not registered.

Parameters:
client -
user -
Returns:
Throws:
java.io.IOException

setVamsasDocument

public void setVamsasDocument(java.io.File archive)
                       throws java.io.IOException
create a new session with an existing vamsas Document - by copying it into the session.

Parameters:
archive -
Throws:
java.io.IOException

writeVamsasDocument

protected void writeVamsasDocument(java.io.File destarchive,
                                   Lock extlock)
                            throws java.io.IOException
write session as a new vamsas Document (this will overwrite any existing file without warning) TODO: test TODO: verify that lock should be released for vamsas document.

Parameters:
destarchive -
Throws:
java.io.IOException

getVamsasDocument

protected VamsasArchive getVamsasDocument()
                                   throws java.io.IOException
Creates a VamsasArchive Vobject for accessing and updating document Note: this will lock the Vamsas Document for exclusive access to the client.

Returns:
session vamsas document
Throws:
java.io.IOException - if locks fail or vamsas document read fails.

unlockVamsasDocument

protected void unlockVamsasDocument()
                             throws java.io.IOException
Unlocks the vamsas archive session document after it has been closed.

Throws:
java.io.IOException

getTempSessionFile

protected SessionFile getTempSessionFile(java.lang.String pref,
                                         java.lang.String suff)
                                  throws java.io.IOException
create a uniquely named uk.ac.vamsas.client.simpleclient.ClientsFile.addClient(ClientHandle)ile in the session Directory

Parameters:
pref - Prefix for name
suff - Suffix for name
Returns:
SessionFile object configured for the new file (of length zero)
Throws:
java.io.IOException
See Also:
java.io.File.createTempFile

addClient

protected void addClient(SimpleClient client)
add a IClient to the session add the client to the client list file

Parameters:
client - client to add to the session

removeClient

protected void removeClient(SimpleClient client)
removes a client from the current session removes the client from the session client list if the client is the last one from the session (ClientList), the current session is removed from active session list. The active should add them self to the client list. To insure to close the session,when the current client is the lact active client, clears the list of clients and when two cycles to insure there is no more active client, that otherwise would have readd themself to the list

Parameters:
client - client to remove

getSessionManager

protected SimpleSessionManager getSessionManager()
Returns:
the sessionManager

setSessionManager

protected void setSessionManager(SimpleSessionManager sessionManager)
Parameters:
sessionManager - the sessionManager to set

getStoreDocFile

public ClientsFile getStoreDocFile()

getClientWatcherElement

public ClientSessionFileWatcherElement getClientWatcherElement()
get or create a watcher on clist.

Returns:
the contents of clistWatchElement or initialise it