Reminder
A. UWS, in brief In few words, what is a UWS service?
1. An asynchronous service
The Universal Worker Service (UWS) pattern defines how to manage asynchronous execution of jobs on a service.
In a synchronous service the client must wait a response for each sent request. Thus he can make only one request at a time and if he disconnects from the service the request is abandoned.
UWS is an asynchronous service. It means the client has not to wait for the response of one request before making another one. Thus, it is possible that a request is executing for hours or days even if the client disconnects from the service. Indeed UWS is also (as most of asynchronous services) a state-full service: it stores the state of each received request.
2. A job-oriented service
UWS consists logically of a set of objects that may be read and written to in order to control jobs. The objects are represented by elements within XML schema [...].
A UWS is organized in one or more JobList objects.
A JobList is a collection of Jobs.
A Job is described by:
- an ID: a unique identifier of the job in its JobList
- a RunID: a kind of label or name of the job given by its owner (it is not used to identify the job)
- an Execution Phase: the state of the job
- an Execution Duration: the maximum authorized duration of the job
- a Deletion Time: the time at which the job must be aborted and removed from its JobList
- a Quote: the estimated end date-time of the job
- one or more results: all the results of the job execution
- one or zero error: the error which has occurred during the job execution
- zero or more additional parameters: parameters useful for the job execution
3. Resources and URIs
In a REST binding of UWS, each of the objects defined above is available as a web resource with its own URI. These URIs must form a hierarchy [...]
Considering {jobs} as a name or an identifier of a JobList and {job-id} a JobID:
| URI | Description | Value | Writable |
|---|---|---|---|
| /{jobs} | List of all jobs contained in the JobList {jobs} | NO | |
| /{jobs}/{job-id} | Description/Summary of the Job {job-id} | NO | |
| /{jobs}/{job-id}/runid | RunID of the Job {job-id} | A String value | YES |
| /{jobs}/{job-id}/phase | Execution Phase of the Job {job-id} | PENDING, QUEUED, EXECUTING, COMPLETED, ERROR, ABORTED, UNKNOWN, HELD or SUSPENDED | YES |
| /{jobs}/{job-id}/owner | Owner of the Job {job-id} | ? (by default a String value) | NO |
| /{jobs}/{job-id}/quote | Quote of the Job {job-id}: estimated end date-time of the job execution. | A date with the format "yyyy-MM-dd'T'HH:mm:ss.SSSZ" (ISO:8601) | NO |
| /{jobs}/{job-id}/executionduration | Execution Duration (in seconds) of the Job {job-id} | Integer number of seconds ≥ 0 ; 0 means unlimited execution duration | YES |
| /{jobs}/{job-id}/destruction | Destruction Time of the Job {job-id} | A date with the format "yyyy-MM-dd'T'HH:mm:ss.SSSZ" (ISO:8601) | YES |
| /{jobs}/{job-id}/error | Description/Summary of the error of the Job {job-id} | NO | |
| /{jobs}/{job-id}/results | Results list of the Job {job-id} | NO | |
| /{jobs}/{job-id}/parameters | List of the additional parameters of the Job {job-id} | YES |
All these web resources are formatted in XML according to the UWS Schema available in the Appendix B of the IVOA Recommendation. Now almost all browsers are able to transform on the client side an XML document into a HTML document by using an XSLT resource (Click here to see an XSLT tutorial).
B. Using a UWS service All possible standard actions
In this part the usability of UWS will be described through an example: the UWS Timers service. Its URL is http://cdsportal.u-strasbg.fr/uwstuto/basic. It manages only one JobList named timers. An HTML form to interact with this UWS is available at http://cdsportal.u-strasbg,fr/uwstuto/basic.html. With this form you can easily manipulate the URL, the HTTP method and the parameters. Thus, you can experiment yourself the different types of request and better understand how to use a UWS service.
So, now, let's see all possible UWS actions!
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers
- Method: GET
- Parameters: none
To list all the jobs of a JobList you only have to access in HTTP-GET the web resource associated with the JobList. Here the only job list available is named: timers.
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers
- Method: POST
- Parameters:
RUNID=...(optional ; name or label of the job ; no special meaning in the UWS service)EXECUTIONDURATION=...(optional ; a duration in seconds is expected)DESTRUCTION=...(optional ; a destruction date formatted in ISO-8601 is expected)PHASE=RUN(optional ; to start the job just after its creation)- one or several additional implementation dependant parameters (i.e. job/task parameters)
Once created the HTTP response to this request must be a redirection to the summary of the Job, that is to say: an HTTP code 303 ("See other") and the URL http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345 (where 12345 is supposed to be the ID of the created job).
No parameter is by default required by the UWS protocol. However, processing proposed by UWS services may require some. The other parameters listed above are standard UWS parameters which let limit the execution and destruction of the job to create.
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345
- Method: GET
- Parameters: none
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345/{attr}
- Method: GET
- Parameters: none
The {attr} element must be replaced by one of the following to get the value of the corresponding job attribute:
- jobid
- runid
- phase
- owner
- quote
- executionduration
- destruction
- parameters
- error
- results
An XML document will be returned for the 3 last attributes. For all the others, the value will be returned as
a simple text/plain content.
The attribute parameters lets get the list of all additional parameters provided by the user at job creation time. The UWS standard does specify how to get the whole list of all these parameters, but does not say anything about getting one of them. It is however possible to set them individually according to the same IVOA definition. So, we can assume that some UWS services may allow to get individually an additional parameter with the URI like: /timers/12345/parameters/{addParamName} (where {addParamName} must be replaced by the name of the parameter to get, with the exact case).
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345/{attr}
- Method: POST
- Parameters: A parameter name and value pair (e.g.
executionduration=30)
In a UWS service, only 2 job attributes can be changed: executionduration and destruction. All the other attributes can not be modified.
Job attributes can be changed only if the job is not running or is not finished.
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345/parameters/{addParamName}
- Method: PUT
- Parameters: A parameter name and value pair (e.g.
time=20)
OR
- URL: 2 possibilities in function of the method supported by the UWS implementation:
- http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345
- http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345/parameters
- Method: POST
- Parameters: A parameter name and value pair (e.g.
time=20)
Only modification of parameter is possible once the job is created. No parameter can be added or removed afterwards. Thus the only way to give parameters to a job is while sending the initial HTTP-POST resquest.
Job parameters can be changed only if the job is not running or is not finished.
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345/phase
- Method: POST
- Parameters:
PHASE=RUN
Once this request received by the service, the job 12345's phase will go from
PENDING to EXECUTING through QUEUED. It might stay in the QUEUED phase
until the service has enough resources to start the job.
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345/phase
- Method: POST
- Parameters:
PHASE=ABORT
Immediately when the service receives this request, the job should stop. Once stopped consequently to this request,
the phase must go to ABORTED.
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345
- Method: DELETE
- Parameters: none
OR
- URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345
- Method: POST
- Parameters:
ACTION=DELETE
When receiving one of these two request the Job execution must abort, all resources associated with the Job (result file, error file, ...) must be deleted and finally the Job must be removed from its JobList. The response to these requests is a redirection to the JobList.
9. Important notes
- When the execution is longer than the given Execution Duration, the job must be aborted. But all previously generated results are retained.
- When the Destruction Time of a Job is reached, the job must be aborted - if running - and destroyed (included all generated results and errors).
-
The Execution Phase cannot be changed freely!
The Job is treated as a state machine with the Execution Phase naming the state.
[...]
A successful job will normally progress through the PENDING, QUEUED, EXECUTING, COMPLETED phases in that order. At any time before the COMPLETED phase a job may either be ABORTED or may suffer an ERROR.
