com.parabon.client
Class SessionManager

java.lang.Object
  extended by com.parabon.client.SessionManager
Direct Known Subclasses:
LocalSessionManager, RemoteSessionManager

public abstract class SessionManager
extends java.lang.Object

A SessionManager is responsible for maintaining a Frontier session, and is the primary entry point for launching, monitoring, and controlling jobs and tasks. Multiple SessionManager instances will result in multiple, independent sets of local or remote interactions. SessionManager itself is abstract and cannot be instantiated directly; concrete implementations include RemoteSessionManager, which operates the library in remote mode, LocalSessionManager, which operates the library in local mode, and SimulatorSessionManager, which operates the library in simulator mode.

See Also:
RemoteSessionManager, LocalSessionManager, SimulatorSessionManager

Field Summary
static java.lang.String DEFAULT_SESSION_MANAGER
           
protected  boolean destroyed
           
protected  com.parabon.util.UniqueIDGenerator idGenerator
           
protected  java.util.Set<Job> jobs
           
static java.lang.String LOCAL_SESSION_MANAGER
           
protected  org.apache.log4j.Logger log
           
protected  com.parabon.util.ObjectPool pool
           
static java.lang.String REMOTE_SESSION_MANAGER
           
static java.lang.String SESSION_MODE_PROPERTY
           
static java.lang.String SIMULATOR_SESSION_MANAGER
           
protected  java.util.List<TaskEventListener> tempListenerList
           
 
Constructor Summary
protected SessionManager()
           
 
Method Summary
 java.net.URI addElement(com.parabon.io.DataWrapper contents)
          Create a client-level element which can be referred to in tasks for this client.
 java.net.URI addElement(java.io.File contents)
          Create a client-level element which can be referred to in tasks for this client.
 java.net.URI addElement(java.lang.String identifier, com.parabon.io.DataWrapper contents)
          Create a client-level element which can be referred to in tasks for this client.
 java.net.URI addElement(java.lang.String identifier, java.io.File contents)
          Create a client-level element which can be referred to in tasks for this client.
protected  void addJob(Job job)
           
abstract  Job createJob(java.util.Map<java.lang.String,java.lang.String> attributes)
          Create and add a new Job with the given attributes.
 void destroy()
          Close this session, and release any resources associated with it.
 void destroy(int blockMillis)
          Close this session, and release any resources associated with it.
 void destroy(com.parabon.util.Listener completionListener)
          Close this session, and release any resources associated with it.
abstract  void flush(int blockMillis)
          Block until all actions taken thus far in the current session have been recieved and acknowledged by the server.
protected abstract  java.net.URI getBaseClientURI()
           
 java.net.URI getClientDataURI()
           
abstract  java.net.URI getGlobalDataURI()
           
static SessionManager getInstance()
          Create a SessionManager instance.
static SessionManager getInstance(java.lang.String mode)
          Create a SessionManager instance.
 java.net.URI getJobDataURI(java.lang.String jobID)
           
 java.util.Set<Job> getJobs()
          Return a Set containing the jobs currently defined for this session.
protected  org.apache.log4j.Logger getLog()
           
 java.net.URI getTaskDataURI(java.lang.String jobID, java.lang.String taskID)
           
protected  void notifyTaskEventListeners(TaskEvent event, java.util.List<TaskEventListener> listeners)
          Notify listeners of task events
 void reestablish()
          Attempt to retrieve the latest list of jobs from the Frontier server, blocking until complete.
abstract  void reestablish(int blockMillis)
          Attempt to retrieve the latest list of jobs from the Frontier server, blocking until complete or until approximately the given number milliseconds have elapsed.
abstract  void reestablish(com.parabon.util.Listener completionListener)
          Attempt to retrieve the latest list of jobs from the Frontier server, returning immediately without waiting for the operation to complete.
protected  void removeJob(Job job)
           
protected  void setLog(org.apache.log4j.Logger log_)
           
protected abstract  void submitElement(java.net.URI uri, com.parabon.io.DataWrapper contents)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOCAL_SESSION_MANAGER

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

REMOTE_SESSION_MANAGER

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

SIMULATOR_SESSION_MANAGER

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

DEFAULT_SESSION_MANAGER

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

SESSION_MODE_PROPERTY

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

pool

protected com.parabon.util.ObjectPool pool

jobs

protected java.util.Set<Job> jobs

