com.parabon.client
Class Job

java.lang.Object
  extended by com.parabon.client.Job
Direct Known Subclasses:
RemoteJob

public abstract class Job
extends java.lang.Object

An instance of the Job class represents an active job and allows it to be queried and controlled, provides an interface for tasks and job-level elements to be created, and provides access to task proxy objects. An instance of Job cannot be created directly. Instead, Job instances are obtained through a SessionManager, for example via SessionManager.createJob().

has been destroyed, either via invoking destroy() directly or when the SessionManager has been destroyed.

The values of all arguments can be modified after the method call returns without affecting the behaviour of the job (in that sense, they are considered pass-by-value); however, modifying an argument in another thread during execution of a method will result in undefined behaviour.


Nested Class Summary
static class Job.JobConstraints
           
protected  class Job.TaskProxyIterator
           
protected  class Job.TaskProxySet
           
protected  class Job.WeakTaskReference
           
 
Constructor Summary
protected Job(SessionManager manager_, java.lang.String jobID_, java.util.Map<java.lang.String,java.lang.String> attributes_, com.parabon.util.ObjectPool pool_)
           
 
Method Summary
 java.net.URI addElement(com.parabon.io.DataWrapper contents)
          Create a job-level element which can be referred to in tasks contained in this job.
 java.net.URI addElement(java.io.File contents)
          Create a job-level element which can be referred to in tasks contained in this job.
 java.net.URI addElement(java.lang.String identifier, com.parabon.io.DataWrapper contents)
          Create a job-level element with the given identifier which can be referred to in tasks contained in this job.
 java.net.URI addElement(java.lang.String identifier, java.io.File contents)
          Create a job-level element with the given identifier which can be referred to in tasks contained in this job.
 java.net.URI addElementBundle(com.parabon.io.DataWrapper contents)
          Create a job-level element bundle containing elements which can be referred to in tasks contained in this job.
 java.net.URI addElementBundle(java.io.File contents)
          Create a job-level element bundle containing elements which can be referred to in tasks contained in this job.
 java.net.URI addElementBundle(java.lang.String identifier, com.parabon.io.DataWrapper contents)
          Create a job-level element bundle containing elements which can be referred to in tasks contained in this job.
 java.net.URI addElementBundle(java.lang.String identifier, java.io.File contents)
          Create a job-level element bundle containing elements which can be referred to in tasks contained in this job.
 void addListener(TaskEventListener listener)
          Add a listener to the job.
protected  void addTask(com.parabon.client.TaskMaster task)
           
 TaskProxy addTask(TaskSpec spec, java.util.Map<java.lang.String,java.lang.String> taskAttributes)
          Add a new task to the job with the given specification and attributes; it will not be started running until TaskProxy.start() is called, and may not be submitted to the server until this time.
protected static boolean attributesMatchTemplate(java.util.Map<java.lang.String,java.lang.String> attributes, java.util.Map<java.lang.String,java.lang.String> template)
           
 SerializableTaskSpec createSerializableTaskSpec()
           
 java.lang.String createTaskID()
          Returns a valid task ID unique within this Job
protected abstract  com.parabon.client.TaskMaster createTaskMaster(TaskSpec spec, java.util.Map<java.lang.String,java.lang.String> taskAttributes)
           
 TaskSpec createTaskSpec()
           
 void destroy()
          Remove all local references to this job and all tasks it contains; stop any locally running tasks within this job.
protected  void finalize()
           
 java.util.Set<TaskProxy> findRemoteTasksByAttribute(java.util.Map<java.lang.String,java.lang.String> template, int blockMillis)
          Search for tasks with attributes matching the given template.
 java.util.Set<TaskProxy> findTasksByAttribute(java.util.Map<java.lang.String,java.lang.String> template)
          Search for tasks with attributes matching the given template.
protected  boolean getAllowTaskRelease()
           
 java.util.Map<java.lang.String,java.lang.String> getAttributes()
          Get the job's attribute list.
protected  com.parabon.client.ElementContainer getElements()
           
protected  java.util.Set<java.net.URI> getElementURIs()
           
 Job.JobConstraints getJobConstraints()
          Retrieve the set of job scheduling constraints which specify the required characteristics of job.
 java.lang.String getJobID()
           
protected  java.util.List<TaskEventListener> getListeners()
           
protected  java.util.List<TaskEventListener> getListeners(boolean create)
           
