C. How to customize a Job ?
4. Error summary
How does it work ?
An error summary is published when any error occurs during the job execution. A full error summary is composed of three pieces of information: a brief message, an error type (transient or fatal) and a URI/URL of a detailed message. In all cases if a job has ended with an error, the type of the error and a boolean which indicates whether there is a detailed message must always be given. Although an error is intended to always have a detailed message, the "brief message" is optional: it is only a sum up of the full message (or its title).
Now, in this library an error summary is published when any exception - except InterruptedException which stops the job with the phase ABORTED - occurs during the execution of a job, that is to say during the call of jobWork(). The publication is done by the function error(UWSException). When an exception is thrown in jobWork(), it is caught and encapsulated in a UWSException (if needed), which is then given as parameter of the function error(UWSException).
By default the function error(UWSException) only calls the function UWSToolBox.publishErrorSummary(AbstractJob, String msg, ErrorType):
public abstract class AbstractJob extends SerializableUWSObject {
...
protected synchronized boolean publishExecutionError(UWSException ue) throws UWSException {
boolean published = UWSToolBox.publishErrorSummary(this, (ue.getCause() != null)?ue.getCause().getMessage():ue.getMessage(), ue.getUWSErrorType());
if (!published)
throw new UWSException("[Set an error] Impossible to set the given UWS exception to the job "+jobId+" !");
}
...
}
UWSToolBox.publishErrorSummary(AbstractJob, String msg, ErrorType) builds an error summary and sets the job phase to ERROR. Because it is impossible, in a generic manner, to know where to write a file with the detailed message of an error, by default only the "brief message" and the error type are set: there is no detailed message.
How to customize ?
To change the default error publication, you must override the function error(UWSException).
For instance to write a detailed message you can call the other function of UWSToolBox: publishErrorSummary(AbstractJob, Exception, ErrorType, URL errorFileUrl, String errorsDirectory, String errorFileName) In this case, the "brief message" and the error type will be filled in the same way than with the other function, but in addition the stack trace of the given exception will be written in the specified file (in errorsDirectory/errorFileName). The URL errorFileUrl is used to indicate a public access to read the detailed message. It will be used to make a redirection when the user types the URI /uws/jobList/job/error.
IMPORTANT
You must take care to check the current execution phase of the job before doing anything ! Indeed the error summary can be set only if the job has not been already stopped before: the publication of an error summary MUST set its phase to ERROR.