uws.job

Class JobThread

java.lang.Object

java.lang.Thread

uws.job.JobThread

All Implemented Interfaces:

java.lang.Runnable

Direct Known Subclasses:

AsyncThread

public abstract class JobThread
extends java.lang.Thread

An instance of this class is a thread dedicated to a job execution.

This thread is necessary associated with a UWSJob instance. Thus the execution of this thread is mainly done in the jobWork() method.

However its execution is possible only if the job phase is EXECUTING. The job phase constraint (=EXECUTING) is already checked so it is useless to check it again in jobWork().

At the end of the execution the job must be correctly filled (cf jobWork()) according to the execution conclusion:

• SUCCESS: the results field of job must be filled (see publishResult(Result) and getResultOutput(Result)),
• ABORTED: the method UWSJob.abort() must be called or an InterruptedException can be thrown
• ERROR: the errors field must be filled by calling setError(ErrorSummary) or setError(UWSException).

In both cases the startTime and the endTime fields are already managed by UWSJob so it is useless to change them.

Just after the job work the job phase is set to COMPLETED if no interruption has been detected, ABORTED otherwise.

If jobWork() throws:

• a UWSException: the method setError(UWSException) is called. Besides the exception is kept in the lastError and is available thanks to the UWSJob.getWorkError().
• an InterruptedException: the method UWSJob.abort() is called.

Version:

4.1 (04/2015)

Author:

Grégory Mantelet (CDS;ARI)

See Also:

UWSJob.start(), UWSJob.abort(), UWSJob.getFileManager(), UWSJob.getWorkError()

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler

Field Summary

Fields

Modifier and Type	Field and Description
protected ServiceErrorWriter	errorWriter Object to use in order to write the content of an error/exception in any output stream.
protected boolean	fatalError Indicate whether the exception stored in the attribute lastError should be considered as a grave error or not.
protected boolean	finished Indicates whether the jobWork() has been called and finished, or not.
protected UWSJob	job The job which contains all parameters for its execution and which must be filled at the end of the execution.
protected UWSException	lastError The last error which has occurred during the execution of this thread.
protected java.lang.String	taskDescription Description of what is done by this thread.
static java.lang.ThreadGroup	tg Group of threads in which this job thread will run.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

Constructors

Constructor and Description
JobThread(UWSJob j) Builds the JobThread instance which will be used by the given job to execute its task.
JobThread(UWSJob j, ServiceErrorWriter errorWriter) Builds the JobThread instance which will be used by the given job to execute its task.
JobThread(UWSJob j, java.lang.String task) Builds the JobThread instance which will be used by the given job to execute its task.
JobThread(UWSJob j, java.lang.String task, ServiceErrorWriter errorWriter) Builds the JobThread instance which will be used by the given job to execute its task.

Method Summary

