com.parabon.client
Class Job

java.lang.Object
  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)