uws.job
Class AbstractJob

java.lang.Object
  uws.job.SerializableUWSObject
      uws.job.AbstractJob

All Implemented Interfaces:

java.io.Serializable

public abstract class AbstractJob
extends SerializableUWSObject

Brief description

Abstract implementation of a job of the UWS pattern. Only the methods which deal with the job execution are abstract. So if you want a job executes a task you must extend AbstractJob and override:

• jobWork(): the task which must be executed (note: it is your responsibility to write the result(s) at the end of the work).

Some attributes comments

• The job attributes startTime and endTime are automatically managed by AbstractJob. You don't have to do anything ! However you can customize the used date/time format thanks to the function setDateFormat(DateFormat). The default date/time format is: yyyy-MM-dd'T'HH:mm:ss.SSSZ


• Once set, the destruction and the executionDuration attributes are automatically managed. That is to say:
  • if the destruction time is reached: the job stops and it is destroyed by its job list
  • if the execution duration is elapsed: the job stops and the phase is put to ABORTED.


• The ownerID attribute is set at the job creation and can not be changed after ! If no owner ID is given at the job creation, its default value is ANONYMOUS_OWNER (=anonymous).


• If your job is executable, do not forget to set the quote parameter ONLY by using the setQuote(long) method (a negative value or QUOTE_NOT_KNOWN value indicates the quote is not known ; QUOTE_NOT_KNOWN is the default value).

More details

• generateJobId(): This function is called at the construction of any AbstractJob. It allows to generate a unique job ID. By default: time (in milliseconds) + a upper-case letter (A, B, C, ....). If you want customizing the job ID of your jobs, you need to override this function.


• loadAdditionalParams(): All parameters that are not managed by default are automatically stored in the job attribute additionalParameters (a map). However if you want manage yourself some or all of these additional parameters (i.e. task parameters), you must override this method. (By default nothing is done.)


• clearResources(): This method is called only at the destruction of the job. By default, the job is stopped (if running) and thread resources are freed. However, it is your responsibility to delete results files if you want their deletion at the job destruction. To do that, you must override this method, call the super method and finally do what you want (i.e. delete all results files).


• publishExecutionError(UWSException): This method is called when any UWSException is thrown from the jobWork() method. By default, the method UWSToolBox.publishErrorSummary(AbstractJob, String, ErrorType) is called. This function can be overrided.


• setPhaseManager(JobPhase): Lets customizing the default behaviors of all the execution phases for any job instance. For more details see JobPhase.


• addObserver(JobObserver): An instance of any kind of AbstractJob can be observed by objects which implements JobObserver (i.e. AbstractUWS). Observers are notified at any change of the execution phase.

Version:

02/2011

Author:

Grégory Mantelet (CDS)

See Also:

Serialized Form

Nested Class Summary

protected static class

AbstractJob.DurationTimerTask Task that the executionDuration timer of a job must trigger: only calls abort().

Field Summary

static java.lang.String	ACTION_DELETE Name of the DELETE action.
protected java.util.Map<java.lang.String,java.lang.String>	additionalParameters This is an enumeration of the other Job parameters (given in POST queries).
static java.lang.String	ANONYMOUS_OWNER Default value of owner if no ID are given at the job creation.
protected java.text.DateFormat	dateFormat The used date formatter.
static java.lang.String	DEFAULT_DATE_FORMAT Default date format pattern.
protected ErrorSummary	errorSummary This error summary gives a human-readable error message for the underlying job.
protected java.lang.String	jobId The identifier of the job (it MUST be different from any other job).
protected static java.lang.String	lastId The last generated job ID.
protected java.lang.String	owner The identifier of the creator of this job.
static java.lang.String	PARAM_ACTION Name of the parameter ACTION.
static java.lang.String	PARAM_DESTRUCTION_TIME Name of the parameter destructionTime.
static java.lang.String	PARAM_ERROR_SUMMARY Name of the parameter errorSummary.
static java.lang.String	PARAM_EXECUTION_DURATION Name of the parameter executionDuration.
static java.lang.String	PARAM_OWNER Name of the parameter owner.
static java.lang.String	PARAM_PARAMETERS Name of the parameter otherParameters.
static java.lang.String	PARAM_PHASE Name of the parameter phase.
static java.lang.String	PARAM_QUOTE Name of the parameter quote.
static java.lang.String	PARAM_RESULTS Name of the parameter results.
static java.lang.String	PARAM_RUN_ID Name of the parameter runId.
static java.lang.String	PHASE_ABORT Value of the parameter phase which aborts the job.
static java.lang.String	PHASE_RUN Value of the parameter phase which starts the job.
static long	QUOTE_NOT_KNOWN The quote value that indicates the quote of this job is not known.
protected java.util.List<Result>	results This is a list of all results of this job.
protected java.lang.String	runId The name/label that the job creator uses to identify this job.
protected JobThread	thread The thread to start for executing the job.
static long	UNLIMITED_DURATION The duration that implies an unlimited execution duration.
protected long	waitForStop The time to wait the end of the thread after an interruption.

Constructor Summary

	AbstractJob(java.util.Map<java.lang.String,java.lang.String> lstParam) Builds a job with a map of all its parameters (UWS and additional parameters).
protected	AbstractJob(java.lang.String ownerID, java.util.Map<java.lang.String,java.lang.String> lstParam) Builds a job with the ID of the owner of this job and a map of all its parameters (UWS and additional parameters).
protected	AbstractJob(java.lang.String jobName, java.lang.String ownerId, long maxDuration, java.util.Date destructTime, java.util.Map<java.lang.String,java.lang.String> lstParam) Builds a job with a job name/label, an owner ID, an execution duration, a destruction time and a map of all its parameters (UWS and additional parameters).
protected	AbstractJob(java.lang.String jobId, java.lang.String jobName, java.lang.String ownerId, ExecutionPhase phase, java.util.Date startTime, java.util.Date endTime, long maxDuration, java.util.Date destructTime, java.util.List<Result> results, ErrorSummary errors, java.util.Map<java.lang.String,java.lang.String> additionalParams) MANUAL CONSTRUCTOR - DISCOURAGED Constructs a Job with all its parameters.