idGenerator

protected com.parabon.util.UniqueIDGenerator idGenerator

destroyed

protected boolean destroyed

tempListenerList

protected java.util.List<TaskEventListener> tempListenerList

log

protected org.apache.log4j.Logger log
Constructor Detail

SessionManager

protected SessionManager()
Method Detail

getInstance

public static SessionManager getInstance()
                                  throws ServerCommunicationException,
                                         com.parabon.io.InvalidLoginException
Create a SessionManager instance. The type of instance created depends on the value of the "mode" system property.

Throws:
com.parabon.io.InvalidLoginException
ServerCommunicationException

getInstance

public static SessionManager getInstance(java.lang.String mode)
                                  throws ServerCommunicationException,
                                         com.parabon.io.InvalidLoginException
Create a SessionManager instance. The type of instance created depends on the value of the mode argument.

If creating a RemoteSessionManager, the server URL is set to the value given by the "com.parabon.frontier.server.url" system property, and the timeout is given by the "serverTimeout" property.

Parameters:
mode - a string value equal to one of SessionManager.LOCAL_SESSION_MANAGER, SessionManager.REMOTE_SESSION_MANAGER, or SessionManager.SIMULATOR_SESSION_MANAGER
Throws:
ServerCommunicationException
com.parabon.io.InvalidLoginException

flush

public abstract void flush(int blockMillis)
Block until all actions taken thus far in the current session have been recieved and acknowledged by the server. Blocks at most approximately the specified number of milliseconds; if blockMillis==-1, no timeout is used, and blocks until the flush condition is satisfied.


destroy

public void destroy()
Close this session, and release any resources associated with it. Any further operations on this session manager or any jobs or tasks created through it will result in undefined behaviour.

Does not neccessarily block until destruction is actually complete: worker threads may continue to run in the background until all pending interactions are complete.

This routine should be used with caution, especially if this is a remote session and an application uses System.exit(), as this can result in messages not being correctly and completely transferred to the Frontier server, and hence operations initiated with this SessionManager (such as job or task creation or removal) may not occur. To avoid this scenario, use destroy(-1) or call flush(-1) before calling destroy().

destroy() is equivalent to destroy(0).

See Also:
destroy(int), flush(int)

destroy

public void destroy(int blockMillis)
Close this session, and release any resources associated with it. Any further operations on this session manager or any jobs or tasks created through it will result in undefined behaviour.

Blocks at most approximately blockMillis milliseconds (or indefinitely if blockMillis == -1) for destruction to complete successfully; otherwise continues destruction but returns from the method call if possible while destruction continues.

Note that this version of destroy() should not be called from within a listener, as this could create a deadlock situation.

If a relatively short timeout is given, and this routine exits before interactions are complete, threads may continue attempting to complete various interactions in the background. If the application subsequently exits the JVM (e.g. via System.exit()), these interactions may not complete successfully -- for example, messages may not be correctly and complete transferred to the Frontier server, and hence operations initiated with this SessionManager (such as job or task creation or removal) may not occur.


destroy

public void destroy(com.parabon.util.Listener completionListener)
Close this session, and release any resources associated with it. Any further operations on this session manager or any jobs or tasks created through it will result in undefined behaviour.

Does not neccessarily block until destruction is actually complete: worker threads may continue to run in the background until all pending interactions are complete. Once all such interactions are complete, calls completionListener.alert(null); this may occur before destroy() returns (on either the current thread or another), or may occur after (on another thread).


setLog

protected void setLog(org.apache.log4j.Logger log_)

getLog

protected org.apache.log4j.Logger getLog()

getJobs

public java.util.Set<Job> getJobs()
Return a Set containing the jobs currently defined for this session. Note that this set will be complete only if reestablish() has been invoked and completed successfully previously during this session, and moreover the set will only be up-to-date if reestablish() was called relatively recently, as concurrent sessions may add or remove jobs.

This Set is read-only; any attempt to modify it will result in undefined behaviour.

See Also:
reestablish()

addJob

protected void addJob(Job job)

createJob

public abstract Job createJob(java.util.Map<java.lang.String,java.lang.String> attributes)
Create and add a new Job with the given attributes. The given attributes may be modified after createJob returns without affecting the newly-created job.


removeJob

protected void removeJob(Job job)

getGlobalDataURI