protected  org.apache.log4j.Logger getLog()
           
protected  SessionManager getManager()
           
protected  com.parabon.util.ObjectPool getPool()
           
protected  com.parabon.client.TaskMaster getTask(java.lang.String taskID)
           
protected  com.parabon.client.TaskMaster getTaskMaster(java.lang.String taskIDString)
           
protected  java.util.Collection<java.lang.Object> getTaskMastersAndReferences()
           
protected  TaskProxy getTaskProxy(java.lang.String taskID)
           
 java.util.Set<TaskProxy> getTasks()
          Get a read-only Set of all non-released tasks.
protected  boolean hasTask(java.lang.String taskID)
           
protected  void notifyListenersChanged()
           
protected  void notifyTaskEventOccurred(TaskEvent event)
           
 void reestablish()
          Equivalent to reestablish(-1).
 void reestablish(int blockMillis)
          Request that the list of tasks contained in this job be reestablished if possible from a remote repository.
 void reestablish(com.parabon.util.Listener completionListener)
          Similar to reestablish(int), but does not block, instead calling the Listener.alert() method of the given listener when and if results are obtained.
 void reestablishPartial(java.util.Map<java.lang.String,java.lang.String> template, com.parabon.util.Listener completionListener)
          Similar to reestablish(Listener completionListener), but reestablishes at a minimum only those tasks matching the given template (as defined in findTasksByAttribute()).
protected  void releaseTask(java.lang.String taskID)
           
 void remove()
          Destroy this job and all tasks it contains, removing all references to it locally and remotely.
 void removeAllListeners()
          Remove all listeners from the job.
 void removeListener(TaskEventListener listener)
          Remove a listener from the job.
protected  com.parabon.io.DataWrapper resolveElement(java.net.URI uri)
           
 void setAllowTaskRelease(boolean value)
          Specify whether the Job allows tasks to be automatically released from the list of tasks that this job knows about.
protected  void setJobConstraints(Job.JobConstraints jobConstraints)
          Replace the current set of job scheduling constraints with those provided.
protected  void setManager(SessionManager sm)
           
 void stop()
          Stop this job and all tasks it contains, leaving all references to it locally and remotely intact.
protected abstract  void stopJob()
           
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Job

protected Job(SessionManager manager_,
              java.lang.String jobID_,
              java.util.Map<java.lang.String,java.lang.String> attributes_,
              com.parabon.util.ObjectPool pool_)
Method Detail

finalize

protected void finalize()
Overrides:
finalize in class java.lang.Object

getManager

protected SessionManager getManager()

setManager

protected void setManager(SessionManager sm)

getPool

protected com.parabon.util.ObjectPool getPool()

getJobID

public java.lang.String getJobID()

getListeners

protected java.util.List<TaskEventListener> getListeners()

getListeners

protected java.util.List<TaskEventListener> getListeners(boolean create)

getElements

protected com.parabon.client.ElementContainer getElements()

hasTask

protected boolean hasTask(java.lang.String taskID)

getTaskMastersAndReferences

protected java.util.Collection<java.lang.Object> getTaskMastersAndReferences()

addTask

protected final void addTask(com.parabon.client.TaskMaster task)

getLog

protected org.apache.log4j.Logger getLog()

getAttributes

public java.util.Map<java.lang.String,java.lang.String> getAttributes()
Get the job's attribute list. May return null iff the job has been released. Returned value is read-only; any attempts to change it will result in undefined behaviour.


setAllowTaskRelease

public void setAllowTaskRelease(boolean value)
Specify whether the Job allows tasks to be automatically released from the list of tasks that this job knows about. If set to false (the default), jobs will maintain a list of all tasks either created during this session or reestablished from the server explicitely or implicitely. If set to true, tasks may be 'forgotten about' if no task-level listeners are registered on those tasks, in which case they would not show up via calls to getTasks() or * findTasksByAttribute(). In the latter case, a given task is less likely to be released if the client application maintains a TaskProxy for that task.


getAllowTaskRelease

protected boolean getAllowTaskRelease()

setJobConstraints

protected void setJobConstraints(Job.JobConstraints jobConstraints)
Replace the current set of job scheduling constraints with those provided. Note that only the contents of the given JobConstraints instance will be copied; the provided JobConstraints instance may be freely modified after this method returns without affecting the contents of this TaskSpec.