Method Summary

void	abort() Stops immediately the job, sets its phase to ABORTED and sets its end time.
boolean	addObserver(JobObserver observer) Lets adding an observer of this job.
boolean	addOrUpdateParameter(java.lang.String paramName, java.lang.String paramValue) Adds or updates the specified parameter with the given value ONLY IF the job can be updated (considering its current execution phase, see JobPhase.isJobUpdatable()).
boolean	addOrUpdateParameters(java.util.Map<java.lang.String,java.lang.String> params) Adds or updates the given parameters ONLY IF the job can be updated (considering its current execution phase, see JobPhase.isJobUpdatable()).
boolean	addResult(Result res) Adds the given result in the results list of this job.
protected void	applyPhaseParam() Looks for an additional parameters which corresponds to the Execution Phase.
protected void	checkPhaseParam() Deprecated. applyPhaseParam().
void	clearResources() Stops the job if running, removes the job from the execution manager, stops the timer for the execution duration and may clear all files or any other resources associated to this job.
boolean	equals(java.lang.Object anotherJob) 2 instances of AbstractJob are equals ONLY IF their ID are equals.
void	error(ErrorSummary error) Stops immediately the job, sets its error summary, sets its phase to ExecutionPhase.ERROR and sets its end time.
void	error(UWSException ue) Publishes the given exception as an error summary.
protected void	finalize() Merely clears resources: it only calls clearResources().
protected java.lang.String	generateJobId() This function lets generating a unique ID.
java.util.Set<java.lang.String>	getAdditionalParameters() Gets the list of parameters' name.
java.lang.String	getAdditionalParameterValue(java.lang.String paramName) Gets the value of the specified additional parameter.
java.text.DateFormat	getDateFormat() Gets the used date-time formatter.
java.util.Date	getDestructionTime() Gets the instant when the job shall be destroyed.
java.util.Date	getEndTime() Gets the time at which the job execution has finished.
ErrorSummary	getErrorSummary() Gets the error that occurs during the execution of this job.
long	getExecutionDuration() Gets the duration (in seconds) for which this job shall run.
ExecutionManager	getExecutionManager() Gets the execution manager of this job, if any.
java.lang.String	getJobId() Gets the ID of this job (this ID MUST be unique).
JobList<? extends AbstractJob>	getJobList() Gets its jobs list, if known.
int	getNbAdditionalParameters() Gets the number of additional parameters.
int	getNbObservers() Gets the total number of observers this job has.
int	getNbOtherParameters() Deprecated. Replaced by getNbAdditionalParameters().
int	getNbResults() Gets the total number of results.
java.util.Iterator<JobObserver>	getObservers() Gets the observers of this job.
java.util.Set<java.lang.String>	getOtherParameters() Deprecated. Replaced by getAdditionalParameters()
java.lang.String	getOtherParameterValue(java.lang.String paramName) Deprecated. Replaced by getAdditionalParameterValue(String).
java.lang.String	getOwner() Gets the ID of the owner of this job.
ExecutionPhase	getPhase() Gets the phase in which this job is now.
JobPhase	getPhaseManager() Gets the phase manager of this job.
long	getQuote() Get the quote attribute of this job.
java.util.Iterator<Result>	getResults() Gets the results list of this job.
java.lang.String	getRunId() Gets the RunID of this job given by the UWS user (presumed to be the owner of this job).
java.util.Date	getStartTime() Gets the time at which the job execution has started.
long	getTimeToWaitForEnd() Gets the time to wait for the end of the thread after an interruption.
UWSException	getWorkError() Gets the error (if any) which has occurred during the job execution.
boolean	isFinished() Tells whether the job is already finished (completed, aborted, error, ...).
boolean	isRunning() Tells whether the job is still running.
protected boolean	isStopped() Tells whether the thread is different from null, is not alive, is interrupted or is finished (see JobThread.isFinished()).
protected abstract void	jobWork() Does the job work (i.e. making a long computation or executing a query on a Database).
protected boolean	loadAdditionalParams() Method called when updating one or several parameters using the functions addOrUpdateParameter(String, String) and addOrUpdateParameters(Map) or at the job creation.
protected java.util.Map<java.lang.String,java.lang.String>	loadDefaultParams(java.util.Map<java.lang.String,java.lang.String> lstParam) Loads the given parameters: all known parameters (with write access) are updated whereas others are returned in a new map in which all keys are in lower case.
void	notifyObservers(ExecutionPhase oldPhase) Notifies all the observer of this job that its phase has changed.
protected boolean	publishExecutionError(UWSException ue) Deprecated. Replaced by error(UWSException).
boolean	removeAdditionalParameter(java.lang.String paramName) Removes the specified additional parameter ONLY IF the job can be updated (considering its current execution phase, see JobPhase.isJobUpdatable()).
void	removeAllAdditionalParameter() Clears the whole list of additional parameters ONLY IF the job can be updated (considering its current execution phase, see JobPhase.isJobUpdatable()).
void	removeAllObservers() Lets removing all observers of this job.
void	removeAllOtherParameter() Deprecated. Replaced by removeAllAdditionalParameter().
boolean	removeObserver(JobObserver observer) Lets removing the given object from the list of observers of this job.
boolean	removeOtherParameter(java.lang.String paramName) Deprecated. Replaced by removeAdditionalParameter(String).
void	serialize(java.io.OutputStream output, java.lang.String[] attributes, UWSSerializer serializer) Serializes the specified attribute of this job in the given output stream by using the given serializer.
java.lang.String	serialize(java.lang.String[] attributes, UWSSerializer serializer) Serializes the specified attribute of this job by using the given serializer.
java.lang.String	serialize(UWSSerializer serializer, java.lang.String ownerId) Serializes the whole object considering the given owner ID (supposed to be the ID of the current user) and thanks to the given serializer.
void	setDateFormat(java.text.DateFormat newDateFormat) Sets the date-time formatter to use.
void	setDestructionTime(java.util.Date destructionTime) Sets the instant when the job shall be destroyed ONLY IF the job can updated (considering its current execution phase, see JobPhase.isJobUpdatable()).
protected void	setEndTime(java.util.Date newDateTime) Sets the time at which the job execution has finished.
void	setErrorSummary(ErrorSummary errorSummary) Sets the error that occurs during the execution of this job.
void	setExecutionDuration(long executionDuration) Sets the duration (in seconds) for which this job shall run ONLY IF the job can updated (considering its current execution phase, see JobPhase.isJobUpdatable()).
void	setExecutionManager(ExecutionManager newManager) Sets the execution manager of this job.
void	setJobList(JobList<? extends AbstractJob> jobList) Sets its jobs list.
void	setPhase(ExecutionPhase p) Sets the current phase of this job.
void	setPhase(ExecutionPhase p, boolean force) Sets the current phase of this job, respecting or not the imposed order.
void	setPhaseManager(JobPhase jobPhase) Sets the phase manager of this job.
void	setQuote(long nbSeconds) Sets the quote attribute of this job ONLY IF the job can updated (considering its current execution phase, see JobPhase.isJobUpdatable()).
void	setRunId(java.lang.String name) Sets the RunID of this job ONLY IF the job can updated (considering its current execution phase, see JobPhase.isJobUpdatable()).
protected void	setStartTime(java.util.Date newDateTime) Sets the time at which the job execution has started.
void	setTimeToWaitForEnd(long timeToWait) Sets the time to wait for the end of the thread after an interruption.
void	start() Starts the job by using the execution manager if any.
void	start(boolean useManager) Starts the job.
protected void	stop() Stops the thread that executes the work of this job.
boolean	sync() This method is called by its job list just after the de-serialization of the whole UWS (this job included).
java.lang.String	toString()