Modifier and Type	Method and Description
Result	createResult() Creates a default result description.
Result	createResult(java.lang.String name) Creates a default result description but by precising its name/ID.
protected static java.lang.String	getDefaultTaskDescription(UWSJob job) Gets a default description of the task executed by a JobThread.
UWSException	getError() Gets the last error which has occurred during the execution of this thread.
UWSFileManager	getFileManager() Gets the manager of the UWS files (particularly: the error and results file).
UWSJob	getJob() Gets the job instance associated to this thread.
java.io.OutputStream	getResultOutput(Result resultToWrite) Gets an output stream for the given result.
long	getResultSize(Result result) Gets the size of the corresponding result file.
boolean	isFinished() Indicates whether the jobWork() method has been called or not.
protected abstract void	jobWork() Does the job work (i.e.
void	publishResult(Result result) Publishes the given result in the job.
void	run() Tests the execution phase of the job: if not EXECUTING, nothing is done...the thread ends immediately. Calls the jobWork() method. Sets the finished flag to true. Changes the job phase to COMPLETED if not interrupted, else ABORTED.
void	setError(ErrorSummary error) Published the given error in the job.
void	setError(UWSException ue) Publishes the given exception as an error summary.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

job

protected final UWSJob job

The job which contains all parameters for its execution and which must be filled at the end of the execution.

lastError

protected UWSException lastError

The last error which has occurred during the execution of this thread.

fatalError

protected boolean fatalError

Indicate whether the exception stored in the attribute lastError should be considered as a grave error or not. By default, lastError is a "normal" error.

Since:

4.1

finished

protected boolean finished

Indicates whether the jobWork() has been called and finished, or not.

taskDescription

protected final java.lang.String taskDescription

Description of what is done by this thread.

errorWriter

protected final ServiceErrorWriter errorWriter

Object to use in order to write the content of an error/exception in any output stream. If NULL, the content will be written by UWSToolBox.writeErrorFile(Exception, ErrorSummary, UWSJob, OutputStream) (in text/plain with stack-trace). Otherwise the content and the MIME type are determined by the error writer.

Since:

4.1

tg

public static final java.lang.ThreadGroup tg

Group of threads in which this job thread will run.

Constructor Detail

JobThread

public JobThread(UWSJob j)
          throws java.lang.NullPointerException

Builds the JobThread instance which will be used by the given job to execute its task.

Parameters:

j - The associated job.

Throws:

java.lang.NullPointerException - If the given job or the given file manager is null.

See Also:

getDefaultTaskDescription(UWSJob)

JobThread

public JobThread(UWSJob j,
                 ServiceErrorWriter errorWriter)
          throws java.lang.NullPointerException

Builds the JobThread instance which will be used by the given job to execute its task.

Parameters:

j - The associated job.

errorWriter - Object to use in case of error in order to format the details of the error for the .../error/details parameter.

Throws:

java.lang.NullPointerException - If the given job is null.

Since:

4.1

See Also:

getDefaultTaskDescription(UWSJob)

JobThread

public JobThread(UWSJob j,
                 java.lang.String task)
          throws java.lang.NullPointerException

Builds the JobThread instance which will be used by the given job to execute its task.

Parameters:

j - The associated job.

task - Description of the task executed by this thread.

Throws:

java.lang.NullPointerException - If the given job is null.

JobThread

public JobThread(UWSJob j,
                 java.lang.String task,
                 ServiceErrorWriter errorWriter)
          throws java.lang.NullPointerException

Builds the JobThread instance which will be used by the given job to execute its task.

Parameters:

j - The associated job.

task - Description of the task executed by this thread.

errorWriter - Object to use in case of error in order to format the details of the error for the .../error/details parameter.

Throws:

java.lang.NullPointerException - If the given job is null.

Since:

4.1

Method Detail

getDefaultTaskDescription

protected static final java.lang.String getDefaultTaskDescription(UWSJob job)

Gets a default description of the task executed by a JobThread.

Parameters:

job - A UWS job.

Returns:

A default description of a JobThread which will execute the given job.

getJob

public final UWSJob getJob()

Gets the job instance associated to this thread.

Returns:

The associated job instance.

getFileManager

public final UWSFileManager getFileManager()

Gets the manager of the UWS files (particularly: the error and results file).

Returns:

The used file manager.

getError

public final UWSException getError()

Gets the last error which has occurred during the execution of this thread.

Returns:

The last error.

isFinished

public final boolean isFinished()

Indicates whether the jobWork() method has been called or not.

Returns:

true if the job work is done, false otherwise.

setError

public void setError(ErrorSummary error)
              throws UWSException

Published the given error in the job.

note: This thread will be stopped.

Parameters:

error - The error to publish.

Throws:

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

See Also:

UWSJob.error(ErrorSummary)

setError

public void setError(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.

By default, this function tries to write the stack trace of the given exception thanks to UWSFileManager.getErrorOutput(ErrorSummary, UWSJob). If it fails or if this job is not connected to a job list or the connected job list is not connected to a UWS, setError(ErrorSummary) is called and no error file is written.

Parameters:

ue - The exception that has interrupted this job.

Throws:

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

See Also:

setError(ErrorSummary), UWSToolBox.writeErrorFile(Exception, ErrorSummary, UWSJob, OutputStream)

createResult

public Result createResult()

Creates a default result description.

Returns:

The created result.

See Also:

createResult(String)

createResult

public Result createResult(java.lang.String name)

Creates a default result description but by precising its name/ID.

Parameters:

name - The name/ID of the result to create.

Returns:

The created result.

See Also:

Result.Result(UWSJob, String)

publishResult

public void publishResult(Result result)
                   throws UWSException

Publishes the given result in the job.

Parameters:

result - The result to publish.

Throws:

UWSException - If there is an error while publishing the result.

See Also:

UWSJob.addResult(Result)

getResultOutput

public java.io.OutputStream getResultOutput(Result resultToWrite)
                                     throws java.io.IOException,
                                            UWSException

Gets an output stream for the given result.

note: the result file will be created if needed.

Parameters:

resultToWrite - The description of the result to write.

Returns:

An output stream for the given result.

Throws:

java.io.IOException - If there is an error while creating the file or the output stream.

UWSException - If an error occurs in the UWSFileManager.getResultOutput(Result, UWSJob).

getResultSize

public long getResultSize(Result result)
                   throws java.io.IOException

Gets the size of the corresponding result file.

Parameters:

result - Description of the Result whose the size is wanted.

Returns:

The size of the corresponding result file.

Throws:

java.io.IOException - If there is an error while getting the result file size.

See Also:

UWSFileManager.getResultSize(Result, UWSJob)

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 UWSJob.stop() method will have no effect, as for UWSJob.abort() and setError(ErrorSummary).

Notes:

• The "setPhase(COMPLETED)" and the "endTime=new Date()" are automatically applied just after the call to jobWork.
• If a UWSException is thrown the JobThread will automatically publish the exception in this job thanks to the UWSJob.error(ErrorSummary) method or the UWSJob.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.

run

public final void run()

1. Tests the execution phase of the job: if not EXECUTING, nothing is done...the thread ends immediately.
2. Calls the jobWork() method.
3. Sets the finished flag to true.
4. Changes the job phase to COMPLETED if not interrupted, else ABORTED.

If any InterruptedException occurs the job phase is only set to ABORTED.

If any UWSException occurs while the phase is EXECUTING the job phase is set to ERROR and an error summary is created.

Whatever is the exception, it will always be available thanks to the getError() after execution.

Specified by:

run in interface java.lang.Runnable

Overrides:

run in class java.lang.Thread

See Also:

jobWork(), UWSJob.setPhase(ExecutionPhase), setError(UWSException), setError(ErrorSummary)