getJobConstraints

public Job.JobConstraints getJobConstraints()
Retrieve the set of job scheduling constraints which specify the required characteristics of job. Modifying the returned JobConstraints will not have any effect on the job since the constraints can only be applied during job creation.


findTasksByAttribute

public java.util.Set<TaskProxy> findTasksByAttribute(java.util.Map<java.lang.String,java.lang.String> template)
Search for tasks with attributes matching the given template. A tasks's attributes are considered to match a template if, for each attribute present in the template, the task has an attribute with identical name and value.

Searches only non-released tasks.

Returns:
a read-only Set of TaskProxys corresponding to matching tasks

findRemoteTasksByAttribute

public java.util.Set<TaskProxy> findRemoteTasksByAttribute(java.util.Map<java.lang.String,java.lang.String> template,
                                                           int blockMillis)
                                                    throws TimeoutException
Search for tasks with attributes matching the given template. A tasks's attributes are considered to match a template if, for each attribute present in the template, the task has an attribute with identical name and value.

Searches all tasks, whether released or not, employing a remote repository (the Frontier server) if applicable.

Returns:
a read-only Set of TaskProxys corresponding to the tasks matching the given template
Throws:
TimeoutException

getTasks

public java.util.Set<TaskProxy> getTasks()
Get a read-only Set of all non-released tasks.


destroy

public void destroy()
Remove all local references to this job and all tasks it contains; stop any locally running tasks within this job. Does not affect remote instances and records of this job. Referencing any records associated with this job or any of its tasks after calling destroy() will result in undefined behaviour.


remove

public void remove()
Destroy this job and all tasks it contains, removing all references to it locally and remotely. If any tasks contained in this job are actively executing, they will be stopped.


stop

public void stop()
Stop this job and all tasks it contains, leaving all references to it locally and remotely intact. If any tasks contained in this job are actively executing, they will be stopped, and any pending results will be


reestablish

public void reestablish()
Equivalent to reestablish(-1).

See Also:
reestablish(int)

reestablish

public void reestablish(int blockMillis)
                 throws TimeoutException
Request that the list of tasks contained in this job be reestablished if possible from a remote repository.

Blocks a maximum of approximately the specified number of milliseconds. If results are not obtained within the specitied timeout, a TimeoutException will be thrown. If blockMillis == -1, will block indefinitely.

Note that this method should never be called with a negative or large block timeout 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 void reestablish(com.parabon.util.Listener completionListener)
Similar to reestablish(int), but does not block, instead calling the Listener.alert() method of the given listener when and if results are obtained.

See Also:
reestablish(int)

reestablishPartial

public void reestablishPartial(java.util.Map<java.lang.String,java.lang.String> template,
                               com.parabon.util.Listener completionListener)
Similar to reestablish(Listener completionListener), but reestablishes at a minimum only those tasks matching the given template (as defined in findTasksByAttribute()).

See Also:
findTasksByAttribute(Map), reestablish(Listener)

getElementURIs

protected java.util.Set<java.net.URI> getElementURIs()

addElement

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

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 within this job. If the returned URI is used in tasks outside this job, behavior is undefined.

addElement

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

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 - 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 within this job. If the returned URI is used in tasks outside this job, behavior is undefined.

addElement

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

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 within this job. If the returned URI is used in tasks outside this job, 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 job-level element with the given identifier which can be referred to in tasks contained in this job.

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 within this job. If the returned URI is used in tasks outside this job, behavior is undefined.
Throws:
java.io.FileNotFoundException
java.io.IOException

addElementBundle

public java.net.URI addElementBundle(com.parabon.io.DataWrapper contents)
Create a job-level element bundle containing elements which can be referred to in tasks contained in this job.

Method may or may not block until data is sent.

Parameters:
contents - the data to be associated with the new elements. The data must be in Parabon Element Bundle format, including a valid bundle manifest.
Returns:
the global unique identifier which may be used to refer to the elements in the bundle from within this task. If the returned URI is used in other tasks, behavior is undefined.

addElementBundle

public java.net.URI addElementBundle(java.lang.String identifier,
                                     com.parabon.io.DataWrapper contents)
Create a job-level element bundle containing elements which can be referred to in tasks contained in this job.

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 - the data to be associated with the new elements. The data must be in Parabon Element Bundle format, including a valid bundle manifest.
Returns:
the global unique identifier which may be used to refer to the elements in the bundle from within this task. If the returned URI is used in other tasks, behavior is undefined.