Methods inherited from class uws.job.SerializableUWSObject

serialize, serialize, serialize

Methods inherited from class java.lang.Object

clone, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PARAM_ACTION

public static final java.lang.String PARAM_ACTION

Name of the parameter ACTION.

See Also:

Constant Field Values

ACTION_DELETE

public static final java.lang.String ACTION_DELETE

Name of the DELETE action.

See Also:

Constant Field Values

PARAM_RUN_ID

public static final java.lang.String PARAM_RUN_ID

Name of the parameter runId.

See Also:

Constant Field Values

PARAM_OWNER

public static final java.lang.String PARAM_OWNER

Name of the parameter owner.

See Also:

Constant Field Values

PARAM_PHASE

public static final java.lang.String PARAM_PHASE

Name of the parameter phase.

See Also:

Constant Field Values

PHASE_RUN

public static final java.lang.String PHASE_RUN

Value of the parameter phase which starts the job.

See Also:

Constant Field Values

PHASE_ABORT

public static final java.lang.String PHASE_ABORT

Value of the parameter phase which aborts the job.

See Also:

Constant Field Values

PARAM_QUOTE

public static final java.lang.String PARAM_QUOTE

Name of the parameter quote.

See Also:

Constant Field Values

PARAM_EXECUTION_DURATION

public static final java.lang.String PARAM_EXECUTION_DURATION

Name of the parameter executionDuration.

See Also:

Constant Field Values

PARAM_DESTRUCTION_TIME

public static final java.lang.String PARAM_DESTRUCTION_TIME

Name of the parameter destructionTime.

See Also:

Constant Field Values

PARAM_ERROR_SUMMARY

public static final java.lang.String PARAM_ERROR_SUMMARY

Name of the parameter errorSummary.

See Also:

Constant Field Values

PARAM_PARAMETERS

public static final java.lang.String PARAM_PARAMETERS

Name of the parameter otherParameters.

See Also:

Constant Field Values

PARAM_RESULTS

public static final java.lang.String PARAM_RESULTS

Name of the parameter results.

See Also:

Constant Field Values

ANONYMOUS_OWNER

public static final java.lang.String ANONYMOUS_OWNER

Default value of owner if no ID are given at the job creation.

See Also:

Constant Field Values

DEFAULT_DATE_FORMAT

public static final java.lang.String DEFAULT_DATE_FORMAT

Default date format pattern.

See Also:

Constant Field Values

QUOTE_NOT_KNOWN

public static final long QUOTE_NOT_KNOWN

The quote value that indicates the quote of this job is not known.

See Also:

Constant Field Values

UNLIMITED_DURATION

public static final long UNLIMITED_DURATION

The duration that implies an unlimited execution duration.

See Also:

Constant Field Values

lastId

protected static java.lang.String lastId

The last generated job ID. It MUST be used ONLY by the function generateJobId() !

jobId

protected final java.lang.String jobId

The identifier of the job (it MUST be different from any other job).
Note: It is assigned automatically at the job creation in any job constructor by the function generateJobId(). To change the way this ID is generated or its format you must override this function.

owner

protected final java.lang.String owner

The identifier of the creator of this job.
Note: This object will not exist for all invocations of the UWS conformant protocol, but only in cases where the access to the service is authenticated.

runId

protected java.lang.String runId

The name/label that the job creator uses to identify this job.
Note: this is distinct from the Job Identifier that the UWS system itself assigns to each job (jobId). It may not be unique !

dateFormat

protected java.text.DateFormat dateFormat

The used date formatter.

errorSummary

protected ErrorSummary errorSummary

This error summary gives a human-readable error message for the underlying job.

Note: This object is intended to be a detailed error message, and consequently, might be a large piece of text such as a stack trace.

additionalParameters

protected java.util.Map<java.lang.String,java.lang.String> additionalParameters

This is an enumeration of the other Job parameters (given in POST queries).