public abstract java.net.URI getGlobalDataURI()
                                       throws java.net.URISyntaxException
Throws:
java.net.URISyntaxException

getBaseClientURI

protected abstract java.net.URI getBaseClientURI()
                                          throws java.net.URISyntaxException
Throws:
java.net.URISyntaxException

getClientDataURI

public java.net.URI getClientDataURI()

getJobDataURI

public java.net.URI getJobDataURI(java.lang.String jobID)

getTaskDataURI

public java.net.URI getTaskDataURI(java.lang.String jobID,
                                   java.lang.String taskID)

addElement

public java.net.URI addElement(com.parabon.io.DataWrapper contents)
Create a client-level element which can be referred to in tasks for this client.

Method may or may not block until data is sent.

Parameters:
contents - the data to be associated with the new element
Returns:
the global unique identifier which may be used to refer to this element by tasks created by this client. If the returned URI is used by other clients, behavior is undefined.

addElement

public java.net.URI addElement(java.lang.String identifier,
                               com.parabon.io.DataWrapper contents)
Create a client-level element which can be referred to in tasks for this client.

Method may or may not block until data is sent.

Parameters:
identifier - the globally unique identifier to be associated with the new element, formed using the provided string. Should be unique for this client; if a data element with this identifier already exists on the server, behavior will be undefined.
contents - the data to be associated with the new element
Returns:
the global unique identifier which may be used to refer to this element by tasks created by this client. If the returned URI is used by other clients, behavior is undefined.

addElement

public java.net.URI addElement(java.io.File contents)
                        throws java.io.FileNotFoundException,
                               java.io.IOException
Create a client-level element which can be referred to in tasks for this client.

Method may or may not block until data is sent.

Parameters:
contents - a file containing the contents to be associated with the new element, which is guaranteed to not be modified or removed during the lifetime of the associated RemoteSessionManager (that is, until destroy() has successfully completed)
Returns:
the global unique identifier which may be used to refer to this element by tasks created by this client. If the returned URI is used by other clients, behavior is undefined.
Throws:
java.io.FileNotFoundException
java.io.IOException

addElement

public java.net.URI addElement(java.lang.String identifier,
                               java.io.File contents)
                        throws java.io.FileNotFoundException,
                               java.io.IOException
Create a client-level element which can be referred to in tasks for this client.

Method may or may not block until data is sent.

Parameters:
identifier - the globally unique identifier to be associated with the new element, formed using the provided string. Should be unique within this job; if a data element with this identifier already exists on the server, behavior will be undefined.
contents - a file containing the contents to be associated with the new element, which is guaranteed to not be modified or removed during the lifetime of the associated RemoteSessionManager (that is, until destroy() has successfully completed)
Returns:
the global unique identifier which may be used to refer to this element by tasks created by this client. If the returned URI is used by other clients, behavior is undefined.
Throws:
java.io.FileNotFoundException
java.io.IOException

submitElement

protected abstract void submitElement(java.net.URI uri,
                                      com.parabon.io.DataWrapper contents)

reestablish

public void reestablish()
Attempt to retrieve the latest list of jobs from the Frontier server, blocking until complete.

Note that this method should never be called from within an event listener or any other method which must complete in order for further events to be processed, as this would lead to a possible deadlock.

Equivalent to reestablish(-1).


reestablish

public abstract void reestablish(int blockMillis)
                          throws TimeoutException
Attempt to retrieve the latest list of jobs from the Frontier server, blocking until complete or until approximately the given number milliseconds have elapsed. If results are not obtained within the specitied timeout, a TimeoutException will be thrown, but the reestablish attempt might still result in the list of jobs being updated in the future.

If blockMillis==-1, the SessionManager will block indefinitely. Note that this method should never be called (except with a timeout of 0) from within an event listener or any other method which must complete in order for further events to be processed, as this would lead to a possible deadlock.

Throws:
TimeoutException

reestablish

public abstract void reestablish(com.parabon.util.Listener completionListener)
Attempt to retrieve the latest list of jobs from the Frontier server, returning immediately without waiting for the operation to complete. completionListener.alert(nul) will be called when reestablishment is complete.


notifyTaskEventListeners

protected void notifyTaskEventListeners(TaskEvent event,
                                        java.util.List<TaskEventListener> listeners)
Notify listeners of task events

Parameters:
event - event to broadcast
listeners - listeners to notify