/[volute]/trunk/projects/grid/uws/doc/UWS.html
ViewVC logotype

Contents of /trunk/projects/grid/uws/doc/UWS.html

Parent Directory Parent Directory | Revision Log Revision Log


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

Properties

Name Value
svn:mime-type application/xhtml+xml

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26