results

protected java.util.List<Result> results

This is a list of all results of this job.

thread

protected transient JobThread thread

The thread to start for executing the job.

waitForStop

protected long waitForStop

The time to wait the end of the thread after an interruption.

Constructor Detail

AbstractJob

public AbstractJob(java.util.Map<java.lang.String,java.lang.String> lstParam)
            throws UWSException

Builds a job with a map of all its parameters (UWS and additional parameters).

Note: if the parameter PARAM_PHASE (phase) is given with the value PHASE_RUN the job execution starts immediately after the Job construction.

Parameters:

lstParam - Map of parameters {key: name of the parameter (see public final static fields of AbstractJob, for instance PARAM_RUN_ID) , value: value of this parameter}.

Throws:

UWSException - If a parameter is incorrect.

See Also:

AbstractJob(String, Map)

AbstractJob

protected AbstractJob(java.lang.String ownerID,
                      java.util.Map<java.lang.String,java.lang.String> lstParam)
               throws UWSException

Builds a job with the ID of the owner of this job and a map of all its parameters (UWS and additional parameters).

Note: if the parameter PARAM_PHASE (phase) is given with the value PHASE_RUN the job execution starts immediately after the job construction.

Parameters:

ownerID - Job.ownerID (PARAM_RUN_ID).

lstParam - Map of parameters {key: name of the parameter (see public final static fields of AbstractJob, for instance PARAM_RUN_ID) , value: value of this parameter}.

Throws:

UWSException - If a parameter is incorrect.

See Also:

AbstractJob(String, String, long, Date, Map)

AbstractJob

protected AbstractJob(java.lang.String jobName,
                      java.lang.String ownerId,
                      long maxDuration,
                      java.util.Date destructTime,
                      java.util.Map<java.lang.String,java.lang.String> lstParam)
               throws UWSException

Builds a job with a job name/label, an owner ID, an execution duration, a destruction time and a map of all its parameters (UWS and additional parameters).

Note: if the parameter PARAM_PHASE (phase) is given with the value PHASE_RUN the job execution starts immediately after the job construction.

Parameters:

jobName - Job.runID (PARAM_RUN_ID).

ownerId - Job.ownerID (PARAM_OWNER).

maxDuration - Job.executionduration (PARAM_EXECUTION_DURATION).

destructTime - Job.destructiontime (PARAM_DESTRUCTION_TIME).

lstParam - Map of parameters {key: name of the parameter (see public final static fields of AbstractJob, for instance PARAM_RUN_ID) , value: value of this parameter}.

Throws:

UWSException - If a parameter is incorrect.

See Also:

JobPhase.JobPhase(AbstractJob), setDestructionTime(Date), loadDefaultParams(Map), generateJobId()

AbstractJob

protected AbstractJob(java.lang.String jobId,
                      java.lang.String jobName,
                      java.lang.String ownerId,
                      ExecutionPhase phase,
                      java.util.Date startTime,
                      java.util.Date endTime,
                      long maxDuration,
                      java.util.Date destructTime,
                      java.util.List<Result> results,
                      ErrorSummary errors,
                      java.util.Map<java.lang.String,java.lang.String> additionalParams)
               throws UWSException

MANUAL CONSTRUCTOR - DISCOURAGED

Constructs a Job with all its parameters. It is the only constructor which lets setting/managing manually all the parameters/attributes of a Job. No automatic process will be done as for the other constructors.

WARNINGS:

• Whatever the given phase is, nothing will be done automatically ! It is your responsibility to really start the job if needed, put the different results and error summaries.
• The parameters given in the map will be all saved as additional parameters and without any interpretation (no call to loadAdditionalParams()).

Parameters:

jobId - Job.jobID (The identifier of this job. It must be unique).

jobName - Job.runID (PARAM_RUN_ID).

ownerId - Job.ownerID (PARAM_OWNER)

phase - Job.phase (The current execution status of this job).

startTime - Job.startTime (The time at which the job execution starts).

endTime - Job.endTime (The time at which the job execution ends).

maxDuration - Job.executionduration (PARAM_EXECUTION_DURATION).

destructTime - Job.destructiontime (PARAM_DESTRUCTION_TIME).

additionalParams - Map of all additional parameters.

Throws:

UWSException - If the given jobId is null.

Method Detail

sync

public final boolean sync()

This method is called by its job list just after the de-serialization of the whole UWS (this job included). It re-initializes the job in function of this last execution phase:

• EXECUTING or QUEUED: all results are deleted, the start/end time are reset, all the timers are restarted (execution duration and destruction time) and the execution phase is reset to PENDING.
• Otherwise: only the destruction timer is restarted if needed.

Note: the variable syncStatus is used to know whether the AbstractJob has been restored by a de-serialization. In this case it is equals to NULL. Otherwise it has another value (!= NULL ; by default: "SYNCHRONIZED").
Thus, this method will do something ONLY IF the variable syncStatus is NULL !

Returns:

true if synchronized, false if the job must not exist any more in its jobList (so it MUST be destroyed) because of an error or if the destruction time is already reached.

generateJobId

protected java.lang.String generateJobId()

This function lets generating a unique ID.

By default: System.currentTimeMillis()+UpperCharacter (UpperCharacter: one upper-case character: A, B, C, ....)

Returns:

A unique job identifier.

loadDefaultParams

protected java.util.Map<java.lang.String,java.lang.String> loadDefaultParams(java.util.Map<java.lang.String,java.lang.String> lstParam)
                                                                      throws UWSException

Loads the given parameters: all known parameters (with write access) are updated whereas others are returned in a new map in which all keys are in lower case.

Important: The phase parameter is NEVER managed here and is ALWAYS added immediately in the additional parameters attribute !

Note: UWS parameters with write access are:

• RUN_ID
• EXECUTION_DURATION
• DESTRUCTION_TIME
• PHASE if equals to PHASE_RUN or PHASE_ABORT

