UWS POST PHASE=RUN

[Grégory Mantelet]

Dear UWS authors, users and implementors,

     Currently working on the new version of the UWS library, I would 
like to be sure that the way I get/read parameters in my library is 
correct and if not, jump on the occasion of this new release to make the 
appropriate corrections.

     Indeed, according to the UWS Recommendation 1.0 and the UWS draft 
for the version 1.1, parameters can be provided in several ways to a UWS 
service. These ways are for me, because of the possible desire to make 
them free, still partially unclear. So I will try in the following lines 
to summarise them as I have understood (and I apologise in advance for 
any eventual stupid question, but I need to be sure on the answers). I 
encourage anybody - and particularly UWS authors - to tell me where I am 
wrong, how it should really work and if I have forgotten something.

*A. When?*

It is possible to create parameters for a job only at its creation.
After creation, they may be modified, but never created, only if the 
PHASE "is not set the executing state".

_/My questions:/_/
//
     * Is a parameter modification possible if the phase is QUEUED? 
Since it is not an executing state, I would say that it is still 
possible, isn't it?//

//    * //I know it is stupid, but what about the phases COMPLETED, 
ERROR and ABORTED? I am sure it should not be possible, but they are 
neither an executing state...//so theoretically and according to the 
standard document, it would be possible to change parameters in those 
phases./

*B. How?*

     1. At the job creation

The only thing defined by the UWS standard is that parameters must be 
submitted in an HTTP POST request. No content-type is defined, which 
would be then totally free.

     2. After creation, but before the executing state

Here, no specific way or format is defined, but a good practice is 
recommended. It lets update parameters 1 by 1, by providing a name-value 
pair with one of the following methods:
     - HTTP POST with application/x-www-form-urlencoded to 
/{jobs}/{job-id} or /{jobs}/{job-id}/parameters
     - HTTP PUT with just the value to 
/{jobs}/{job-id}/parameters/{parameter-name}


For 1. and 2., it is said that it is possible to POST an XML document to 
create or update parameters. The structure/schema of this document is 
let free, as the content-type to use to submit it to the UWS service.

*C. XML representation*

A textual parameter must be represented like that in /{jobs}/{job-id}:
     <parameter id="{param-name}">{param-value}</parameter>

A non-textual parameter or at least a parameter value that can not be 
written legally in an XML document must be represented:
     <parameter id="{param-name}" byReference="true">{URL toward the 
param-value}</parameter>


_/My questions about B. and C.:/_/
//
//    * When an XML document is submitted as single parameter, how must 
it be stored in the UWS service: as one parameter (with 
byReference=true) or as some individual parameters which has been 
extracted from the XML document?//
//
//    * In the case where a submitted XML document must be stored as one 
parameter, what must be its name/id (the id which must be written in the 
"id" attribute of the XML node "parameter")?//Since it has been 
submitted alone, I presume that no name has been given, and so that one 
must be invented and associated to it by the UWS service. That method 
could work because it is not possible to create parameters after the job 
creation. Is it correct?
//
//    * Should it be possible to mix the usage of content-types? For 
instance, creating a job in POST multipart and updating parameters 
afterward with individual POST in ///application/x-www-form-urlencoded.///
//
//    * If the way to create or update parameters is such free that it 
allows even POSTing XML documents with no defined schema or structure to 
set them, why just XML documents are allowed? I am not at all in favor 
of having other kinds of document to set parameters, but I just wonder 
why allowing just XML documents while not defining its schema...I do not 
see the interest of fixing the MIME type without providing any clue to 
parse its content and use it smartly in the UWS service./

*D. PHASE=RUN*

This parameter name-value pair must be POSTed to /{jobs}/{job-id}/phase 
in order to start the specified job (going first through the QUEUED phase).
It may be possible to post it also at the initial POST in order to start 
the job immediately after its creation.

_/My question:/_/

//    * As has said Matthew, there is no content-type defined for this 
POST. So should there be one? I personally think that this special 
parameter, must always be submitted using 
//application/x-www-form-urlencoded//, when submitted after the job 
creation./

Cheers,
Grégory Mantelet


On 29.10.2014 19:45, Matthew Graham wrote:
> Hi,
>
> The current spec states:
>
>
>         2.2.3.5. Starting a Job
>
> A job may be started by POSTing to the /{jobs}/(job-id)/phase URI. The 
> POST contains a single parameter PHASE=RUN which instructs the UWS to 
> attempt to start the job. The response to this request must have code 
> 303 “See other” and the Location header of the response must point to 
> the /{jobs}/(job-id) URI so that the client receives the phase that 
> the job has been set to. Typically a UWS will put a job into a QUEUED 
> state on receipt of this command, but depending on how busy the server 
> is, the job might be put almost immediately (and without client 
> intervention) into an EXECUTING state.
>
> ---
>
> This makes no mention of any encoding required (i.e.,
>
> /application/x-www-form-urlencoded) /whereas other neighbouring 
> subsections do - is this an oversight?
>
>
> Cheers,
>
> Matthew

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/grid/attachments/20141030/e7305c0e/attachment.html>