UWS 0.4

[Paul Harrison]

On 2008-06 -13, at 23:53, Patrick Dowler wrote:

> On 2008-6-13 15:15, Patrick Dowler wrote:
>> On 2008-6-6 02:22, Paul Harrison wrote:
>>> I have uploaded a new version (0.4) of the UWS document
>>
>> One more detail about the phase: the user can POST to the phase  
>> resource
>> with param PHASE=RUN  or PHASE=ABORT to switch to the EXECUTING or  
>> ABORTED
>> state respectively.
>
>> The values (RUN and ABORT) are verbs, which implies this is an  
>> ACTION. They
>> are definitely not the new states. I thought in REST that a POST  
>> was to
>> update/modify, in which case the value submitted should be the new  
>> state.
>> At least that way, the POST and GET would be symmetric and use the  
>> same
>> strings and fewer UWS constants would have to be defined.
>>
>> So it would seem that a POST of the new value would be nicer, eg
>> PHASE=EXECUTING or PHASE=ABORTED.
>
> OK, it's friday afternoon, I have a cold, and I am responding to  
> myself :-)
>
> Now that I have noticed the QUEUED phase and it is clear that RUN  
> can put the
> job into either the QUEUED or EXECUTING state. Still, I think  
> PHASE=RUN may
> not be so good.... how about ACTION=RUN since we really are  
> introducing a
> verb here. That at least follows POSTing ACTION=DELETE stylistically.
>
> In the SOAP bindings, there are methods like execute() and abort() and
> destroy()  (aka delete) rather than setPhase()....

On your first point - the intention is that the POST should be viewed  
as a *request* to change the state of the PHASE, so the verb form of  
the parameter value was chosen to try to indicate this, and as you say  
although the client might request that a job be run, the server is  
free to respond that the job is in the QUEUED state (from which it  
will automatically be put into the EXECUTING state), so it is not  
always appropriate that exactly the same value could be used to set  
the phase as would be seen when getting the phase.

The reason why the parameter key was chosen to be "phase" concerns one  
of the open questions that I had at the end of my talk in Trieste -  
namely whether it be legal to set the phase by posting to the job  
object itself as well as the currently specified job/phase object. If  
this were allowed then the key would have to indicate which object the  
action was for. However, I admit there is possibly some stylistic  
inconsistency here in the use of POST parameter keys over the various  
objects (eg. setting the destruction time). In general I think that I  
would favour having the key repeat the object name in all cases.

>
>
>> For a GET operation on phase(also applies to termination and  
>> destruction):
>> should the mimetype of the response be text/plain and just contain  
>> a simple
>> string (eg caller can just strip the whitspace and parse the  
>> value)? Or is
>> it in the same form/mimetype as the POST? eg does GET /joblist/job/ 
>> phase
>> return
>
> Doh! I completely skipped section 2.2.1.2 which says I need to be  
> able to send
> HTML (or XHTML) to clients that accept that and XML otherwise. I'll  
> blame it
> on the sinus medication :-)

Although the document might not make this explicit, the intention is  
that the "minimum" requirement is that a UWS service return XML for  
all of the job objects (excluding the individual results which may be  
returned in their "natural" mime type). I.e. MUST support the Accept:  
application/xml request header.

The preliminary schema attached to the document would have the phase  
returned as

<?xml version="1.0" encoding="UTF-8"?>
<uws:phase xmlns:uws="http://www.ivoa.net/xml/UWS/v0.9">COMPLETED</ 
uws:phase>

Additionally if the client indicates that it can accept html then the  
XHTML can be returned - as there is a strong desire to be able to  
drive these UWS from standard browsers. I am currently a little unsure  
how proscriptive we can attempt to be on the form that the XHTML  
takes, but I think it would be nice if we could find a way of  
guaranteeing that it works on as wide a range of browsers as possible  
- i.e. don't be too fancy with the HTML interface, and try to use  
browser specific features.

Cheers,
	Paul.