Note: To check more DEFAULT parameters you just have to:

1. override the function loadDefaultParams(Map)
2. call super.loadParams(Map)
3. add your own checking (do not forget to update the returned map and to return it).

Parameters:

lstParam - The list of parameters to load (UWS - included PHASE - and additional parameters).

Returns:

• a new map with all the parameters that have not been loaded (additional parameters and/or not known UWS parameter and/or the PHASE parameter)
• or an empty map
• or null if the job is executing or is ended (actually: all phase except PENDING)

Throws:

UWSException - If a given UWS parameter is not correct.

loadAdditionalParams

protected boolean loadAdditionalParams()
                                throws UWSException

Method called when updating one or several parameters using the functions addOrUpdateParameter(String, String) and addOrUpdateParameters(Map) or at the job creation.

It is useful if you need to check or to process all or a part of the additional parameters stored in additionalParameters.

By default this function does nothing and always return true.

Returns:

true if all required additional parameters have been successfully updated, false otherwise.

Throws:

UWSException - If an error occurred during the updating of one parameter.

See Also:

addOrUpdateParameter(String, String), addOrUpdateParameters(Map)

applyPhaseParam

protected void applyPhaseParam()
                        throws UWSException

Looks for an additional parameters which corresponds to the Execution Phase. If it exists and:

• is equals to RUN => remove it from the attribute additionalParameters and start the job.
• is equals to ABORT => remove it from the attribute additionalParameters and abort the job.
• is another value => the attribute stays in the attribute additionalParameters and nothing is done.

Throws:

UWSException - If it is impossible to change the Execution Phase.

See Also:

start(), abort()

getPhase

public final ExecutionPhase getPhase()

Gets the phase in which this job is now.

Returns:

The current phase of this job.

See Also:

JobPhase.getPhase()

setPhase

public final void setPhase(ExecutionPhase p)
                    throws UWSException

Sets the current phase of this job.

IMPORTANT:

• The order of all phases must be respected: BY DEFAULT
  PENDING ---> QUEUED ---> EXECUTING ---> COMPLETED.
• The only way to go to the EXECUTING phase is by sending a POST query with the value RUN for the parameter PHASE.
• The only way to go to the ABORTED phase is by sending a POST query with the value ABORT for the parameter PHASE.
• The start time and the end time are set automatically when the phase is set to EXECUTING and COMPLETED, ABORTED or ERROR

Parameters:

p - The phase to set for this job.

Throws:

UWSException - If the given phase does not respect the job's phases order.

See Also:

setPhase(ExecutionPhase, boolean)

setPhase

public final void setPhase(ExecutionPhase p,
                           boolean force)
                    throws UWSException

Sets the current phase of this job, respecting or not the imposed order.

IMPORTANT:

• If the parameter force is false, the order of all phases must be respected:
  PENDING ---> QUEUED ---> EXECUTING ---> COMPLETED.
• The only way to go to the EXECUTING phase is by sending a POST query with the value RUN for the parameter PARAM_PHASE.
• The only way to go to the ABORTED phase is by sending a POST query with the value ABORT for the parameter PARAM_PHASE.
• The start time and the end time are set automatically when the phase is set to EXECUTING and COMPLETED, ABORTED or ERROR

Parameters:

p - The phase to set for this job.

force - true to impose the given execution phase, false to take into account the order of all phases.

Throws:

UWSException - If the given phase does not respect the job's phases order.

See Also:

JobPhase.setPhase(ExecutionPhase, boolean), JobPhase.isFinished(), ExecutionManager.remove(AbstractJob), notifyObservers(ExecutionPhase)

getPhaseManager

public final JobPhase getPhaseManager()

Gets the phase manager of this job.

Note: The phase manager manages all the transitions between all the execution phases.

Returns:

Its phase manager.

setPhaseManager

public final void setPhaseManager(JobPhase jobPhase)

Sets the phase manager of this job.

Note: The phase manager manages all the transitions between all the execution phases.

Parameters:

jobPhase - Its new phase manager (if null this function does nothing).

getDateFormat

public final java.text.DateFormat getDateFormat()

Gets the used date-time formatter.

Returns:

The current date format.

setDateFormat

public final void setDateFormat(java.text.DateFormat newDateFormat)

Sets the date-time formatter to use.

Parameters:

newDateFormat - The date format which must be used from now (if null this function does nothing).

getStartTime

public final java.util.Date getStartTime()

Gets the time at which the job execution has started.

Returns:

The start time of the execution of this job.

setStartTime

protected final void setStartTime(java.util.Date newDateTime)

Sets the time at which the job execution has started.

Parameters:

newDateTime - The start time of the execution of this job.

getEndTime

public final java.util.Date getEndTime()

Gets the time at which the job execution has finished.

Returns:

The end time of the execution of this job.

setEndTime

protected final void setEndTime(java.util.Date newDateTime)

Sets the time at which the job execution has finished.

Parameters:

newDateTime - The end time of the execution of this job.

getExecutionDuration

public final long getExecutionDuration()

Gets the duration (in seconds) for which this job shall run.

Returns:

The execution duration of this job.

setExecutionDuration

public final void setExecutionDuration(long executionDuration)

Sets the duration (in seconds) for which this job shall run ONLY IF the job can updated (considering its current execution phase, see JobPhase.isJobUpdatable()).

Note: A duration of 0 (or less) implies unlimited execution duration.

Parameters:

executionDuration - The execution duration of this job.

getDestructionTime

public final java.util.Date getDestructionTime()

Gets the instant when the job shall be destroyed.

Returns:

The destruction time of this job.

setDestructionTime

public final void setDestructionTime(java.util.Date destructionTime)

Sets the instant when the job shall be destroyed ONLY IF the job can updated (considering its current execution phase, see JobPhase.isJobUpdatable()). If known the jobs list is notify of this destruction time update.

Parameters:

destructionTime - The destruction time of this job.

See Also:

