• Previous
• Next
• Home
• The IVOA Recommendation
  • A. Brief Reminder of UWS
  • B. Using a UWS
• The UWS Library
  • A. Getting started
  • B. Example: The UWS Timers
  • C. How to customize a Job ?
  • D. How to customize a UWS ?
  • E. UWS Tools-Box
  • F. Javadoc
• Go to...
  • 1. List jobs
  • 2. Create a job
  • 3. Get a job summary
  • 4. Change some job parameters
  • 5. Start a job
  • 6. Abort a job
  • 7. Destroy a job
  • 8. Important notes
• 
• 

B. Using a UWS

In this part the usability of UWS will be described through an example: the UWS Timers. Its URL is http://cdsportal.u-strasbg.fr/uwstuto/basic. It manages only one JobList named timers. A HTML form to interact with this UWS is available at http://cdsportal.u-strasbg.fr/uwstuto/3.0/basic.html. With this form you can easily manipulate the URL, the HTTP method and the parameters, so that you can experiment yourself the different types of request.

So, now, let's see the basic operations of a UWS !

1. List jobs

To list all the jobs of a JobList you only have to select the web resource associated with the JobList. Here you just have to type in your browser the URL:

2. Create a job

To create a job you just need to send a HTTP-POST request to the JobList. No parameter is required, but if you want you can give one of the following:

• RUNID
• EXECUTIONDURATION
• DESTRUCTION
• one or several additional parameters
• PHASE=RUN (to start the job just after its creation)

The JobID must be generated automatically so that it can identify only one job in the whole jobs list.

Once created the response to the 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 (supposing the created job has the ID 12345). If the parameter PHASE has been given with the value RUN, the Job must start directly.

3. Get a job summary

As said previously UWS is a service based on REST. That means that any resource is available thanks to a URI build in a hierarchical manner. To get a job summary, you need to know the URL of the UWS, the name of the JobList and the ID of the job:

So you get the following URL: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345.

4. Change some job parameters

Some job parameters are writable. That means the client can change their value by sending a HTTP-POST request to the URL of the job parameter to change. The request must have exactly one parameter whose the key must be the name of the parameter to change. The response will always be a redirection to the job summary.

For example: To change the parameter Execution Duration you must send a request to http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345/executionduration with the parameter EXECUTIONDURATION=120 (for 120 seconds). The response will be a redirection to http://cdsportal.u-strasbg.fr/uwstuto/basic/timers/12345.

Additional parameters must be updated in a different way. A HTTP-POST request must be sent to the URI /{jobs}/(job-id)/parameters with one key-value pair which associates the name of the parameter and its value. An alternative is to send a HTTP-PUT request with the same parameter but at the following URI /{jobs}/(job-id)/parameters/{paramName}.

5. Start a job

Starting a job implies sending a HTTP-POST request to the job phase with the parameter PHASE=RUN. In this case the execution phase of the Job goes from PENDING to QUEUED when the server starts to execute the Job, and finally to EXECUTING when the execution finishes successfully.

6. Abort a job

Aborting a job implies sending a HTTP-POST request to the job phase with the parameter PHASE=ABORT. In this case the execution must finished and the execution phase must be set to ABORT.

7. Destroy a job

There are two possible ways to remove a job from a jobs list:

• by sending a HTTP-DELETE request to job resource
• by sending a HTTP-POST request with the parameter ACTION=DELETE to the job resource

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: http://cdsportal.u-strasbg.fr/uwstuto/basic/timers.

8. 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.