addElementBundle

public java.net.URI addElementBundle(java.io.File contents)
                              throws java.io.FileNotFoundException,
                                     java.io.IOException
Create a job-level element bundle containing elements which can be referred to in tasks contained in this job.

Method may or may not block until data is sent.

Parameters:
contents - a file containing the contents to be associated with the new elements, which is guaranteed to not be modified or removed during the lifetime of the associated RemoteSessionManager (that is, until destroy() has successfully completed). The data must be in Parabon Element Bundle format, including a valid bundle manifest.
Returns:
the global unique identifier which may be used to refer to the elements in the bundle from within this task. If the returned URI is used in other tasks, behavior is undefined.
Throws:
java.io.FileNotFoundException
java.io.IOException

addElementBundle

public java.net.URI addElementBundle(java.lang.String identifier,
                                     java.io.File contents)
                              throws java.io.FileNotFoundException,
                                     java.io.IOException
Create a job-level element bundle containing elements which can be referred to in tasks contained in this job.

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 elements, which is guaranteed to not be modified or removed during the lifetime of the associated RemoteSessionManager (that is, until destroy() has successfully completed). The data must be in Parabon Element Bundle format, including a valid bundle manifest.
Returns:
the global unique identifier which may be used to refer to the elements in the bundle from within this task. If the returned URI is used in other tasks, behavior is undefined.
Throws:
java.io.FileNotFoundException
java.io.IOException

resolveElement

protected com.parabon.io.DataWrapper resolveElement(java.net.URI uri)
                                             throws NoSuchElementException
Throws:
NoSuchElementException

createTaskID

public java.lang.String createTaskID()
Returns a valid task ID unique within this Job


createTaskSpec

public TaskSpec createTaskSpec()

createSerializableTaskSpec

public SerializableTaskSpec createSerializableTaskSpec()

createTaskMaster

protected abstract com.parabon.client.TaskMaster createTaskMaster(TaskSpec spec,
                                                                  java.util.Map<java.lang.String,java.lang.String> taskAttributes)

stopJob

protected abstract void stopJob()

addTask

public TaskProxy addTask(TaskSpec spec,
                         java.util.Map<java.lang.String,java.lang.String> taskAttributes)
Add a new task to the job with the given specification and attributes; it will not be started running until TaskProxy.start() is called, and may not be submitted to the server until this time. Returns a TaskProxy which can be used to monitor and control the task.

The client application retains ownership of both the spec and taskAttributes, and may freely modify them after this routine returns without affecting the behaviour of the client library.

Throws:
java.lang.IllegalStateException - if the job has already been removed

releaseTask

protected void releaseTask(java.lang.String taskID)
                    throws NoSuchTaskException
Throws:
NoSuchTaskException

getTaskProxy

protected TaskProxy getTaskProxy(java.lang.String taskID)
                          throws NoSuchTaskException
Throws:
NoSuchTaskException

getTask

protected com.parabon.client.TaskMaster getTask(java.lang.String taskID)
                                         throws NoSuchTaskException
Throws:
NoSuchTaskException

notifyListenersChanged

protected void notifyListenersChanged()

addListener

public void addListener(TaskEventListener listener)
Add a listener to the job. The listener will be sent any events occurring for all tasks contained within this job for which the listener implements relevant interfaces. The order in which job-level listeners are called is not defined, but all task-level listeners will be invoked for a given event before any job-level listeners.

Listeners can re-enter any Frontier API entry point. It is highly recommended, however, that listeners perform only very brief, lightweight actions. In particular, listeners should never call methods that block waiting for task, job, or session state changes to occur.

If a single listener is added to the same job more than once, it may or may not receive any given events more than once.


removeListener

public void removeListener(TaskEventListener listener)
Remove a listener from the job.


removeAllListeners

public void removeAllListeners()
Remove all listeners from the job.


notifyTaskEventOccurred

protected void notifyTaskEventOccurred(TaskEvent event)

getTaskMaster

protected com.parabon.client.TaskMaster getTaskMaster(java.lang.String taskIDString)

attributesMatchTemplate

protected static boolean attributesMatchTemplate(java.util.Map<java.lang.String,java.lang.String> attributes,
                                                 java.util.Map<java.lang.String,java.lang.String> template)