JobPhase.isJobUpdatable(), JobList.updateDestruction(AbstractJob)

getErrorSummary

public final ErrorSummary getErrorSummary()

Gets the error that occurs during the execution of this job.

Returns:

A summary of the error.

setErrorSummary

public final void setErrorSummary(ErrorSummary errorSummary)
                           throws UWSException

Sets the error that occurs during the execution of this job.

IMPORTANT: This function will have no effect if the job is finished, that is to say if the current phase is ABORTED, ERROR or COMPLETED..

Parameters:

errorSummary - A summary of the error.

Throws:

UWSException - If the job execution is finished that is to say if the phase is ABORTED, ERROR or COMPLETED.

See Also:

isFinished()

getJobId

public final java.lang.String getJobId()

Gets the ID of this job (this ID MUST be unique).

Returns:

The job ID (unique).

getRunId

public final java.lang.String getRunId()

Gets the RunID of this job given by the UWS user (presumed to be the owner of this job). This ID isn't the one used to access to this job thanks to the jobs list: it is more likely a label/name than an ID => it is not unique.

Warning: This ID may be used by other jobs BUT their job id (cf getJobId()) must be different.

Returns:

The Run ID (a kind of job name/label).

setRunId

public final void setRunId(java.lang.String name)

Sets the RunID of this job ONLY IF the job can updated (considering its current execution phase, see JobPhase.isJobUpdatable()).

Parameters:

name - Its name/label.

See Also:

JobPhase.isJobUpdatable()

getOwner

public final java.lang.String getOwner()

Gets the ID of the owner of this job.

Returns:

The owner ID.

getQuote

public final long getQuote()

Get the quote attribute of this job.

Returns:

The estimated duration of the job execution (in seconds).

setQuote

public final void setQuote(long nbSeconds)

Sets the quote attribute of this job ONLY IF the job can updated (considering its current execution phase, see JobPhase.isJobUpdatable()).

Parameters:

nbSeconds - The estimated duration of the job execution (in seconds).

See Also:

JobPhase.isJobUpdatable()

getAdditionalParameters

public final java.util.Set<java.lang.String> getAdditionalParameters()

Gets the list of parameters' name.

Returns:

The additional parameters of this job.

getNbAdditionalParameters

public final int getNbAdditionalParameters()

Gets the number of additional parameters.

Returns:

Number of additional parameters.

getAdditionalParameterValue

public final java.lang.String getAdditionalParameterValue(java.lang.String paramName)

Gets the value of the specified additional parameter.

Parameters:

paramName - The name of the parameter whose the value is wanted.

Returns:

The value of the specified parameter or null if it doesn't exist.

addOrUpdateParameter

public final boolean addOrUpdateParameter(java.lang.String paramName,
                                          java.lang.String paramValue)
                                   throws UWSException

Adds or updates the specified parameter with the given value ONLY IF the job can be updated (considering its current execution phase, see JobPhase.isJobUpdatable()).

Parameters:

paramName - The name of the parameter to add or to update.

paramValue - The (new) value of the specified parameter.

Returns:

• true if the parameter has been successfully added/updated,
• false otherwise (particularly if paramName=null or paramName="" or paramValue=null).

Throws:

UWSException - If a parameter value is incorrect.

See Also:

JobPhase.isJobUpdatable(), addOrUpdateParameters(Map)

addOrUpdateParameters

public boolean addOrUpdateParameters(java.util.Map<java.lang.String,java.lang.String> params)
                              throws UWSException

Adds or updates the given parameters ONLY IF the job can be updated (considering its current execution phase, see JobPhase.isJobUpdatable()).

Whatever is the result of loadDefaultParams(Map) the method applyPhaseParam() is called so that if there is an additional parameter PARAM_PHASE with the value:

• RUN then the job is starting and the phase goes to EXECUTING.
• ABORT then the job is aborting.
• otherwise the parameter PARAM_PHASE remains in the additionalParameters list.

Parameters:

params - A list of parameters to add/update.

Returns:

• true if all the given parameters have been successfully added/updated,
• false if some parameters have not been managed.

Throws:

UWSException - If a parameter value is incorrect.

See Also:

loadDefaultParams(Map), JobPhase.isJobUpdatable(), loadAdditionalParams(), applyPhaseParam()

removeAdditionalParameter

public final boolean removeAdditionalParameter(java.lang.String paramName)

Removes the specified additional parameter ONLY IF the job can be updated (considering its current execution phase, see JobPhase.isJobUpdatable()).

Parameters:

paramName - The name of the parameter to remove.

Returns:

true if the parameter has been successfully removed, false otherwise.

See Also:

JobPhase.isJobUpdatable()

removeAllAdditionalParameter

public final void removeAllAdditionalParameter()

Clears the whole list of additional parameters ONLY IF the job can be updated (considering its current execution phase, see JobPhase.isJobUpdatable()).

See Also:

JobPhase.isJobUpdatable()

getResults

public final java.util.Iterator<Result> getResults()

Gets the results list of this job.

Returns:

An iterator on the results list.

getNbResults

public final int getNbResults()

Gets the total number of results.

Returns:

The number of results.

addResult

public boolean addResult(Result res)
                  throws UWSException

Adds the given result in the results list of this job.

IMPORTANT: This function will throw an error if the job is finished.

Parameters:

res - The result to add (not null).

Returns:

true if the result has been successfully added, false else.

Throws:

UWSException - If the job execution is finished that is to say if the phase is ABORTED, ERROR or COMPLETED.

See Also:

isFinished()

getExecutionManager

public final ExecutionManager getExecutionManager()

Gets the execution manager of this job, if any.

Returns:

Its execution manager (may be null).

setExecutionManager

public final void setExecutionManager(ExecutionManager newManager)
                               throws UWSException

Sets the execution manager of this job.

Parameters:

newManager - Its new execution manager (may be null ; in this case the job will always start immediately => no QUEUED phase).

Throws:

