| 1 |
<?xml version="1.0" encoding="ISO-8859-1"?><!-- $Id:$ |
| 2 |
Universal Worker Service WD |
| 3 |
Note that this file should be xhtml with div to mark sections so that it can be updated with xslt. |
| 4 |
Paul Harrison --><!-- DOCTYPE html |
| 5 |
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"--> |
| 6 |
<html xmlns="http://www.w3.org/1999/xhtml"> |
| 7 |
<head xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" profile="http://www.w3.org/1999/xhtml/vocab"><title>Universal Worker Service Specification</title><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/> |
| 8 |
<meta name="Title" content="IVOA WG Internal Draft"/> |
| 9 |
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/> |
| 10 |
<meta name="author" content="Paul Harrison, paul.harrison@manchester.ac.uk"/> |
| 11 |
<meta name="maintainedBy" content="Paul Harrison, paul.harrison@manchester.ac.uk"/> |
| 12 |
<link href="http://www.ivoa.net/misc/ivoa_a.css" rel="stylesheet" type="text/css"/> |
| 13 |
<link rel="stylesheet" href="http://www.ivoa.net/misc/ivoa_wd.css" type="text/css"/> |
| 14 |
<link href="./ivoadoc/XMLPrint.css" rel="stylesheet" type="text/css"/> |
| 15 |
<link href="./ivoadoc/ivoa-extras.css" rel="stylesheet" type="text/css"/> |
| 16 |
</head> |
| 17 |
<body bgcolor="#FFFFFF"> |
| 18 |
<div class="head"> |
| 19 |
<table><tr><td rowspan="1" colspan="1"><a href="http://www.ivoa.net/" shape="rect"><img alt="IVOA" src="http://www.ivoa.net/icons/ivoa_logo_small.jpg"/></a></td></tr></table> |
| 20 |
<h1>Universal Worker Service<br clear="none"/> |
| 21 |
Version 0.9</h1> |
| 22 |
<h2>IVOA Working Draft @RELEASEDATE@</h2> |
| 23 |
<dl><dt>Working Group</dt><dd><a href="http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices" shape="rect">http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices</a></dd><dt><b>This version:</b></dt><dd> 0.9</dd><dt><b>Latest version:</b></dt><dd> not issued outside |
| 24 |
GWS-WG</dd><dt><b>Previous version(s):</b></dt><dd> Internal Working Draft |
| 25 |
v0.1, 2005-01-24 |
| 26 |
Internal Working Draft |
| 27 |
v0.2, 2006-05-11 Internal |
| 28 |
Working Draft v.0.3, 2007-04-26 Internal |
| 29 |
Working Draft v.04 2008-05-10, Internal Working draft 0.5 </dd><dt><b>Author(s):</b></dt><dd> P. |
| 30 |
Harrison, G. Rixon</dd> |
| 31 |
</dl> |
| 32 |
|
| 33 |
<h2>Abstract</h2> |
| 34 |
<p>The Universal Worker Service pattern |
| 35 |
(UWS) defines how to manage asynchronous execution of jobs on a |
| 36 |
service. Any application of the pattern defines a family of related |
| 37 |
services with a common service contract. Four possible applications |
| 38 |
are described.</p> |
| 39 |
<h2> Status of This Document</h2> |
| 40 |
<p>This is an working draft of |
| 41 |
the GWS-WG. The first release of this document was on 2005-01-24 |
| 42 |
within the working group; This version is the first public WD.</p> |
| 43 |
<p><em>This |
| 44 |
is an IVOA Working Draft for review by IVOA members and other |
| 45 |
interested parties. It is a draft document and may be updated, |
| 46 |
replaced, or made obsolete by other documents at any time. It is |
| 47 |
inappropriate to use IVOA Working Drafts as reference materials or to |
| 48 |
cite them as other than “work in progress”.</em></p> |
| 49 |
<p> <em>A list of </em><span style="background: transparent"><a href="http://www.ivoa.net/Documents/" shape="rect"><i>current |
| 50 |
IVOA Recommendations and other technical documents</i></a></span><em> can be found at http://www.ivoa.net/Documents/.</em></p> |
| 51 |
<h2 class="prologue-heading-western">Acknowledgements</h2> |
| 52 |
<p>The need for the UWS pattern was |
| 53 |
inspired by AstroGrid’s Common Execution Architecture and |
| 54 |
particularly by discussions with Noel Winstanley. The ideas about |
| 55 |
statefulness are distilled from debates in the Global Grid Forum in |
| 56 |
respect of the Open Grid Services Infrastructure that was the |
| 57 |
fore-runner of Web Services Resource Framework. The REST binding came |
| 58 |
initially from suggestions by Norman Gray.</p> |
| 59 |
</div> |
| 60 |
<h2>Contents</h2> |
| 61 |
<div><copy xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/"><div id="toc" class="toc"><ul><li><a href="#Introduction"><span class="secnum">1. </span>Introduction</a><ul><li><a href="#SynchronousStateless"><span class="secnum">1.1. </span> Synchronous, stateless services</a></li><li><a href="#IVOOutGrow"><span class="secnum">1.2. </span> Some IVO activities that outgrow synchronous, stateless services</a></li><li><a href="#AsynchronousServices"><span class="secnum">1.3. </span> Asynchronous and stateful services</a></li><li><a href="#JDL"><span class="secnum">1.4. </span> Job description language, service contracts and universality</a></li></ul></li><li><a href="#UWSpattern"><span class="secnum">2. </span> Universal Worker Service Pattern</a><ul><li><a href="#UWSObjects"><span class="secnum">2.1. </span> Objects within a UWS</a><ul><li><a href="#Joblist"><span class="secnum">2.1.1. </span> |
| 62 |
Job list </a></li><li><a href="#Job"><span class="secnum">2.1.2. </span>Job</a></li><li><a href="#ExecutionPhase"><span class="secnum">2.1.3. </span> Execution Phase</a></li><li><a href="#ExecutionDuration"><span class="secnum">2.1.4. </span> Execution Duration</a></li><li><a href="#DestructionTime"><span class="secnum">2.1.5. </span> Destruction Time</a></li><li><a href="#Quote"><span class="secnum">2.1.6. </span>Quote</a></li><li><a href="#Error"><span class="secnum">2.1.7. </span>Error</a></li><li><a href="#Error2"><span class="secnum">2.1.8. </span>Owner</a></li><li><a href="#Error3"><span class="secnum">2.1.9. </span>RunId</a></li><li><a href="#ResultsList"><span class="secnum">2.1.10. </span>Results List</a></li><li><a href="#ResultsList2"><span class="secnum">2.1.11. </span>Parameter List</a></li></ul></li><li><a href="#RESTbinding"><span class="secnum">2.2. </span>The REST Binding</a><ul><li><a href="#d1e834"><span class="secnum">2.2.1. </span>Resources and URIs</a></li><li><a href="#d1e603"><span class="secnum">2.2.2. </span>Representations of resources</a><ul><li><a href="#d1e1030"><span class="secnum">2.2.2.1. </span>Job List</a></li><li><a href="#d1e1040"><span class="secnum">2.2.2.2. </span>Job</a></li><li><a href="#d1e1344"><span class="secnum">2.2.2.3. </span>Results List</a></li><li><a href="#d1e1353"><span class="secnum">2.2.2.4. </span>Parameters List</a></li></ul></li><li><a href="#d1e634"><span class="secnum">2.2.3. </span>State changing requests</a><ul><li><a href="#d1e1375"><span class="secnum">2.2.3.1. </span>Creating a Job</a></li><li><a href="#d1e1390"><span class="secnum">2.2.3.2. </span>Deleting a Job</a></li><li><a href="#d1e1402"><span class="secnum">2.2.3.3. </span>Changing the Destruction |
| 63 |
Time</a></li><li><a href="#d1e1420"><span class="secnum">2.2.3.4. </span>Changing the Execution |
| 64 |
Duration</a></li><li><a href="#d1e1439"><span class="secnum">2.2.3.5. </span> Starting a Job</a></li><li><a href="#d1e1448"><span class="secnum">2.2.3.6. </span>Aborting a Job</a></li></ul></li><li><a href="#d1e708"><span class="secnum">2.2.4. </span>Message pattern</a></li></ul></li></ul></li><li><a href="#security"><span class="secnum">3. </span>Security Considerations</a></li><li><a href="#ApplicationsOfUWS"><span class="secnum">4. </span> Applications of UWS (informative)</a><ul><li><a href="#Imageservice"><span class="secnum">4.1. </span> Image service with data staging</a></li><li><a href="#ADQLservice"><span class="secnum">4.2. </span> ADQL service with cursor</a></li><li><a href="#ParameterizedApplications"><span class="secnum">4.3. </span> Parameterized applications</a></li></ul></li><li><a href="#SynchronousService"><span class="secnum">5. </span> Implementing a Synchronous Service on top of UWS (informative)</a></li><li><a href="#Updates"><span class="secnum">Appendix A. </span> Updates from previous versions</a><ul><li><a href="#d1e1112"><span class="secnum">Appendix A.1. </span>At Version 0.5</a></li><li><a href="#d1e1775"><span class="secnum">Appendix A.2. </span>At Version 1.0</a></li></ul></li><li><a href="#UWSSchema"><span class="secnum">Appendix B. </span> UWS Schema</a></li></ul></div></copy></div> |
| 65 |
<div class="body"> |
| 66 |
<div class="section"><h2><a name="Introduction" id="Introduction" shape="rect"/><span class="secnum">1. </span>Introduction</h2> |
| 67 |
<p>The Universal Worker Service (UWS) |
| 68 |
pattern defines how to build <i>asynchronous</i>, <i>stateful</i>, <i>job-oriented</i> services<i> </i>(the italicized terms are defined |
| 69 |
in sub-sections of this introduction). It does so in a way that |
| 70 |
allows for wide-scale reuse of software and support from software |
| 71 |
toolkits.</p> |
| 72 |
<p>Section <h:span xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="xref"><a href="#UWSpattern">2. </a></h:span> of this document describes |
| 73 |
the pattern and lists the aspects that are common to all its |
| 74 |
applications. Any such application would involve a service contract |
| 75 |
that embodies the pattern and fixes the issues left undefined in the |
| 76 |
pattern itself. The contract would include the XML schemata (XSD and |
| 77 |
WSDL) for the application. It is intended that each such contract |
| 78 |
cover a family of related applications, such that the implementations |
| 79 |
may be widely reused.</p> |
| 80 |
<p>Section 3 outlines several possible |
| 81 |
applications of the pattern. These use-cases may be expanded into |
| 82 |
full IVOA standards that are siblings of the current document.</p> |
| 83 |
<p>Section 4 describes the preferred |
| 84 |
method of creating a synchronous facade to a UWS system.</p> |
| 85 |
<div class="section"><h3><a name="SynchronousStateless" id="SynchronousStateless" shape="rect"/><span class="secnum">1.1. </span> Synchronous, stateless services</h3> |
| 86 |
<p>Simple web services are <i>synchronous</i> and <i>stateless</i>. Synchronous means that the client waits for |
| 87 |
each request to be fulfilled; if the client disconnects from the |
| 88 |
service then the activity is abandoned. <i>Stateless</i> means that |
| 89 |
the service does not remember results of a previous activity (or, at |
| 90 |
least, the client cannot ask the service about them).</p> |
| 91 |
<p>Synchronous, stateless services work |
| 92 |
well when two criteria apply.</p> |
| 93 |
<ol><li> |
| 94 |
<p>The length of each activity is |
| 95 |
less than the “attention span” of the connection.</p> |
| 96 |
</li><li> |
| 97 |
<p>The results of each activity are |
| 98 |
compact enough to be easily passed back to the client via the |
| 99 |
connection on which the request was made (and possibly pushed back |
| 100 |
to the service as parameters of the next activity).</p> |
| 101 |
</li></ol> |
| 102 |
<p>There are various limits to the |
| 103 |
attention span.</p> |
| 104 |
<ul><li> |
| 105 |
<p>HTTP assumes that the start of a |
| 106 |
reply quickly follows its request, even if the body of the reply |
| 107 |
takes a long time to stream. If the service takes too long to |
| 108 |
compute the results and to start the reply, then HTTP times out at |
| 109 |
the request is lost.</p> |
| 110 |
</li><li> |
| 111 |
<p>A client runs computer which |
| 112 |
will not stay on-line indefinitely.</p> |
| 113 |
</li><li> |
| 114 |
<p>A network with finite |
| 115 |
reliability will eventually break communications during an activity.</p> |
| 116 |
</li><li> |
| 117 |
<p>A service is sometimes shut down |
| 118 |
for maintenance.</p> |
| 119 |
</li></ul> |
| 120 |
<p>Synchronous, stateless services, in |
| 121 |
short, do not scale well.</p> |
| 122 |
</div> |
| 123 |
<div class="section"><h3><a name="IVOOutGrow" id="IVOOutGrow" shape="rect"/><span class="secnum">1.2. </span> Some IVO activities that outgrow synchronous, stateless services</h3> |
| 124 |
<p>These cases are examples. They are |
| 125 |
not a complete list!</p> |
| 126 |
<ol><li> |
| 127 |
<p>An ADQL <cite> |
| 128 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:std:adql">std:adql</a>] |
| 129 |
</cite> service gives access |
| 130 |
to a large object-catalogue. Most queries run in less than a minute, |
| 131 |
but some legitimate queries involve a full-table traverse and take |
| 132 |
hours or days. The service needs to run these special cases in a |
| 133 |
low-priority queue.</p> |
| 134 |
</li><li> |
| 135 |
<p>An object-finding service runs |
| 136 |
the SExtractor <cite> |
| 137 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:sextractor">sextractor</a>] |
| 138 |
</cite> application on a list of images. Normally, the list |
| 139 |
is short and the request is quickly satisfied. Occasionally, a list |
| 140 |
of 10,000 images is sent in the expectation that the work will be |
| 141 |
finished over the weekend.</p> |
| 142 |
</li><li> |
| 143 |
<p>A cone-search <cite> |
| 144 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:std:scs">std:scs</a>] |
| 145 |
</cite> request on a |
| 146 |
rich catalogue raises 10,000,000 rows of results, but the client is |
| 147 |
connected via a slow link and cannot read all the results in a |
| 148 |
reasonable time. The client needs the service to send the results |
| 149 |
into storage over a faster link. This could mean sending them to |
| 150 |
VOSpace, or simply holding them temporarily until the user can |
| 151 |
retrieve them on a fast link.</p> |
| 152 |
</li><li> |
| 153 |
<p>An ADQL service allows users to |
| 154 |
save query results into new tables such that they can be the target |
| 155 |
of later queries. However, space is limited and the results tables |
| 156 |
can only be kept for a short time. The client and service negotiate |
| 157 |
the lifetime of the results tables.</p> |
| 158 |
</li><li> |
| 159 |
<p>A service performs image |
| 160 |
stacking on a list of fields. Each field can be processed by a |
| 161 |
synchronous service but the list is long and the user wants to |
| 162 |
retrieve the results of the early fields before the last fields are |
| 163 |
processed.</p> |
| 164 |
</li></ol> |
| 165 |
</div> |
| 166 |
<div class="section"><h3><a name="AsynchronousServices" id="AsynchronousServices" shape="rect"/><span class="secnum">1.3. </span> Asynchronous and stateful services</h3> |
| 167 |
<p>Services can be made to scale better |
| 168 |
by making them <i>asynchronous</i> and <i>stateful</i>. Asynchronous |
| 169 |
means that a client makes two or more separate requests to the |
| 170 |
service in the course of one activity, and that the client and |
| 171 |
service may be disconnected, possibly for days or more, in between |
| 172 |
those requests. Stateful means that the service stores state |
| 173 |
information about the activity and the client addresses requests to |
| 174 |
this state.</p> |
| 175 |
<p>Web services that are asynchronous |
| 176 |
are almost always stateful. Most of special extra arrangements for |
| 177 |
asynchronous activities are actually managing the state of the |
| 178 |
activity.</p> |
| 179 |
<p>There is an important class of |
| 180 |
stateful services where the state is peculiar to one job or session |
| 181 |
and the job is “owned” by one user. These, for the purpose of |
| 182 |
this document, are called <i>job-oriented</i> services. There are |
| 183 |
stateful services that are not job-oriented (e.g. a service managing |
| 184 |
a shared, client-writeable DB table), but UWS does not apply to |
| 185 |
these.</p> |
| 186 |
<p>For the purpose of this discussion, |
| 187 |
let the term <i>job</i> refer to the work specified by the JDL |
| 188 |
instructions and the term <i>resource</i> refer to the state of the |
| 189 |
job as recorded by the service. Both have a finite duration. The <i>lifetime</i> of the resource – i.e. the time from inception |
| 190 |
until the service forgets the state – is generally finite and must |
| 191 |
be at least as long the duration of the job.</p> |
| 192 |
</div> |
| 193 |
<div class="section"><h3><a name="JDL" id="JDL" shape="rect"/><span class="secnum">1.4. </span> Job description language, service contracts and universality</h3> |
| 194 |
<p>Consider the web-service operation |
| 195 |
that starts off a job. This operation must express what is to be done |
| 196 |
in the activity: it must carry parameters in some form.</p> |
| 197 |
<p>The parameters may be expressed as a |
| 198 |
list. E.g., a cone search service takes a list of three parameters: |
| 199 |
RA, DEC, RADIUS. Alternatively, the parameters may be arranged as an |
| 200 |
XML document (e.g. ADQL, CEA). The rules for setting and arranging |
| 201 |
the parameters for a job are called the<i> Job-Description Language </i>(JDL).</p> |
| 202 |
<p>The combination of the UWS pattern, a |
| 203 |
JDL and details of the job state visible to the client defines a |
| 204 |
service contract; for a SOAP service, this contract can be captured |
| 205 |
in WSDL. Changing the JDL changes the contract. Thus, it is not |
| 206 |
meaningful to “implement UWS” in isolation; any implementation |
| 207 |
standard must specify the rest of the contract.</p> |
| 208 |
<p>If the JDL is very general, a single |
| 209 |
service-contract can be reused for many kinds of service. AstroGrid’s |
| 210 |
CEA <cite> |
| 211 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:harrison05">harrison05</a>] |
| 212 |
</cite>exploits this: one JDL covers all services offering parameterized |
| 213 |
applications and even ADQL services. In the limit, a |
| 214 |
sufficiently-general JDL turns a specialized worker service into a |
| 215 |
universal worker service.</p> |
| 216 |
</div> |
| 217 |
</div> |
| 218 |
<div class="section"><h2><a name="UWSpattern" id="UWSpattern" shape="rect"/><span class="secnum">2. </span> Universal Worker Service Pattern</h2> |
| 219 |
<div class="section"><h3><a name="UWSObjects" id="UWSObjects" shape="rect"/><span class="secnum">2.1. </span> Objects within a UWS</h3> |
| 220 |
<p>A UWS consists logically in a set of |
| 221 |
objects that may be read and written to in order to control jobs.</p> |
| 222 |
<p>In a SOAP binding of UWS, these |
| 223 |
components are exposed as properties of the object that lives at the |
| 224 |
endpoint registered for the service. In a REST binding, the |
| 225 |
components are distinct web-resources each with its own URI.</p> |
| 226 |
<p> The following sub-sections explain the semantics of the objects. The |
| 227 |
UML diagram below shows the relationships more succinctly.</p> |
| 228 |
<p><img src="Class_Diagram__UWS__UWSObjects.png" alt="UWS Objects Class Diagram" name="graphics2" width="460" height="390" border="0" align="top" id="graphics2"/></p> |
| 229 |
<div class="section"><h4><a name="Joblist" id="Joblist" shape="rect"/><span class="secnum">2.1.1. </span> |
| 230 |
Job list </h4> |
| 231 |
<p>The Job List is the outermost object: |
| 232 |
it contains all the other objects in the UWS. The immediate children |
| 233 |
of the job list are Job objects (see next sub-section).</p> |
| 234 |
<p>The job list may be read to find the |
| 235 |
extant jobs.</p> |
| 236 |
<p>The job list may be updated to add a |
| 237 |
new job.</p> |
| 238 |
<p>The job list itself does not allow |
| 239 |
jobs to be deleted. Instead, when a job is destroyed by an action on |
| 240 |
its job object, then the list updates itself accordingly.</p> |
| 241 |
</div> |
| 242 |
<div class="section"><h4><a name="Job" id="Job" shape="rect"/><span class="secnum">2.1.2. </span>Job</h4> |
| 243 |
<p>A Job object contains the state of |
| 244 |
one job. The state is a collection of other objects. Each Job |
| 245 |
aggregates</p> |
| 246 |
<ul><li> |
| 247 |
<p>Exactly one Execution Phase.</p> |
| 248 |
</li><li> |
| 249 |
<p>Exactly one Execution Duration.</p> |
| 250 |
</li><li> |
| 251 |
<p>Exactly one Deletion Time</p> |
| 252 |
</li><li> |
| 253 |
<p>Exactly one Quote.</p> |
| 254 |
</li><li> |
| 255 |
<p>Exactly one Results List.</p> |
| 256 |
</li><li> |
| 257 |
<p>Zero or one Error.</p> |
| 258 |
</li></ul> |
| 259 |
</div> |
| 260 |
<div class="section"><h4><a name="ExecutionPhase" id="ExecutionPhase" shape="rect"/><span class="secnum">2.1.3. </span> Execution Phase</h4> |
| 261 |
<p>The job is treated as a state machine |
| 262 |
with the Execution Phase naming the state. The phases are;</p> |
| 263 |
<ul><li> |
| 264 |
<p>PENDING: the job is accepted by |
| 265 |
the service but not yet committed for execution by the client. In |
| 266 |
this state, the job quote can be read and evaluated. This is the |
| 267 |
state into which a job enters when it is first created.</p> |
| 268 |
</li><li> |
| 269 |
<p>QUEUED: the job is committed for |
| 270 |
execution by the client but the service has not yet assigned it to a |
| 271 |
processor. No Results are produced in this phase.</p> |
| 272 |
</li><li> |
| 273 |
<p>EXECUTING: the job has been |
| 274 |
assigned to a processor. Results may be produced at any time during |
| 275 |
this phase.</p> |
| 276 |
</li><li> |
| 277 |
<p>COMPLETED: the execution of the |
| 278 |
job is over. The Results may be collected.</p> |
| 279 |
</li><li> |
| 280 |
<p>ERROR: the job failed to |
| 281 |
complete. No further work will be done nor Results produced. Results |
| 282 |
may be unavailable or available but invalid; either way the Results |
| 283 |
should not be trusted.</p> |
| 284 |
</li><li> |
| 285 |
<p>ABORTED: the job has been |
| 286 |
manually aborted by the user, or the system has aborted the job due |
| 287 |
to lack of or overuse of resources.</p> |
| 288 |
</li></ul> |
| 289 |
</div> |
| 290 |
<div class="section"><h4><a name="ExecutionDuration" id="ExecutionDuration" shape="rect"/><span class="secnum">2.1.4. </span> Execution Duration</h4> |
| 291 |
<p>An Execution Duration object defines |
| 292 |
the duration for which a job shall run. This represents the |
| 293 |
“computation time” that a job is to be allowed, although because |
| 294 |
a specific measure of CPU time may not be available in all |
| 295 |
environments, this duration is defined in real clock seconds. An |
| 296 |
execution duration of 0 implies unlimited execution duration.</p> |
| 297 |
<p>When the execution duration has been |
| 298 |
exceeded the service will automatically abort the job, which has the |
| 299 |
same effect as when a manual “Abort” is requested.</p> |
| 300 |
<p>Specifically, when a job is aborted:</p> |
| 301 |
<ul><li> |
| 302 |
<p>if the job is still executing, |
| 303 |
the execution is aborted.</p> |
| 304 |
</li><li> |
| 305 |
<p>any previously generated results |
| 306 |
of the job are retained.</p> |
| 307 |
</li></ul> |
| 308 |
<p>When a job is created, the service |
| 309 |
sets the initial execution duration. The client may write to an |
| 310 |
Execution Duration to try to change the job's cpu time allocation. |
| 311 |
The service may forbid changes, or may set limits on the allowed |
| 312 |
execution duration.</p> |
| 313 |
</div> |
| 314 |
<div class="section"><h4><a name="DestructionTime" id="DestructionTime" shape="rect"/><span class="secnum">2.1.5. </span> Destruction Time</h4> |
| 315 |
<p>The Destruction Time object |
| 316 |
represents the instant when the job shall be destroyed. The |
| 317 |
Destruction Time is an absolute time.</p> |
| 318 |
<p>Destroying a job implies;</p> |
| 319 |
<ul><li> |
| 320 |
<p>if the job is still executing, |
| 321 |
the execution is aborted.</p> |
| 322 |
</li><li> |
| 323 |
<p>any results from the job are |
| 324 |
destroyed and storage reclaimed.</p> |
| 325 |
</li> |
| 326 |
<li> |
| 327 |
<p>the service forgets that |
| 328 |
the job existed.</p> |
| 329 |
</li></ul> |
| 330 |
<p>The Destruction Time may be viewed as |
| 331 |
a measure of the amount of time that a service is prepared to |
| 332 |
allocate storage for a job – typically this will be a longer |
| 333 |
duration that the amount of CPU time that a service would allocate.</p> |
| 334 |
<p>When a job is created the service |
| 335 |
sets the initial Destruction Time. The client may write to the |
| 336 |
Destruction Time to try to change the life expectancy of the job. The |
| 337 |
service may forbid changes, or may set limits on the allowed |
| 338 |
destruction time.</p> |
| 339 |
</div> |
| 340 |
<div class="section"><h4><a name="Quote" id="Quote" shape="rect"/><span class="secnum">2.1.6. </span>Quote</h4> |
| 341 |
<p>A Quote object predicts when the job |
| 342 |
is likely to complete. The intention is that a client creates the |
| 343 |
same job on several services, compares the quotes and then accepts |
| 344 |
the best quote.</p> |
| 345 |
<p>Quoting for a computational job is |
| 346 |
notoriously difficult. A UWS implementation must always provide a |
| 347 |
quote object, in order that the two-phase committal of jobs be |
| 348 |
uniform across all UWS, but it may supply a “don't know” answer |
| 349 |
for the completion time.</p> |
| 350 |
</div> |
| 351 |
<div class="section"><h4><a name="Error" id="Error" shape="rect"/><span class="secnum">2.1.7. </span>Error</h4> |
| 352 |
<p>The error object gives a human |
| 353 |
readable error message (if any) for the underlying job. This object |
| 354 |
is intended to be a detailed error message, and consequently might be |
| 355 |
a large piece of text such as a stack trace. When there is an error |
| 356 |
running a job a summary of the error should be given using the |
| 357 |
optional errorSummary element of the JobSummary type.</p> |
| 358 |
</div> |
| 359 |
<div class="section"><h4><a name="Error" id="Error2" shape="rect"/><span class="secnum">2.1.8. </span>Owner</h4> |
| 360 |
<p>The owner object represents the identifier for the creator of the job. This object will not exist for all invocations of a UWS conformant protocol, but only in cases where the access to the service is authenticated as discussed more thoroughly in <h:span xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="xref"><a href="#security">3. </a></h:span>. </p> |
| 361 |
</div> |
| 362 |
<div class="section"><h4><a name="Error" id="Error3" shape="rect"/><span class="secnum">2.1.9. </span>RunId</h4> |
| 363 |
<p>The RunId object represents an identifier that the job creator uses to identify the job. Note that this is distinct from the Job Identifier that the UWS system itself assigns to each job. The UWS system should do no parsing or processing of the RunId, but merely pass back the value (if it exists) as it was passed to the UWS at job creation time. In particular it may be the case that multiple jobs have the same RunId, as this is a mechanism by which the calling process can identifiy jobs that belong to a particular group. The exact mechanism of setting the RunId is not specified here, but will be part of the specification of the protocol using the UWS pattern.</p> |
| 364 |
</div> |
| 365 |
<div class="section"><h4><a name="ResultsList" id="ResultsList" shape="rect"/><span class="secnum">2.1.10. </span>Results List</h4> |
| 366 |
<p>The Results List object is a |
| 367 |
container for formal results of the job. Its children may be any |
| 368 |
objects resulting from the computation that may be fetched from the |
| 369 |
service when the job has completed.</p> |
| 370 |
<p>Reading the Results List itself |
| 371 |
enumerates the available or expected result objects.</p> |
| 372 |
<p>The children of the Results List may |
| 373 |
be read but not updated or deleted. The client may not add anything |
| 374 |
to the Results List.</p> |
| 375 |
</div> |
| 376 |
<div class="section"><h4><a name="ResultsList" id="ResultsList2" shape="rect"/><span class="secnum">2.1.11. </span>Parameter List</h4> |
| 377 |
<p>The Parameter List</p> |
| 378 |
<p>Reading the Results List itself |
| 379 |
enumerates the available or expected result objects.</p> |
| 380 |
<p>A particular imlementation of UWS may choose to allow the parameters to be updated after the initial job creation step, before the Phase is set to the executing state. It is up to the individual implementation to specify exactly how these parameters may be updated, but good practice would be to choose one of the following options.</p> |
| 381 |
<ol> |
| 382 |
<li>HTTP POST an <i>application/x-www-form-urlencoded</i><b> </b>parameter name, value pair to either |
| 383 |
<ol> |
| 384 |
<li>/{jobs}/{job-id)</li> |
| 385 |
<li>/{jobs}/{job-id)/parameters</li> |
| 386 |
</ol> |
| 387 |
</li> |
| 388 |
<li>HTTP PUT the parameter value to /{jobs}/{job-id)/parameters/(parameter-name)</li> |
| 389 |
</ol> |
| 390 |
</div> |
| 391 |
</div> |
| 392 |
<div class="section"><h3><a name="RESTbinding" id="RESTbinding" shape="rect"/><span class="secnum">2.2. </span>The REST Binding</h3> |
| 393 |
<p>In order to create a usable service the objects discussed in the section above must be exposed in a particular interface which can be addressed over a particular transport mechanism - this combination is known as a "binding". In this first version of the UWS pattern only a REST (Representational State |
| 394 |
Transfer) binding <cite> |
| 395 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:fielding00">fielding00</a>] |
| 396 |
</cite>is presented, however, future versions of this document will add other bindings such as SOAP. <cite> |
| 397 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:std:soap">std:soap</a>] |
| 398 |
</cite></p> |
| 399 |
|
| 400 |
<div class="section"><h4><a name="d1e834"/><span class="secnum">2.2.1. </span>Resources and URIs</h4> |
| 401 |
<p>In a REST (Representational State |
| 402 |
Transfer) binding of UWS, each of the objects defined above is |
| 403 |
available as a web resource with its own URI. These URIs must form a |
| 404 |
hierarchy as shown in the rable below:</p> |
| 405 |
<table border="1" cellpadding="2" cellspacing="0"> |
| 406 |
<tr> |
| 407 |
<th scope="col">URI</th> |
| 408 |
<th scope="col">Description</th> |
| 409 |
<th scope="col">Representation</th> |
| 410 |
</tr> |
| 411 |
<tr> |
| 412 |
<td>/{jobs}</td> |
| 413 |
<td>the Job List</td> |
| 414 |
<td> the <span class="xmlelement"><jobs></span> element in the UWS schema</td> |
| 415 |
</tr> |
| 416 |
<tr> |
| 417 |
<td>/{jobs}/(job-id)</td> |
| 418 |
<td>a Job</td> |
| 419 |
<td><p>the <span class="xmlelement"><job></span> element in the UWS schema<br/> |
| 420 |
</p></td> |
| 421 |
</tr> |
| 422 |
<tr> |
| 423 |
<td>/{jobs}/(job-id)/phase</td> |
| 424 |
<td> the Phase of job |
| 425 |
(job-id)</td> |
| 426 |
<td>one of the fixed strings</td> |
| 427 |
</tr> |
| 428 |
<tr> |
| 429 |
<td>/{jobs}/(job-id)/executionduration</td> |
| 430 |
<td>the |
| 431 |
maximum execution duration of (job-id)</td> |
| 432 |
<td>Integer number of seconds</td> |
| 433 |
</tr> |
| 434 |
<tr> |
| 435 |
<td>/{jobs}/(job-id)/destruction</td> |
| 436 |
<td> the |
| 437 |
destruction instant for (job-id)</td> |
| 438 |
<td><cite> |
| 439 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:std:iso8601">std:iso8601</a>] |
| 440 |
</cite></td> |
| 441 |
</tr> |
| 442 |
<tr> |
| 443 |
<td>/{jobs}/(job-id)/error</td> |
| 444 |
<td>any error |
| 445 |
message associated with (job-id)</td> |
| 446 |
<td>any representation appropriate to the implementing service</td> |
| 447 |
</tr> |
| 448 |
<tr> |
| 449 |
<td>/{jobs}/(job-id)/quote </td> |
| 450 |
<td>the Quote for |
| 451 |
(job-id)</td> |
| 452 |
<td>Integer number of seconds</td> |
| 453 |
</tr> |
| 454 |
<tr> |
| 455 |
<td>/{jobs}/(job-id)/results</td> |
| 456 |
<td>any parameters for the job |
| 457 |
(job-id)</td> |
| 458 |
<td>the <span class="xmlelement"><results></span> element in the UWS schema</td> |
| 459 |
</tr> |
| 460 |
<tr> |
| 461 |
<td>/{jobs}/(job-id)/parameters</td> |
| 462 |
<td>any parameters for the job |
| 463 |
(job-id)</td> |
| 464 |
<td>the <span class="xmlelement"><parameters></span> element in the UWS schema</td> |
| 465 |
</tr> |
| 466 |
<tr> |
| 467 |
<td>/{jobs}/(job-id)/owner</td> |
| 468 |
<td>the owner of the job (job-id)</td> |
| 469 |
<td>and appropriate identifier as discussed in <h:span xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="xref"><a href="#security">3. </a></h:span></td> |
| 470 |
</tr> |
| 471 |
</table> |
| 472 |
<p>The service implementor is free to |
| 473 |
choose the names given in parentheses above, i.e. the root of the URI tree, and the form that the job identifider takes (though note that it should be a legal URI path element) - the other names are part |
| 474 |
of the UWS standard.</p> |
| 475 |
<p>The URI for the Job List, in its |
| 476 |
absolute form is the root URI for the whole UWS. This URI should be |
| 477 |
given as the access URL in the UWS registration.</p> |
| 478 |
</div> |
| 479 |
<div class="section"><h4><a name="d1e603" id="d1e603" shape="rect"/><span class="secnum">2.2.2. </span>Representations of resources</h4> |
| 480 |
<p>For each of the resources HTTP GET |
| 481 |
fetches a representation. In general where an object is a container for other objects then an XML representation of the object is returned, otherwise for simple atomic types a textual representation is returned. The XML schema for the various objects described above is |
| 482 |
detailed in <h:span xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="xref"><a href="#UWSSchema">Appendix B. </a></h:span> of this specification. This schema is the definitive description of the exact form of the XML returned by a UWS and should not vary between implementations.</p> |
| 483 |
<p>HTTP allows multiple representations |
| 484 |
of a resource distinguished by their MIME types and selected by the |
| 485 |
HTTP "Accept" headers of a GET request. UWS exploits this to support both web |
| 486 |
browsers and rich clients in the same tree of resources. Although the default behaviour is to return XML, a UWS should return HTML or XHTML to |
| 487 |
clients that accept these types. These clients are assumed to be web |
| 488 |
browsers and the UWS is generating its own user interface. The HTML |
| 489 |
interface generated should allow full control of the UWS via the use |
| 490 |
of HTML forms and appropriate links.</p> |
| 491 |
<p>Clients which are assumed to be part |
| 492 |
of remote applications that drive UWS without showing the details to |
| 493 |
their users should accept only "application/xml". A UWS must therefore |
| 494 |
return XML representations of the resources in preference to the HTML representation. A technique that may be used to always return XML that modern browsers can transform on the client-side to HTML is via the <span class="xmlelement"><?xml-stylesheet ?></span> processing instruction, which can be used to point to a suitable XSL resource to perform the transformation.</p> |
| 495 |
<p> More detail for some of the UWS objects is provided below;</p> |
| 496 |
<div class="section"><h4><a name="d1e1030"/><span class="secnum">2.2.2.1. </span>Job List</h4> |
| 497 |
<p>The representation of the Job List is |
| 498 |
a list of links to extant jobs. The list may be empty if the UWS is |
| 499 |
idle.</p> |
| 500 |
</div> |
| 501 |
<div class="section"><h4><a name="d1e1040"/><span class="secnum">2.2.2.2. </span>Job</h4> |
| 502 |
<p>The representation of a Job is as specified by the <span class="xmlelement"><job></span> element in the UWS schema as detailed in <h:span xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="xref"><a href="#UWSSchema, "/></h:span>an example or such a job instance is shown below</p> |
| 503 |
<div><?incxml href="../UWSJobInstance.xml" ?><div xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="viewxml"><div class="element"><span class="markup"><</span><span class="start-tag">uws:job</span> <span class="attribute-name">xsi:schemaLocation</span><span class="markup">=</span><span class="attribute-value">"http://www.ivoa.net/xml/UWS/v1.0rc3 UWS.xsd "</span> <span class="attribute-name">xlmns:xml</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/XML/1998/namespace"</span> <span class="attribute-name">xlmns:uws</span><span class="markup">=</span><span class="attribute-value">"http://www.ivoa.net/xml/UWS/v1.0rc3"</span> <span class="attribute-name">xlmns:xlink</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/1999/xlink"</span> <span class="attribute-name">xlmns:xsi</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/2001/XMLSchema-instance"</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">uws:jobId</span><span class="markup">></span><span class="text">cea-agdevel.jb.man.ac.uk-130.88.24.18-1242749568029-508182314</span><span class="markup"></</span><span class="end-tag">uws:jobId</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">uws:ownerId</span> <span class="attribute-name">xsi:nil</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">/></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">uws:phase</span><span class="markup">></span><span class="text">COMPLETED</span><span class="markup"></</span><span class="end-tag">uws:phase</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">uws:startTime</span><span class="markup">></span><span class="text">2009-05-19T17:12:48.038+01:00</span><span class="markup"></</span><span class="end-tag">uws:startTime</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">uws:endTime</span><span class="markup">></span><span class="text">2009-05-19T17:12:48.041+01:00</span><span class="markup"></</span><span class="end-tag">uws:endTime</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">uws:executionDuration</span><span class="markup">></span><span class="text">86400</span><span class="markup"></</span><span class="end-tag">uws:executionDuration</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">uws:destruction</span><span class="markup">></span><span class="text">2009-05-29T17:12:48.035+01:00</span><span class="markup"></</span><span class="end-tag">uws:destruction</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">uws:parameters</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">uws:parameter</span> <span class="attribute-name">id</span><span class="markup">=</span><span class="attribute-value">"scaleFactor"</span><span class="markup">></span><span class="text">1.8</span><span class="markup"></</span><span class="end-tag">uws:parameter</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">uws:parameter</span> <span class="attribute-name">id</span><span class="markup">=</span><span class="attribute-value">"image"</span> <span class="attribute-name">byReference</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">></span><span class="text"> |
| 504 |
http://myserver.org/uws/jobs/jobid123/param/image</span><span class="markup"></</span><span class="end-tag">uws:parameter</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">uws:parameters</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">uws:results</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">uws:result</span> <span class="attribute-name">id</span><span class="markup">=</span><span class="attribute-value">"correctedImage"</span> <span class="attribute-name">xlink:href</span><span class="markup">=</span><span class="attribute-value">"http://myserver.org/uws/jobs/jobid123/result/image"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">uws:results</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">uws:errorSummary</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"transient"</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">uws:message</span><span class="markup">></span><span class="text">we have problem</span><span class="markup"></</span><span class="end-tag">uws:message</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">uws:detail</span> <span class="attribute-name">xlink:href</span><span class="markup">=</span><span class="attribute-value">"http://myserver.org/uws/jobs/jobid123/error"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">uws:errorSummary</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">uws:jobInfo</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">any</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xml</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">thatyouwant</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xml</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">any</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">uws:jobInfo</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">uws:job</span><span class="markup">></span></div></div></div> |
| 505 |
<p>The <span class="xmlelement"><job></span> element has placeholders of all of the standard UWS objects, and in addition there is a <span class="xmlelement"><uws:jobinfo></span> element which can be used by implementations to include any extra information within the job description.</p> |
| 506 |
</div> |
| 507 |
<div class="section"><h4><a name="d1e1344"/><span class="secnum">2.2.2.3. </span>Results List</h4> |
| 508 |
<p>The representation of a Results List |
| 509 |
is a list of links to the resources representing the results. These |
| 510 |
resources may have any URI and any MIME type. A sensible default for |
| 511 |
their URIs is to make them children of /{jobs}/(job-id)/results, but |
| 512 |
this is not required. It may sometimes be easier for a service |
| 513 |
implementer to point to a resource on some web server separate from |
| 514 |
that running the UWS. Therefore, a client must always parse the |
| 515 |
Results List to find the results. Where a protocol applying UWS |
| 516 |
specifies standard results it must do so by naming those results; the |
| 517 |
names then appear in the Results List in addition to the URIs. Not |
| 518 |
all results need to be named; sometimes the meaning of the result is |
| 519 |
obvious from the context and the name is omitted.</p> |
| 520 |
</div> |
| 521 |
<div class="section"><h4><a name="d1e1353"/><span class="secnum">2.2.2.4. </span>Parameters List</h4> |
| 522 |
The representation of the parameters list is a list of |
| 523 |
<span class="xmlelement"><parameter></span> elements. Each of these elements can either represent the value of the parameter directly, where the content of the element is a textual representation of the parameter, or in the case where the parameter value cannot be represented legally within XML (e.g. the parameter is a binary type such as a FITS file) then the content of the parameter is a URL to the parameter value - to indicate this case the attribute byReference is set to "true".</div> |
| 524 |
</div> |
| 525 |
<div class="section"><h4><a name="d1e634" id="d1e634" shape="rect"/><span class="secnum">2.2.3. </span>State changing requests</h4> |
| 526 |
<p>Certain of the UWS' resources accept |
| 527 |
HTTP POST and DELETE messages to change the state of the service – |
| 528 |
This is the fundamental way that a client controls the execution of a |
| 529 |
job. In most of the cases where a job subobject is set the response |
| 530 |
will have a http 303 “See other” status and a Location header |
| 531 |
that points back to the main job summary obtained at the <span style="font-weight: medium">/{jobs}/(job-id) |
| 532 |
URI. The job summary contains the values of (or links to) all the UWS objects |
| 533 |
within the returned XML (or XHTML). This mode of operation was chosen |
| 534 |
(as opposed to returning only the sub-object being altered) as it |
| 535 |
makes for a more natural user interface – especially in the case of |
| 536 |
the XHMTL interface. A client that wants to obtain only the value of |
| 537 |
a particular sub-object can at any time request that sub-object with |
| 538 |
a HTTP GET.</span></p> |
| 539 |
<div class="section"><h4><a name="d1e1375"/><span class="secnum">2.2.3.1. </span>Creating a Job</h4> |
| 540 |
<p>POSTing a request to the Job List |
| 541 |
creates a new job (unless the service rejects the request). The |
| 542 |
response when a job is accepted must have code 303 “See other” |
| 543 |
and the Location header of the response must point to the created |
| 544 |
job.</p> |
| 545 |
<p>This initial POST will in most cases |
| 546 |
carry parameters for the protocol that is using the UWS pattern, as |
| 547 |
detailed in <h:span xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="xref"><a href="#ApplicationsOfUWS">4. </a></h:span>.</p> |
| 548 |
</div> |
| 549 |
<div class="section"><h4><a name="d1e1390"/><span class="secnum">2.2.3.2. </span>Deleting a Job</h4> |
| 550 |
<p>Sending a HTTP DELETE to a Job |
| 551 |
resource destroys that job, with the meaning noted in the definition |
| 552 |
of the Job object, above. No other resource of the UWS may be |
| 553 |
directly deleted by the client. The response to this request must |
| 554 |
have code 303 “See other” and the Location header of the response |
| 555 |
must point to the Job List at the /{jobs} URI.</p> |
| 556 |
<p>Posting a request with a parameter |
| 557 |
ACTION=DELETE to the Job also destroys the job, the response being as |
| 558 |
for a deletion. This action supports web browsers which typically |
| 559 |
cannot send DELETE requests.</p> |
| 560 |
</div> |
| 561 |
<div class="section"><h4><a name="d1e1402"/><span class="secnum">2.2.3.3. </span>Changing the Destruction |
| 562 |
Time</h4> |
| 563 |
<p>The Destruction Time may be changed |
| 564 |
by POSTing to /{jobs}/(job-id)/destruction. In this case, the body |
| 565 |
of the posted request is of type <i>application/x-www-form-urlencoded</i><b> </b><span style="font-weight: medium">and |
| 566 |
contains the parameter named DESTRUCTION whose value is the new |
| 567 |
destruction time in ISO8601 format; i.e. this request is what an HTML |
| 568 |
form sends.</span></p> |
| 569 |
<p style="font-weight: medium">The |
| 570 |
response to this request must have code 303 “See other” and the |
| 571 |
Location header of the response must point to the /{jobs}/(job-id) |
| 572 |
URI so that the client receives the value that the service has |
| 573 |
actually set the Destruction Time to within the Job summary response.</p> |
| 574 |
</div> |
| 575 |
<div class="section"><h4><a name="d1e1420"/><span class="secnum">2.2.3.4. </span>Changing the Execution |
| 576 |
Duration</h4> |
| 577 |
<p>The Execution Duration may be changed |
| 578 |
by POSTing to /{jobs}/(job-id)/executionduration. In this case, the body |
| 579 |
of the posted request is of type <i>application/x-www-form-urlencoded</i><b> </b><span style="font-weight: medium">and |
| 580 |
contains the parameter named EXECUTIONDURATION whose value is the new |
| 581 |
executionduration in seconds.</span></p> |
| 582 |
<p style="font-weight: medium">The |
| 583 |
response to this request must have code 303 “See other” and the |
| 584 |
Location header of the response must point to the |
| 585 |
/{jobs}/(job-id) so that the client receives the value that the |
| 586 |
service has actually set the Execution Duration to – the service is |
| 587 |
free to override the request if it needs.</p> |
| 588 |
</div> |
| 589 |
<div class="section"><h4><a name="d1e1439"/><span class="secnum">2.2.3.5. </span> Starting a Job</h4> |
| 590 |
<p style="font-weight: medium">A |
| 591 |
job may be started by POSTing to the /{jobs}/(job-id)/phase URI. The |
| 592 |
POST contains a single parameter PHASE=RUN which instructs the UWS to |
| 593 |
attempt to start the job. The response to this request must have code |
| 594 |
303 “See other” and the Location header of the response must |
| 595 |
point to the /{jobs}/(job-id) URI so that the client receives the |
| 596 |
phase that the job has been set to. Typically a UWS will put a job |
| 597 |
into a QUEUED state on receipt of this command, but depending on how |
| 598 |
busy the server is, the job might be put almost immediately (and |
| 599 |
without client intervention) into an EXECUTING state.</p> |
| 600 |
</div> |
| 601 |
<div class="section"><h4><a name="d1e1448"/><span class="secnum">2.2.3.6. </span>Aborting a Job</h4> |
| 602 |
<p style="font-weight: medium">A |
| 603 |
job may be aborted by POSTing to the /{jobs}/(job-id)/phase URI. The |
| 604 |
POST contains a single parameter PHASE=ABORT which instructs the UWS |
| 605 |
to attempt to abort the job. The response to this request must have |
| 606 |
code 303 “See other” and the Location header of the response must |
| 607 |
point to the /{jobs}/(job-id) URI so that the client receives the |
| 608 |
phase that the job has been set to.</p> |
| 609 |
</div> |
| 610 |
</div> |
| 611 |
<div class="section"><h4><a name="d1e708" id="d1e708" shape="rect"/><span class="secnum">2.2.4. </span>Message pattern</h4> |
| 612 |
<p>The REST binding results in the |
| 613 |
message pattern shown in figure 2.</p> |
| 614 |
<p><i>Illustration 2: |
| 615 |
Typical calling sequence for the REST binding of UWS</i></p> |
| 616 |
<p><img src="Sequence_Diagram__UWS__Rest_Message_Pattern__Rest_Message_Pattern__Rest_Message_Pattern.png" name="graphics3" width="1970" height="1024" border="0" align="left" id="graphics3" alt="rest message pattern"/> |
| 617 |
</p> |
| 618 |
</div> |
| 619 |
</div> |
| 620 |
|
| 621 |
</div> |
| 622 |
<div class="section"><h2><a name="security" id="security" shape="rect"/><span class="secnum">3. </span>Security Considerations</h2> |
| 623 |
<p>A UWS should follow IVOA standards for security <cite> |
| 624 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:std:ssoauth">std:ssoauth</a>] |
| 625 |
</cite> if it is desired that a non-public UWS be created. It is possible to imagine many different authorization policies that might be employed in an authenticated UWS, where particular groups of users have different permissions to create and view different types of jobs. A full discussion of such authorization policies is beyond the scope of this document, but a UWS should behave as described in section <h:span xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="xref"><a href="#RESTbinding">2.2. </a></h:span> for any individual authenticated user, although it is clear that a user without sufficient privileges might only obtain a restricted list of jobs withing the joblist at /{jobs}. Any attempt to retrieve a job for which the user does not have sufficient privilege should result in a 403 Forbiden HTTP status being returned.</p> |
| 626 |
<p>When an authentication mechanism is used in the UWS then the implementation should set the owner object to the identity obtained by the authentication. </p> |
| 627 |
</div> |
| 628 |
<div class="section"><h2><a name="ApplicationsOfUWS" id="ApplicationsOfUWS" shape="rect"/><span class="secnum">4. </span> Applications of UWS (informative)</h2> |
| 629 |
<p>The UWS pattern leaves undefined two |
| 630 |
essential parts of the service contract: the content that must be |
| 631 |
posted to create a job; and the pattern of results made available by |
| 632 |
a completed job. An application of UWS completes a service contract |
| 633 |
by defining these matters.</p> |
| 634 |
<p>There follow some use cases applying |
| 635 |
the UWS pattern. The descriptions are neither formal nor complete. |
| 636 |
The intention is to show a range of ways that the pattern can be |
| 637 |
applied without burdening the reader with the level of detail needed |
| 638 |
for a standard implementation.</p> |
| 639 |
<p>Any of these cases could be worked up |
| 640 |
into a full IVOA standard by formalizing the description, adding |
| 641 |
detail (schemata, WSDL) and generally making the specification more |
| 642 |
exact and complete.</p> |
| 643 |
<div class="section"><h3><a name="Imageservice" id="Imageservice" shape="rect"/><span class="secnum">4.1. </span> Image service with data staging</h3> |
| 644 |
<p>Consider a service that computes |
| 645 |
images from archive data. The computation takes significant time, so |
| 646 |
the service is asynchronous. The service keeps the computed images in |
| 647 |
its own storage until the user downloads them; this is essentially |
| 648 |
the model of SIAP <cite> |
| 649 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:std:siap">std:siap</a>] |
| 650 |
</cite>.</p> |
| 651 |
<p>The asynchronous image-service is a |
| 652 |
logical extension of a synchronous SIA service. Therefore it uses the |
| 653 |
REST binding of UWS.</p> |
| 654 |
<p>The parameters for posting a new job |
| 655 |
are as for SIAP 1.0:</p> |
| 656 |
<ul><li> |
| 657 |
<p>POS, the position on the sky to |
| 658 |
be searched;</p> |
| 659 |
</li><li> |
| 660 |
<p>SIZE, the size of the search |
| 661 |
box;</p> |
| 662 |
</li><li> |
| 663 |
<p>FORMAT: the type of images to be |
| 664 |
computed.</p> |
| 665 |
</li></ul> |
| 666 |
<p>Particular implementations are free |
| 667 |
to add extra parameters.</p> |
| 668 |
<p>These parameters are posted in a |
| 669 |
document of type <i>application/x-www-form-urlencoded</i><span style="font-style: normal">: |
| 670 |
i.e. they can be sent from an HTML form.</span></p> |
| 671 |
<p style="font-style: normal">The |
| 672 |
images generated by the job are accessible as unnamed results. Each |
| 673 |
image has its own URI and can be downloaded over HTTP at any time |
| 674 |
until the destruction time of the job. The URIs for the images may be |
| 675 |
discovered from the Results List in the normal UWS way.</p> |
| 676 |
<p style="font-style: normal">SIAP |
| 677 |
1.0 produces, for each query, a table of metadata describing the |
| 678 |
images. The asynchronous image-service produces a table to the same |
| 679 |
schema as a named result, called “table”.</p> |
| 680 |
<p><span style="font-style: normal">Image |
| 681 |
results are added to the results list, and to the “table” result, |
| 682 |
as they are generated. Hence, a client that polls the service can |
| 683 |
discover, download and use some of the images before the job is |
| 684 |
finished. </span>If the client is satisfied with |
| 685 |
these early images, the client can cancel the rest of the job by |
| 686 |
destroying the job. However, destroying the job deletes the cached |
| 687 |
images so the client has to download them <i>first</i>.</p> |
| 688 |
</div> |
| 689 |
<div class="section"><h3><a name="ADQLservice" id="ADQLservice" shape="rect"/><span class="secnum">4.2. </span> ADQL service with cursor</h3> |
| 690 |
<p>ADQL [1] can serve as a JDL. Consider |
| 691 |
an ADQL service that supports long-running queries as asynchronous |
| 692 |
operations. In general, the results of the query may be a large set |
| 693 |
of data. They may be too large to download comfortably. We might like |
| 694 |
to cache these results on the service and to operate a cursor, |
| 695 |
drawing down from the resource a few rows of the table at a time.</p> |
| 696 |
<p>The parameters of a job are as |
| 697 |
follows:</p> |
| 698 |
<ul><li> |
| 699 |
<p>ADQL: the query text</p> |
| 700 |
</li><li> |
| 701 |
<p>FORMAT: the format for the |
| 702 |
results</p> |
| 703 |
</li></ul> |
| 704 |
<p>These parameters are posted in a |
| 705 |
document of type <i>application/x-www-form-urlencoded</i><span style="font-style: normal">: |
| 706 |
i.e. they can be sent from an HTML form.</span></p> |
| 707 |
<p style="font-style: normal">A |
| 708 |
successful query generates the following, named results.</p> |
| 709 |
<ul><li> |
| 710 |
<p style="font-style: normal"><i>table</i>: |
| 711 |
the whole result set as one file resource.</p> |
| 712 |
</li><li> |
| 713 |
<p style="font-style: normal"><i>header</i>: |
| 714 |
the metadata for the output table.</p> |
| 715 |
</li><li> |
| 716 |
<p style="font-style: normal"><i>cursor</i>: |
| 717 |
a selection of rows of output.</p> |
| 718 |
</li></ul> |
| 719 |
<p>The <i>cursor</i> result is |
| 720 |
parameterized by the query parameters FIRST and LAST in the query |
| 721 |
string of its URI: these parameters state the index of the first and |
| 722 |
last row to be returned; e.g.</p> |
| 723 |
<p> http://whatever.org/adlqService/results/cursor?FIRST=1&LAST=100</p> |
| 724 |
<p>If the parameters are missing, the |
| 725 |
service decides which rows to emit.</p> |
| 726 |
</div> |
| 727 |
<div class="section"><h3><a name="ParameterizedApplications" id="ParameterizedApplications" shape="rect"/><span class="secnum">4.3. </span> Parameterized applications</h3> |
| 728 |
<p>There is a class of applications on |
| 729 |
which a job may be defined by a list of simple parameters. “Simple” |
| 730 |
here means unstructured: a scalar value such as a number, a string of |
| 731 |
text or a Boolean value. If the parameters are allowed to name files, |
| 732 |
so that structured data are passed indirectly, then the class of |
| 733 |
applications is very large indeed: almost any non-interactive |
| 734 |
application can be driven in this way.</p> |
| 735 |
<p>Turning each application of choice |
| 736 |
into a service (with or without UWS semantics) would be onerous. |
| 737 |
However, if the application’s interface is entirely characterized, |
| 738 |
through the JDL, in terms of typed input and output parameters, then |
| 739 |
one service contract will work for all the applications and a single |
| 740 |
implementation of the contract can be reused for all cases.</p> |
| 741 |
<p>AstroGrid’s Common Execution |
| 742 |
Architecture (CEA) <cite> |
| 743 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:harrison05">harrison05</a>] |
| 744 |
</cite> works in this way. It has just one service |
| 745 |
contract for all applications (including ADQL services; the ADQL |
| 746 |
query is passed in the list of parameters). It has four |
| 747 |
implementations, one for each of the possible interfaces between the |
| 748 |
service and a kind of job (jobs can be implemented with Java classes, |
| 749 |
command-line applications, HTTP-get services or JDBC databases). CEA |
| 750 |
also specifies stateful, asynchronous services and makes use of |
| 751 |
VOSpace.</p> |
| 752 |
<p>Consider a CEA reworked to use the |
| 753 |
UWS pattern for consistency with other (future) IVOA standards. Call |
| 754 |
it CEA v2 to distinguish it from CEA v1 as currently maintained by |
| 755 |
AstroGrid. For this example, consider the particular kind of CEA |
| 756 |
service that runs applications supplied as executable binaries.</p> |
| 757 |
<p>A binary application-server has a |
| 758 |
library of applications co-located with its service and defined in |
| 759 |
the service configuration set by the service provider. It does not |
| 760 |
accept code from the client for local execution.</p> |
| 761 |
<p>The JDL in CEA v2 is similar to that |
| 762 |
in CEA v1 It is a formal, XML vocabulary for expressing choice |
| 763 |
of application and parameter lists <cite> |
| 764 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:std:vocea">std:vocea</a>] |
| 765 |
</cite>. Parameters may be inputs or |
| 766 |
outputs of the job.</p> |
| 767 |
<p>To start a job, a document in this |
| 768 |
JDL is posted to the UWS. The document is sent in its native |
| 769 |
MIME-type, application/xml, so this is not an interface that can be |
| 770 |
driven directly from an HTML form, although it can be driven from the |
| 771 |
emerging XForms technology<cite> |
| 772 |
[<a xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" href="#ref:std:xform">std:xform</a>] |
| 773 |
</cite>.</p> |
| 774 |
<p>The results of the job depend on the |
| 775 |
choice of application. They are all named results and the names and |
| 776 |
types are defined in the definition of the application. That |
| 777 |
application-definition is registered, so the client knows before |
| 778 |
running the job what results to expect.</p> |
| 779 |
<p>CEA input-parameters may be indirect: |
| 780 |
i.e. they may refer to data in on-line storage. In this case, the JDL |
| 781 |
document contains the URIs for those data objects Alternatively, the |
| 782 |
parameters may be direct, in which case the JDL contains the actual |
| 783 |
value of the parameters.</p> |
| 784 |
<p>Similarly, CEA results may be made |
| 785 |
indirect. In this case, the results are named as parameters in the |
| 786 |
JDL where the values are the URIs to which the results are delivered. |
| 787 |
The application server can then stream the results to the specified |
| 788 |
destination as they become available and need not cache them locally. |
| 789 |
If a job result is indirect, then the server can choose whether or |
| 790 |
not to keep a local copy. If it chooses not to cache locally, then |
| 791 |
the result URI in the UWS is set to the external location named in |
| 792 |
the URI.</p> |
| 793 |
</div> |
| 794 |
</div> |
| 795 |
<div class="section"><h2><a name="SynchronousService" id="SynchronousService" shape="rect"/><span class="secnum">5. </span> Implementing a Synchronous Service on top of UWS (informative)</h2> |
| 796 |
<p>Whilst the provision of synchronous |
| 797 |
services is not one of the design aims of the UWS pattern, there is |
| 798 |
clearly a desire in second generation IVOA services to still allow a |
| 799 |
simple synchronous calling pattern to be available to simple clients. |
| 800 |
What follows is a recommended recipe for putting a synchronous facade |
| 801 |
on UWS;</p> |
| 802 |
<p>It is assumed that the core of the |
| 803 |
service does provide a true UWS compliant set of endpoints rooted at |
| 804 |
/async (equivalent to the /{jobs} endpoint in the nomenclature used |
| 805 |
above). The desired synchronous service is to be rooted at /sync.</p> |
| 806 |
<ol><li> |
| 807 |
<p>The job is started by either a |
| 808 |
GET (for compatibility with existing IVOA standards) or a POST |
| 809 |
(preferably) of form encoded parameters to the /sync endpoint.</p> |
| 810 |
</li><li> |
| 811 |
<p>Internally the service creates a |
| 812 |
job in the standard UWS system with the given parameters and sets |
| 813 |
the PHASE to RUN, noting the returned job identifier which we will |
| 814 |
call {job-id}. The /sync endpoint then responds with a STATUS 303 |
| 815 |
(redirection) response to the URL /sync/{job-id}.</p> |
| 816 |
</li><li> |
| 817 |
<p>The /sync/{job-id} endpoint then |
| 818 |
blocks until it detects that the underlying job has finished at |
| 819 |
which point it responds with a STATUS 303 (redirection) to the |
| 820 |
/{jobs}/{job-id}/results/mainresult URL, where “mainresult” is |
| 821 |
the name of the primary result of the job.</p> |
| 822 |
</li></ol> |
| 823 |
<p>In this way the service appears to be |
| 824 |
a synchronous to the original client – assuming it obeys standard |
| 825 |
HTTP redirection semantics, so a simple client like a web browser |
| 826 |
could obtain the result with a single “click”. At the same time a |
| 827 |
more sophisticated, UWS aware, client could control the same job from |
| 828 |
the standard /{jobs} endpoint – indeed if the synchronous call |
| 829 |
timed out for some reason, then it would be possible for the original |
| 830 |
client to retrieve the results by looking at the /{jobs}/{job-id} URL |
| 831 |
tree, because it could make the association of the job-Id from the |
| 832 |
URL it receives in step 2 above.</p> |
| 833 |
<p>The purely synchronous client is |
| 834 |
restricted compared with the full UWS pattern in that there can only |
| 835 |
be one result directly returned to the client, as noted in stage 3 |
| 836 |
above. This is usually not a problem for compatibility with existing |
| 837 |
version 1.0 DAL services as they typically return a single VOTable |
| 838 |
containing references to the desired data.</p> |
| 839 |
</div> |
| 840 |
|
| 841 |
<div class="appendices"><h2>Appendices</h2> |
| 842 |
|
| 843 |
<div class="section"><h2><a name="Updates" id="Updates"/><span class="secnum">Appendix A. </span> Updates from previous versions</h2> |
| 844 |
<div class="section"><h3><a name="d1e1112" id="d1e1112"/><span class="secnum">Appendix A.1. </span>At Version 0.5</h3> |
| 845 |
<ul><li> |
| 846 |
<p>changed the POST parameter names |
| 847 |
to be the same as the resource paths.</p> |
| 848 |
</li><li> |
| 849 |
<p>added synchronous section.</p> |
| 850 |
</li><li> |
| 851 |
<p>updated SOAP binding section</p> |
| 852 |
</li></ul> |
| 853 |
</div> |
| 854 |
<div class="section"><h3><a name="d1e1775"/><span class="secnum">Appendix A.2. </span>At Version 1.0</h3> |
| 855 |
<ul> |
| 856 |
<li>Removed all SOAP binding - deferred to later version.</li> |
| 857 |
<li>Added parameterList</li> |
| 858 |
<li>Added ownerId and jobId as subsidiary job object</li> |
| 859 |
</ul> |
| 860 |
</div> |
| 861 |
</div> |
| 862 |
|
| 863 |
<div class="section"><h2><a name="UWSSchema" id="UWSSchema"/><span class="secnum">Appendix B. </span> UWS Schema</h2> |
| 864 |
<p>Note that this schema can be found on-line at <a href="http://www.ivoa.net/xml/UWS/1.0" shape="rect">http://www.ivoa.net/xml/UWS/v1.0</a> (i.e. the target namespace |
| 865 |
can also be used as a URL for the schema.) This location should |
| 866 |
represent the definitive source, the schema is reproduced below only for |
| 867 |
completeness of this document.</p> |
| 868 |
<div><?incxml href="../UWS.xsd"?><div xmlns:h="http://www.w3.org/1999/xhtml" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" class="viewxml"><div class="comment"><!-- $Id: UWS.xsd,v 1.1 2009/06/15 15:30:32 pah Exp $ --></div><div class="comment"><!-- proposal for basic UWS schema - Paul Harrison May 2008 --></div><div class="comment"><!-- |
| 869 |
$Log: UWS.xsd,v $ |
| 870 |
Revision 1.1 2009/06/15 15:30:32 pah |
| 871 |
made some of the global element defintions for job subobjects just local again |
| 872 |
added runid, ownerid |
| 873 |
added ParamList |
| 874 |
changed some element names to be consistent with the uris |
| 875 |
Revision 1.6 2008/10/01 11:54:02 pah fix up cvs |
| 876 |
header Revision 1.5 2008/09/25 00:22:35 pah change termination |
| 877 |
time to execution duration |
| 878 |
--></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:schema</span> <span class="attribute-name">targetNamespace</span><span class="markup">=</span><span class="attribute-value">"http://www.ivoa.net/xml/UWS/v1.0rc3"</span> <span class="attribute-name">elementFormDefault</span><span class="markup">=</span><span class="attribute-value">"qualified"</span> <span class="attribute-name">attributeFormDefault</span><span class="markup">=</span><span class="attribute-value">"unqualified"</span> <span class="attribute-name">xlmns:xml</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/XML/1998/namespace"</span> <span class="attribute-name">xlmns:xs</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/2001/XMLSchema"</span> <span class="attribute-name">xlmns:uws</span><span class="markup">=</span><span class="attribute-value">"http://www.ivoa.net/xml/UWS/v1.0rc3"</span> <span class="attribute-name">xlmns:xlink</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/1999/xlink"</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:import</span> <span class="attribute-name">namespace</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/1999/xlink"</span> <span class="attribute-name">schemaLocation</span><span class="markup">=</span><span class="attribute-value">"http://software.astrogrid.org/schema/stc/STC/v1.30/XLINK.xsd"</span><span class="markup">/></span></div><div class="comment"><!-- |
| 879 |
<xs:import namespace="http://www.w3.org/1999/xlink" |
| 880 |
schemaLocation="http://www.ivoa.net/xml/Xlink/xlink.xsd"/> |
| 881 |
--></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"ShortJobDescription"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:sequence</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"phase"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ExecutionPhase"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> the execution phase - returned at |
| 882 |
/(jobs)/(jobid)/phase</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:sequence</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:attribute</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"id"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:JobIdentifier"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"required"</span><span class="markup">/></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:attributeGroup</span> <span class="attribute-name">ref</span><span class="markup">=</span><span class="attribute-value">"uws:reference"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:attributeGroup</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"reference"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">standard xlink references |
| 883 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:attribute</span> <span class="attribute-name">ref</span><span class="markup">=</span><span class="attribute-value">"xlink:type"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"optional"</span> <span class="attribute-name">default</span><span class="markup">=</span><span class="attribute-value">"simple"</span><span class="markup">/></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:attribute</span> <span class="attribute-name">ref</span><span class="markup">=</span><span class="attribute-value">"xlink:href"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"optional"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:attributeGroup</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:simpleType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"ExecutionPhase"</span><span class="markup">></span><div class="comment"><!-- |
| 884 |
need to think a little here about the implication of allowing a |
| 885 |
"re-entrant" application that is capable of running |
| 886 |
mini-jobs...probably this is indicated with a different state |
| 887 |
varible entirely |
| 888 |
--></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> Enumeration of possible phases of job |
| 889 |
execution</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:restriction</span> <span class="attribute-name">base</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"PENDING"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The first phase a job is entered into |
| 890 |
- this is where a job is being set up but no request |
| 891 |
to run has occurred.</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"QUEUED"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> An job has been accepted for execution |
| 892 |
but is waiting in a queue</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"EXECUTING"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">An job is running</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"COMPLETED"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> An job has completed successfully |
| 893 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"ERROR"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> Some form of error has occurred |
| 894 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"UNKNOWN"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The job is in an unknown state |
| 895 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"HELD"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The job is HELD pending execution and |
| 896 |
will not automatically be executed (cf pending) |
| 897 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"SUSPENDED"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The job has been suspended by the |
| 898 |
system during execution</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"ABORTED"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The job has been aborted, either by |
| 899 |
user request or by the server because of lack or |
| 900 |
overuse of resources.</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:enumeration</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:restriction</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:simpleType</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"JobSummary"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">The complete representation of the state |
| 901 |
of a job</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:sequence</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"jobId"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:JobIdentifier"</span><span class="markup">/></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"runId"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> this is a client supplied identifier - |
| 902 |
the UWS system does nothing other than to return it as |
| 903 |
part of the description of the job</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"ownerId"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">the owner (creator) of the job - |
| 904 |
this should be expressed as a string that can be |
| 905 |
parsed in accordance with IVOA security standards. If |
| 906 |
there was no authenticated job creator then this |
| 907 |
should be set to NULL.</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"phase"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ExecutionPhase"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> the execution phase - returned at |
| 908 |
/(jobs)/(jobid)/phase</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"quote"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> A Quote predicts when the job is likely to complete - returned at /(jobs)/(jobid)/quote |
| 909 |
"don't know" is encoded by setting to the XML null value xsi:nil="true"</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"startTime"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">The instant at which the job started execution.</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"endTime"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">The instant at which the job finished execution</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"executionDuration"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:int"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"false"</span><span class="markup">></span><div class="comment"><!-- TODO look if xs:duration here has any benefits --></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The duration (in seconds) for which |
| 910 |
the job should be allowed to run - a value of 0 is |
| 911 |
intended to mean unlimited - returned at |
| 912 |
/(jobs)/(jobid)/executionduration</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"destruction"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The time at which the whole job + |
| 913 |
records + results will be destroyed. returned at |
| 914 |
/(jobs)/(jobid)/destruction</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">ref</span><span class="markup">=</span><span class="attribute-value">"uws:parameters"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">The parameters to the job (where appropriate) |
| 915 |
can also be retrieved at /(jobs)/(jobid)/parameters</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">ref</span><span class="markup">=</span><span class="attribute-value">"uws:results"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">The results for the job - can also be retrieved at /(jobs)/(jobid)/results</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"errorSummary"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ErrorSummary"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">></span><span class="text"> |
| 916 |
</span><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"jobInfo"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> This is arbitrary information that can |
| 917 |
be added to the job description by the UWS |
| 918 |
implementation.</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:sequence</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:any</span> <span class="attribute-name">namespace</span><span class="markup">=</span><span class="attribute-value">"##any"</span> <span class="attribute-name">processContents</span><span class="markup">=</span><span class="attribute-value">"lax"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"unbounded"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:sequence</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:sequence</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:simpleType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"JobIdentifier"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The identifier for the job |
| 919 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:restriction</span> <span class="attribute-name">base</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:simpleType</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"job"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:JobSummary"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> This is the information that is returned |
| 920 |
when a GET is made for a single job resource - i.e. |
| 921 |
/(jobs)/(jobid)</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"jobs"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The list of job references returned at |
| 922 |
/(jobs)</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> ISSUE - do we want to have any sort of |
| 923 |
paging or selection mechanism in case the job list gets |
| 924 |
very large? Or is that an unnecessary complication... |
| 925 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:sequence</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"jobref"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ShortJobDescription"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"unbounded"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:sequence</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"ResultReference"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> A reference to a UWS result |
| 926 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:sequence</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"phase"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ExecutionPhase"</span><span class="markup">/></span></div><div class="comment"><!-- |
| 927 |
pah - TODO why is this here - there was a use case to do |
| 928 |
with picking up results of partially finished jobs ? |
| 929 |
--></div><span class="markup"></</span><span class="end-tag">xs:sequence</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:attribute</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"id"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"required"</span><span class="markup">/></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:attributeGroup</span> <span class="attribute-name">ref</span><span class="markup">=</span><span class="attribute-value">"uws:reference"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"results"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> The element returned for |
| 930 |
/(jobs)/(jobid)/results</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:sequence</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"result"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ResultReference"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"unbounded"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:sequence</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"ErrorSummary"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> A short summary of an error - a fuller representation of the error may be retrieved from /(jobs)/(jobid)/error |
| 931 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:sequence</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"message"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span><span class="markup">/></span></div><div class="comment"><!-- is this detail redundant if we say that the "detailed message" is always available from /(jobs)/(jobid)/error--></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"detail"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:attributeGroup</span> <span class="attribute-name">ref</span><span class="markup">=</span><span class="attribute-value">"uws:reference"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:sequence</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:attribute</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"type"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ErrorType"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text">characterization of the |
| 932 |
type of the error</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:attribute</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:simpleType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"ErrorType"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:restriction</span> <span class="attribute-name">base</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"transient"</span><span class="markup">/></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:enumeration</span> <span class="attribute-name">value</span><span class="markup">=</span><span class="attribute-value">"fatal"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:restriction</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:simpleType</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"Parameter"</span> <span class="attribute-name">mixed</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> the list of input parameters to the job - if |
| 933 |
the job description language does not naturally have |
| 934 |
parameters, then this list should contain one element which |
| 935 |
is the content of the original POST that created the job. |
| 936 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:attribute</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"byReference"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:boolean"</span> <span class="attribute-name">default</span><span class="markup">=</span><span class="attribute-value">"false"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> if this attribute is true then the |
| 937 |
content of the parameter represents a URL to retrieve the |
| 938 |
actual parameter value.</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> It is up to the implementation to decide |
| 939 |
if a parameter value cannot be returned directly as the |
| 940 |
content - the basic rule is that the representation of |
| 941 |
the parameter must allow the whole job element to be |
| 942 |
valid XML. If this cannot be achieved then the parameter |
| 943 |
value must be returned by reference.</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:attribute</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:attribute</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"id"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"required"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:annotation</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:documentation</span><span class="markup">></span><span class="text"> the identifier for the parameter |
| 944 |
</span><span class="markup"></</span><span class="end-tag">xs:documentation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:annotation</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:attribute</span><span class="markup">></span></div><div class="indent"><span class="markup"><</span><span class="start-tag">xs:attribute</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"isPost"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:boolean"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><div class="element"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"parameters"</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:complexType</span><span class="markup">></span><div class="element"><span class="markup"><</span><span class="start-tag">xs:sequence</span><span class="markup">></span><div class="indent"><span class="markup"><</span><span class="start-tag">xs:element</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"parameter"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:Parameter"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"unbounded"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">/></span></div><span class="markup"></</span><span class="end-tag">xs:sequence</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:complexType</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:element</span><span class="markup">></span></div><span class="markup"></</span><span class="end-tag">xs:schema</span><span class="markup">></span></div><div class="comment"><!-- |
| 945 |
|
| 946 |
--></div></div></div> |
| 947 |
|
| 948 |
</div> |
| 949 |
</div> |
| 950 |
<div class="section-nonum'"><h2><a name="References" id="References"/>References</h2> |
| 951 |
<div> |
| 952 |
<?bibliography ivoadoc/refs.bib ?> |
| 953 |
<dl> |
| 954 |
|
| 955 |
<dt><a name="std:xform">[std:xform] John~M. Boyer, editor.</a></dt> <dd> |
| 956 |
<a href="http://www.w3.org/TR/xforms11/" >Xforms 1.1</a>, 2007. |
| 957 |
</dd> |
| 958 |
|
| 959 |
<dt><a name="std:soap">[std:soap] Don Box, David Ehnebuske, Gopal Kakivaya, |
| 960 |
Andrew Layman, Noah Mendelsohn, Henrik~Frystyk Nielsen, Satish Thatte, and |
| 961 |
Dave Winer.</a></dt> <dd> |
| 962 |
<a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/" >Simple object access |
| 963 |
protocol (soap) 1.1</a>, 2000. |
| 964 |
</dd> |
| 965 |
|
| 966 |
<dt><a name="fielding00">[fielding00] Roy~Thomas Fielding.</a></dt> <dd> |
| 967 |
<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm" |
| 968 |
><em>Architectural Styles and the Design of Network-based Software |
| 969 |
Architectures</em></a>. |
| 970 |
PhD thesis, University of California, Irvine, 2000. |
| 971 |
</dd> |
| 972 |
|
| 973 |
<dt><a name="std:iso8601">[std:iso8601] {Grid and Web Services Working Group}, |
| 974 |
Guy Rixon and Matthew Graham, editors.</a></dt> <dd> |
| 975 |
<a href="http://www.ivoa.net/Documents/latest/SSOAuthMech.html" >Ivoa |
| 976 |
single-sign-on profile: Authentication mechanisms version 1.01</a>, 2008. |
| 977 |
</dd> |
| 978 |
|
| 979 |
<dt><a name="std:ssoauth">[std:ssoauth] {Grid and Web Services Working Group}, |
| 980 |
Guy Rixon and Matthew Graham, editors.</a></dt> <dd> |
| 981 |
<a href="http://www.ivoa.net/Documents/latest/SSOAuthMech.html" >Ivoa |
| 982 |
single-sign-on profile: Authentication mechanisms version 1.01</a>, 2008. |
| 983 |
</dd> |
| 984 |
|
| 985 |
<dt><a name="harrison05">[harrison05] P.~Harrison.</a></dt> <dd> |
| 986 |
<a href="http://www.ivoa.net/Documents/latest/CEA.html" >A proposal for a |
| 987 |
common execution architecture</a>. |
| 988 |
{IVOA Note}, May 2005. |
| 989 |
</dd> |
| 990 |
|
| 991 |
<dt><a name="std:vocea">[std:vocea] Paul Harrison.</a></dt> <dd> |
| 992 |
Vocea - an xml schema for registering cea. |
| 993 |
</dd> |
| 994 |
|
| 995 |
<dt><a name="sextractor">[sextractor] |
| 996 |
http://astromatic.iap.fr/software/sextractor/.</a></dt> <dd> |
| 997 |
<a href="http://astromatic.iap.fr/software/sextractor/" >Sextractor</a>. |
| 998 |
[Online]. |
| 999 |
</dd> |
| 1000 |
|
| 1001 |
<dt><a name="std:adql">[std:adql] Iñaki Ortiz, Jeff Lusted, Pat Dowler, |
| 1002 |
Alexander Szalay, Yuji Shirasaki, Maria~A. Nieto-Santisteba, Masatoshi |
| 1003 |
Ohishi, William OÕMullane, Pedro Osuna, the VOQL-TEG, and the VOQL |
| 1004 |
Working~Group, Pedro Osuna and Iñaki Ortiz, editors.</a></dt> <dd> |
| 1005 |
<a href="http://www.ivoa.net/Documents/latest/ConeSearch.html" >Ivoa |
| 1006 |
astronomical data query language</a>. |
| 1007 |
{IVOA Recommendation}, 2008. |
| 1008 |
</dd> |
| 1009 |
|
| 1010 |
<dt><a name="std:siap">[std:siap] Doug Tody and Ray Plant, Paul Harrison, |
| 1011 |
editor.</a></dt> <dd> |
| 1012 |
<a href="http://www.ivoa.net/Documents/latest/SIA.html" >Simple image access |
| 1013 |
specification</a>. |
| 1014 |
{IVOA Recommendation}, 2009. |
| 1015 |
</dd> |
| 1016 |
|
| 1017 |
<dt><a name="std:scs">[std:scs] Roy Williams, Robert Hanisch, Alex Szalay, and |
| 1018 |
Raymond Plante, Raymond Plante, editor.</a></dt> <dd> |
| 1019 |
<a href="http://www.ivoa.net/Documents/latest/ConeSearch.html" >Simple cone |
| 1020 |
search</a>. |
| 1021 |
{IVOA Recommendation}, 2008. |
| 1022 |
</dd> |
| 1023 |
|
| 1024 |
</dl></div> |
| 1025 |
</div> |
| 1026 |
</div> |
| 1027 |
<p style="text-align: right; font-size: x-small; color: #888;"> |
| 1028 |
$Revision: 847 $ $Date: 2008-10-29 14:33:57 +0000 (Wed, 29. Oct 2008) $ |
| 1029 |
</p> |
| 1030 |
|
| 1031 |
</body></html> |
Parent Directory
| 
Revision Log