UWSException - If there is an error when removing this job from the former execution manager or when updating the new execution manager.

See Also:

ExecutionManager.remove(AbstractJob), ExecutionManager.update(AbstractJob)

getJobList

public final JobList<? extends AbstractJob> getJobList()

Gets its jobs list, if known.

Returns:

Its jobs list (may be null).

setJobList

public final void setJobList(JobList<? extends AbstractJob> jobList)
                      throws UWSException

Sets its jobs list.

Note: If the given jobs list does not know this job, it will be added immediately (see JobList.addNewJob(AbstractJob)). Obviously, before all, we ensure that the job is removed from its former jobs list.

Parameters:

jobList - Its new jobs list (may be null).

Throws:

UWSException - If an error occurs when adding this job in the given jobs list.

See Also:

JobList.removeJob(String), JobList.getJob(String), JobList.addNewJob(AbstractJob)

getTimeToWaitForEnd

public final long getTimeToWaitForEnd()

Gets the time to wait for the end of the thread after an interruption.

Returns:

The time to wait for the end of the thread (a negative or null value means no wait for the end of the thread).

setTimeToWaitForEnd

public final void setTimeToWaitForEnd(long timeToWait)

Sets the time to wait for the end of the thread after an interruption.

Parameters:

timeToWait - The new time to wait for the end of the thread (a negative or null value means no wait for the end of the thread).

start

public final void start()
                 throws UWSException

Starts the job by using the execution manager if any.

Throws:

UWSException

start

public void start(boolean useManager)
           throws UWSException

Starts the job.

Note: This function does nothing if the job is already running !

Parameters:

useManager - true to let the execution manager deciding whether the job starts immediately or whether it must be put in a queue until enough resources are available, false to start the execution immediately.

Throws:

UWSException - If there is an error while changing the execution phase or when starting the corresponding thread.

See Also:

isRunning(), ExecutionManager.execute(AbstractJob), setPhase(ExecutionPhase), isFinished(), startTime

isRunning

public final boolean isRunning()

Tells whether the job is still running.

Note: This function tests the execution phase (see JobPhase.isExecuting()) AND the status of the thread (see isStopped()).

Returns:

true if the job is still running, false otherwise.

See Also:

JobPhase.isExecuting(), isStopped()

isFinished

public final boolean isFinished()

Tells whether the job is already finished (completed, aborted, error, ...).

Note: This function test the execution phase (see JobPhase.isFinished()) AND the status of the thread (see isStopped())

Returns:

true if the job is finished, false otherwise.

See Also:

JobPhase.isFinished(), isStopped()

abort

public void abort()
           throws UWSException

Stops immediately the job, sets its phase to ABORTED and sets its end time.

IMPORTANT: If the thread does not stop immediately the phase and the end time are not modified. However it can be done by calling one more time abort(). Besides you should check that you test regularly the interrupted flag of the thread in jobWork() !

Throws:

UWSException - If there is an error while changing the execution phase.

See Also:

stop(), isStopped(), setPhase(ExecutionPhase), setEndTime(Date)

error

public void error(ErrorSummary error)
           throws UWSException

Stops immediately the job, sets its error summary, sets its phase to ExecutionPhase.ERROR and sets its end time.

IMPORTANT: If the thread does not stop immediately the phase, the error summary and the end time are not modified. However it can be done by calling one more time error(ErrorSummary). Besides you should check that you test regularly the interrupted flag of the thread in jobWork() !

Parameters:

error - The error that has interrupted this job.

Throws:

UWSException - If there is an error while setting the error summary or while changing the phase.

See Also:

stop(), isStopped(), JobPhase.isFinished(), setErrorSummary(ErrorSummary), setPhase(ExecutionPhase), setEndTime(Date)

error

public void error(UWSException ue)
           throws UWSException

Publishes the given exception as an error summary. Doing that also stops the job, sets the phase to ExecutionPhase.ERROR and sets the end time.

Note: This function only calls UWSToolBox.publishErrorSummary(AbstractJob, String, ErrorType). An exception is thrown only if the publication has failed.

Parameters:

ue - The exception that has interrupted this job.

Throws:

UWSException - If there is an error while publishing the given exception.

See Also:

UWSToolBox.publishErrorSummary(AbstractJob, String, ErrorType)

stop

protected void stop()

Stops the thread that executes the work of this job.

isStopped

protected final boolean isStopped()

Tells whether the thread is different from null, is not alive, is interrupted or is finished (see JobThread.isFinished()).

Returns:

true if the thread is not still running, false otherwise.

jobWork

protected abstract void jobWork()
                         throws UWSException,
                                java.lang.InterruptedException

Does the job work (i.e. making a long computation or executing a query on a Database).

Important:

• This method does the job work but it MUST also fill the associated job with the execution results and/or errors.
• Do not forget to check the interrupted flag of the thread (Thread.isInterrupted()) and then to send an InterruptedException. Otherwise the stop() method will have no effect, as for abort() and error(ErrorSummary).

Notes:

• The "setPhase(COMPLETED)" and the "endTime=new Date()" are automatically applied just after the call to jobWork.
• If an UWSException is thrown the JobThread will automatically publish the exception in this job thanks to the error(UWSException) method or the setErrorSummary(ErrorSummary) method, and so it will set its phase to ExecutionPhase.ERROR.
• If an InterruptedException is thrown the JobThread will automatically set the phase to ExecutionPhase.ABORTED

Throws:

UWSException - If there is any kind of error which must be propagated.

java.lang.InterruptedException - If the thread has been interrupted or if any method throws this exception.

clearResources

public void clearResources()

Stops the job if running, removes the job from the execution manager, stops the timer for the execution duration and may clear all files or any other resources associated to this job.

By default the job is aborted, only the thread attribute is set to null and the timers are stopped; no other operations (i.e. clear result files and error files) is done.

finalize

protected void finalize()
                 throws java.lang.Throwable

Merely clears resources: it only calls clearResources().

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

See Also:

clearResources(), Object.finalize()

addObserver

public final boolean addObserver(JobObserver observer)

Lets adding an observer of this job. The observer will be notified each time the execution phase changes.

Parameters:

observer - A new observer of this job.

Returns:

true if the given object has been successfully added as observer of this job, false otherwise.

getNbObservers

public final int getNbObservers()

Gets the total number of observers this job has.

Returns:

Number of its observers.

getObservers

public final java.util.Iterator<JobObserver> getObservers()

Gets the observers of this job.

Returns:

An iterator on the list of its observers.

removeObserver

public final boolean removeObserver(JobObserver observer)

Lets removing the given object from the list of observers of this job.

Parameters:

observer - The object which must not be considered as observer of this job.

Returns:

true if the given object is not any more an observer of this job, false otherwise.

removeAllObservers

public final void removeAllObservers()

Lets removing all observers of this job.

notifyObservers

public final void notifyObservers(ExecutionPhase oldPhase)
                           throws UWSException

Notifies all the observer of this job that its phase has changed.

Parameters:

oldPhase - The former phase of this job.

Throws:

UWSException - If at least one observer can not have been updated.

getWorkError

public final UWSException getWorkError()

Gets the error (if any) which has occurred during the job execution.

Note: In the case an error summary can not have been published, the job has no error summary. However the last UWSException caught during the execution of a JobThread is saved and is available thanks to JobThread.getError(). In that case, the getWorkError() method can be used to get back the occurred error.

Returns:

The error which interrupts the thread or null if there was no error or if the job is still running.

serialize

public java.lang.String serialize(UWSSerializer serializer,
                                  java.lang.String ownerId)
                           throws UWSException

Description copied from class: SerializableUWSObject

Serializes the whole object considering the given owner ID (supposed to be the ID of the current user) and thanks to the given serializer.

Specified by:

serialize in class SerializableUWSObject

Parameters:

serializer - The serializer to use.

ownerId - The ID of the current user.

Returns:

The serialized representation of this object.

Throws:

UWSException - If there is an error during the serialization.

serialize

public java.lang.String serialize(java.lang.String[] attributes,
                                  UWSSerializer serializer)
                           throws UWSException

Serializes the specified attribute of this job by using the given serializer.

Parameters:

attributes - All the given attributes (may be null or empty).

serializer - The serializer to use.

Returns:

The serialized job attribute (or the whole job if attributes is an empty array or is null).

Throws:

UWSException - If there is an error during the serialization.

See Also:

UWSSerializer.getJob(AbstractJob, String[], boolean)

serialize

public void serialize(java.io.OutputStream output,
                      java.lang.String[] attributes,
                      UWSSerializer serializer)
               throws UWSException

Serializes the specified attribute of this job in the given output stream by using the given serializer.

Parameters:

output - The output stream in which the job attribute must be serialized.

attributes - The name of the attribute to serialize (if null, the whole job will be serialized).

serializer - The serializer to use.

Throws:

UWSException - If there is an error during the serialization.

See Also:

serialize(String[], UWSSerializer)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object anotherJob)

2 instances of AbstractJob are equals ONLY IF their ID are equals.

Note: If the given object is not an AbstractJob, super.equals(..) is called.

Overrides:

equals in class java.lang.Object

See Also:

Object.equals(java.lang.Object)

getOtherParameters

@Deprecated
public final java.util.Set<java.lang.String> getOtherParameters()

Deprecated. Replaced by getAdditionalParameters()

Gets the list of parameters' name.

Returns:

The additional parameters of this job.

getNbOtherParameters

@Deprecated
public final int getNbOtherParameters()

Deprecated. Replaced by getNbAdditionalParameters().

Gets the number of additional parameters.

Returns:

Number of additional parameters.

getOtherParameterValue

@Deprecated
public final java.lang.String getOtherParameterValue(java.lang.String paramName)

Deprecated. Replaced by getAdditionalParameterValue(String).

Gets the value of the specified additional parameter.

Parameters:

paramName - The name of the parameter whose the value is wanted.

Returns:

The value of the specified parameter or null if it doesn't exist.

removeOtherParameter

@Deprecated
public final boolean removeOtherParameter(java.lang.String paramName)

Deprecated. Replaced by removeAdditionalParameter(String).

Removes the specified additional parameter.

Parameters:

paramName - The name of the parameter to remove.

Returns:

true if the parameter has been successfully removed, false otherwise.

removeAllOtherParameter

@Deprecated
public final void removeAllOtherParameter()

Deprecated. Replaced by removeAllAdditionalParameter().

Clears the whole list of additional parameters.

checkPhaseParam

@Deprecated
protected final void checkPhaseParam()
                              throws UWSException

Deprecated. applyPhaseParam().

Checks whether there is an additional parameters which corresponds to the Execution Phase. If it exists and:

• is equals to RUN => remove it from the attribute otherParameters and start the job.
• is equals to ABORT => remove it from the attribute otherParameters and abort the job.
• is another value => the attribute stays in the attribute otherParameters and nothing is done.

Throws:

UWSException - If it is impossible to change the Execution Phase.

publishExecutionError

@Deprecated
protected final boolean publishExecutionError(UWSException ue)
                                       throws UWSException

Deprecated. Replaced by error(UWSException).

Sets the phase to ERROR and sets the error summary thanks to the given UWSException.

Note: By default this method ONLY set the phase to ERROR and write the message of the given exception in a new error summary. To change this behavior (for instance writing an error file) you need to override this function (for instance you can call the function UWSToolBox.publishErrorSummary(AbstractJob, Exception, ErrorType, java.net.URL, String, String))

Parameters:

ue - The UWSException to use to publish the error summary.

Returns:

true if the error has been successfully published, false otherwise.

Throws:

UWSException - It there is an error while setting the phase or setting the summary or writing the error file (if any).

See Also:

UWSToolBox.publishErrorSummary(AbstractJob, String, ErrorType)