/[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 5785 - (show annotations)
Mon May 11 15:05:35 2020 UTC (3 months ago) by harripa
File MIME type: application/xhtml+xml
File size: 161880 byte(s)
small error in html meta information

1 <?xml version="1.0" encoding="UTF-8"?><!-- $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 <!DOCTYPE html
6 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
7 <html xmlns="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xml:lang="en" lang="en" xsi:schemalocation="http://www.w3.org/1999/xhtml http://www.w3.org/2002/08/xhtml/xhtml1-transitional.xsd" xml:space="preserve">
8 <head profile="http://www.w3.org/1999/xhtml/vocab"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
9
10 <title>Universal Worker Service Pattern 1.1 - IVOA Recommendation 24 October 2016</title>
11 <meta name="Title" content="IVOA WG Recomendation" />
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 href="http://volute.googlecode.com/svn/trunk/projects/ivoapub/ivoadoc/XMLPrint.css" rel="stylesheet" type="text/css" />
16 <link href="http://volute.googlecode.com/svn/trunk/projects/ivoapub/ivoadoc/ivoa-extras.css" rel="stylesheet" type="text/css" />
17 <link rel="stylesheet" type="text/css" href="http://www.ivoa.net/misc/ivoa_rec.css" />
18 </head>
19 <body>
20 <div class="head">
21 <div id="titlehead" style="position:relative;height:170px;width: 500px">
22 <div id="logo" style="position:absolute;width:300px;height:169px;left: 50px;top: 0px;">
23 <img src="http://www.ivoa.net/pub/images/IVOA_wb_300.jpg" alt="IVOA logo" /></div>
24 <div id="logo-title" style="position: absolute; width: 200px; height: 115px; left: 320px; top: 5px; font-size: 14pt; color: #005A9C; font-style: italic;">
25 <p style="position: absolute; left: 0px; top: 0px;"><span style="font-weight: bold;">I</span> nternational</p>
26 <p style="position: absolute; left: 15pt; top: 25pt;"><span style="font-weight: bold;">V</span> irtual</p>
27 <p style="position: absolute; left: 15pt; top: 50pt;"><span style="font-weight: bold;">O</span> bservatory</p>
28 <p style="position: absolute; left: 0px; top: 75pt;"><span style="font-weight: bold;">A</span> lliance</p>
29 </div>
30 </div>
31 <h1>Universal Worker Service Pattern<br clear="none" />
32 Version <span class="docversion">1.1</span></h1>
33 <h2 class="subtitle">IVOA Recommendation 24 October 2016</h2>
34 <dl><dt>Working Group:</dt><dd><a href="http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices" shape="rect">http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices</a></dd>
35 <dt><b>This version:</b></dt><dd><a href="http://www.ivoa.net/Documents/UWS/20150519/" shape="rect">http://www.ivoa.net/Documents/UWS/20150519/</a></dd>
36 <dt><b>Latest Recommendation:</b></dt><dd><a href="http://www.ivoa.net/Documents/UWS/" shape="rect">http://www.ivoa.net/Documents/UWS/</a></dd>
37 <dt><b>Previous version(s):</b></dt><dd>
38 <a href="http://www.ivoa.net/documents/UWS/20101010/" shape="rect">Recommendation v1.0 2010-10-10</a><br clear="none" />
39 <a href="http://www.ivoa.net/documents/UWS/20140527/" shape="rect">Working Draft v1.1 2014-05-27</a><br clear="none" />
40 <a href="http://www.ivoa.net/documents/UWS/20140930/" shape="rect">Working Draft v1.1 2014-09-30</a><br clear="none" />
41 <a href="http://www.ivoa.net/documents/UWS/20150615/" shape="rect">Working Draft v1.1 2015-06-15</a><br clear="none" />
42 <a href="http://www.ivoa.net/documents/UWS/20150626/" shape="rect">Proposed Recommendation v1.1 2015-06-26</a><br clear="none" />
43 <a href="http://www.ivoa.net/documents/UWS/20151130/" shape="rect">Proposed Recommendation v1.1 2015-11-30</a><br clear="none" />
44 <a href="http://www.ivoa.net/documents/UWS/20160505/" shape="rect">Proposed Recommendation v1.1 2016-05-05</a><br clear="none" />
45 </dd>
46 <dt>
47 </dt>
48 <dt> <br clear="none" />
49 </dt><dd>&nbsp;</dd><dt><b>Author(s):</b></dt>
50 <dd> P. A. Harrison, G. Rixon</dd>
51 <dt> <br clear="none" />
52 </dt><dd>&nbsp;</dd>
53 <dt><b>Editor:</b></dt>
54 <dd> P. A. Harrison</dd>
55 </dl>
56
57 <h2>Abstract</h2>
58 <p>The Universal Worker Service (UWS) pattern
59 defines how to manage asynchronous execution of jobs on a
60 service. Any application of the pattern defines a family of related
61 services with a common service contract. Possible uses of the pattern are also described.</p>
62 <h2> Status of This Document</h2>
63 <p id="statusdecl"><em>
64 This document has been reviewed by IVOA Members and other
65 interested parties, and has been endorsed by the IVOA
66 Executive Committee as an IVOA Recommendation. It is a
67 stable document and may be used as reference material or
68 cited as a normative reference from another document.
69 IVOA's role in making the Recommendation is to draw
70 attention to the specification and to promote its
71 widespread deployment. This enhances the functionality and
72 interoperability inside the Astronomical Community.
73 </em></p>
74 <p> <em>A list of </em><span style="background: transparent"><a href="http://www.ivoa.net/Documents/" shape="rect"><i>current
75 IVOA Recommendations and other technical documents</i></a></span><em> can be found at http://www.ivoa.net/Documents/.</em></p>
76 <p>The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and "OPTIONAL" (in upper or lower case) used in this document are to be interpreted as described in IETF standard, RFC 2119 <cite>[<a href="#std:rfc2119">std:rfc2119</a>]</cite>.</p>
77 <h2 class="prologue-heading-western">Acknowledgements</h2>
78 <p>The need for the UWS pattern was
79 inspired by AstroGrid’s Common Execution Architecture and
80 particularly by discussions with Noel Winstanley. The ideas about
81 statefulness are distilled from debates in the Global Grid Forum in
82 respect of the Open Grid Services Infrastructure that was the
83 fore-runner of Web Services Resource Framework. The REST binding came
84 initially from suggestions by Norman Gray. Enhancements introduced in version 1.1 were as a result of feedback from implementors, particularly Pat Dowler, Dave Morris, Mark Taylor, Petr Škoda and Kristin Riebe.</p>
85 </div><h2>Contents</h2><div><!--The contents of this div are automatically generated from the following processing instruction when processed with ivoarestructure.xsl-->
86 <?toc?><div id="toc" class="toc"><ul><li><a href="#Introduction"><span class="secnum">1. </span>Introduction (informative)</a><ul><li><a href="#SynchronousStateless"><span class="secnum">1.1. </span>Synchronous, stateless services</a></li><li><a href="#AsynchronousServices"><span class="secnum">1.2. </span>Asynchronous and stateful services</a></li><li><a href="#JDL"><span class="secnum">1.3. </span>Job description language, service contracts and universality</a></li><li><a href="#IVOARCH"><span class="secnum">1.4. </span>UWS in the IVOA Architecture</a></li></ul></li><li><a href="#UWSpattern"><span class="secnum">2. </span>Universal Worker Service Pattern (normative)</a><ul><li><a href="#UWSObjects"><span class="secnum">2.1. </span>Objects within a UWS</a><ul><li><a href="#Joblist"><span class="secnum">2.1.1. </span>Job list</a></li><li><a href="#Job"><span class="secnum">2.1.2. </span>Job</a></li><li><a href="#ExecutionPhase"><span class="secnum">2.1.3. </span>Execution Phase</a></li><li><a href="#ExecutionDuration"><span class="secnum">2.1.4. </span>Execution Duration</a></li><li><a href="#DestructionTime"><span class="secnum">2.1.5. </span>Destruction Time</a></li><li><a href="#Quote"><span class="secnum">2.1.6. </span>Quote</a></li><li><a href="#Error"><span class="secnum">2.1.7. </span>Error</a></li><li><a href="#ownerId"><span class="secnum">2.1.8. </span>Owner</a></li><li><a href="#runId"><span class="secnum">2.1.9. </span>RunId</a></li><li><a href="#ResultsList"><span class="secnum">2.1.10. </span>Results List</a></li><li><a href="#ResultsList2"><span class="secnum">2.1.11. </span>Parameter List</a></li></ul></li><li><a href="#RESTbinding"><span class="secnum">2.2. </span>The REST Binding</a><ul><li><a href="#resourceuri"><span class="secnum">2.2.1. </span>Resources and URIs</a><ul><li><a href="#versioning"><span class="secnum">2.2.1.1. </span>Determining the Protocol Version</a></li><li><a href="#blocking"><span class="secnum">2.2.1.2. </span>Blocking Behaviour</a></li></ul></li><li><a href="#d1e603"><span class="secnum">2.2.2. </span>Representations of resources</a><ul><li><a href="#jobList"><span class="secnum">2.2.2.1. </span>Job List</a></li><li><a href="#jobobj"><span class="secnum">2.2.2.2. </span>Job</a></li><li><a href="#resultList"><span class="secnum">2.2.2.3. </span>Results List</a></li><li><a href="#d1e1353"><span class="secnum">2.2.2.4. </span>Parameters List</a></li><li><a href="#d1e1556"><span class="secnum">2.2.2.5. </span>Error</a></li></ul></li><li><a href="#jobcontrol"><span class="secnum">2.2.3. </span>State changing requests</a><ul><li><a href="#jobCreation"><span class="secnum">2.2.3.1. </span>Creating a Job</a><ul><li><a href="#d2e1612"><span class="secnum">2.2.3.1.1. </span>Inline Parameters</a></li></ul></li><li><a href="#d1e1390"><span class="secnum">2.2.3.2. </span>Deleting a Job</a></li><li><a href="#d1e1402"><span class="secnum">2.2.3.3. </span>Changing the Destruction Time</a></li><li><a href="#d1e1420"><span class="secnum">2.2.3.4. </span>Changing the Execution Duration</a></li><li><a href="#d1e1439"><span class="secnum">2.2.3.5. </span>Starting a Job</a></li><li><a href="#d1e1448"><span class="secnum">2.2.3.6. </span>Aborting a Job</a></li></ul></li></ul></li></ul></li><li><a href="#security"><span class="secnum">3. </span>Security Considerations (normative)</a></li><li><a href="#ApplicationsOfUWS"><span class="secnum">4. </span>Applications of UWS (informative)</a><ul><li><a href="#Imageservice"><span class="secnum">4.1. </span>Image service with data staging</a></li><li><a href="#ADQLservice"><span class="secnum">4.2. </span>ADQL service with cursor</a></li><li><a href="#ParameterizedApplications"><span class="secnum">4.3. </span>Parameterised applications</a></li></ul></li><li><a href="#SynchronousService"><span class="secnum">5. </span>Implementing a Synchronous Service on top of UWS (informative)</a></li><li><a href="#Updates"><span class="secnum">A. </span>Updates from previous versions</a><ul><li><a href="#d1e1112"><span class="secnum">A.1. </span>At Version 0.5</a></li><li><a href="#d1e1775"><span class="secnum">A.2. </span>At Version 1.0</a></li><li><a href="#ver11"><span class="secnum">A.3. </span>At Version 1.1</a></li></ul></li><li><a href="#UWSSchema"><span class="secnum">B. </span>UWS Schema</a></li></ul></div>
87 <!--end of autogenerated content--></div><div class="body">
88 <div class="section"><h2><a id="Introduction" shape="rect"><span class="secnum">1. </span>Introduction (informative)</a></h2>
89 <p>The Universal Worker Service (UWS)
90 pattern defines how to build <i>asynchronous</i>, <i>stateful</i>, <i>job-oriented</i> services<i> </i>(the italicised terms are defined
91 in sub-sections of this introduction). It does so in a way that
92 allows for wide-scale reuse of software and support from software
93 toolkits.</p>
94 <p>Section <span class="xref"><a href="#UWSpattern">2</a></span>
95 of this document describes
96 the pattern and lists the aspects that are common to all its
97 applications. Any such application would involve a service contract
98 that embodies the pattern and fixes the issues left undefined in the
99 pattern itself (see section <span class="xref"><a href="#JDL">1.3</a></span>). The contract might include the XML schemata which form a "job description language" 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
100 cover a family of related applications, such that the implementations
101 may be widely reused.</p>
102 <p>Section <a href="#ApplicationsOfUWS" shape="rect">4</a> outlines several possible
103 applications of the pattern. These use-cases may be expanded into
104 full IVOA standards that are siblings of the current document.</p>
105 <p>Section <a class="xref" href="#SynchronousService" shape="rect">5</a> describes the preferred
106 method of creating a synchronous facade to a UWS system.</p>
107 <div class="section"><h3><a id="SynchronousStateless" shape="rect"><span class="secnum">1.1. </span>Synchronous, stateless services</a></h3>
108 <p>Simple web services are <i>synchronous</i> and <i>stateless</i>. Synchronous means that the client waits for
109 each request to be fulfilled; if the client disconnects from the
110 service then the activity is abandoned. <i>Stateless</i> means that
111 the service does not remember results of a previous activity (or, at
112 least, the client cannot ask the service about them).</p>
113 <p>Synchronous, stateless services work
114 well when two criteria apply.</p>
115 <ol><li>
116 <p>The length of each activity is
117 less than the “attention span” of the connection.</p>
118 </li><li>
119 <p>The results of each activity are
120 compact enough to be easily passed back to the client via the
121 connection on which the request was made (and possibly pushed back
122 to the service as parameters of the next activity).</p>
123 </li></ol>
124 <p>There are various limits to the
125 attention span.</p>
126 <ul><li>
127 <p>HTTP assumes that the start of a
128 reply quickly follows its request, even if the body of the reply
129 takes a long time to stream. If the service takes too long to
130 compute the results and to start the reply, then HTTP times out and
131 the request is lost.</p>
132 </li><li>
133 <p>A client runs on a computer which
134 will not stay on-line indefinitely.</p>
135 </li><li>
136 <p>A network with finite
137 reliability will eventually break communications during an activity.</p>
138 </li><li>
139 <p>A service is sometimes shut down
140 for maintenance.</p>
141 </li></ul>
142 <p>Synchronous, stateless services, in
143 short, do not scale well. The following examples illustrate situations in the VO in which synchronous, stateless services are inadequate.</p>
144 <ol><li>
145 <p>An ADQL <cite>[<a href="#std:adql">std:adql</a>]</cite> service gives access
146 to a large object-catalogue. Most queries run in less than a minute,
147 but some legitimate queries involve a full-table traverse and take
148 hours or days. The service needs to run these special cases in a
149 low-priority queue.</p>
150 </li><li>
151 <p>An object-finding service runs
152 the SExtractor <cite>[<a href="#sextractor">sextractor</a>]</cite> application on a list of images. Normally, the list
153 is short and the request is quickly satisfied. Occasionally, a list
154 of 10,000 images is sent in the expectation that the work will be
155 finished over the weekend.</p>
156 </li><li>
157 <p>A cone-search <cite>[<a href="#std:scs">std:scs</a>]</cite> request on a
158 rich catalogue raises 10,000,000 rows of results, but the client is
159 connected via a slow link and cannot read all the results in a
160 reasonable time. The client needs the service to send the results
161 into storage over a faster link. This could mean sending them to
162 VOSpace <cite>[<a href="#std:vospace">std:vospace</a>]</cite>, or simply holding them temporarily at the service until the user can
163 retrieve them on a fast link. UWS provides a pattern for doing the latter.</p>
164 </li><li>
165 <p>An ADQL service allows users to
166 save query results into new tables such that they can be the target
167 of later queries. However, space is limited and the results tables
168 can only be kept for a short time. The client and service negotiate
169 the lifetime of the results tables.</p>
170 </li><li>
171 <p>A service performs image
172 stacking on a list of fields. Each field can be processed by a
173 synchronous service but the list is long and the user wants to
174 retrieve the results of the early fields before the last fields are
175 processed.</p>
176 </li></ol>
177 </div>
178 <div class="section"><h3><a id="AsynchronousServices" shape="rect"><span class="secnum">1.2. </span>Asynchronous and stateful services</a></h3>
179 <p>Services can be made to scale better
180 by making them <i>asynchronous</i> and <i>stateful</i>. Asynchronous
181 means that a client makes two or more separate requests to the
182 service in the course of one activity, and that the client and
183 service may be disconnected, possibly for days or more, in between
184 those requests. Stateful means that the service stores state
185 information about the activity and the client addresses requests to
186 this state.</p>
187 <p>Web services that are asynchronous
188 are almost always stateful. Most of the special extra arrangements for
189 asynchronous activities are actually managing the state of the
190 activity.</p>
191 <p>There is an important class of
192 stateful services where the state is peculiar to one job or session
193 and the job is “owned” by one user. These, for the purpose of
194 this document, are called <i>job-oriented</i> services. There are
195 stateful services that are not job-oriented (e.g. a service managing
196 a shared, client-writeable DB table), but UWS does not apply to
197 these.</p>
198 <p>For the purpose of this discussion,
199 let the term <i>job</i> refer to the work specified by the JDL
200 instructions and the term <i>resource</i> refer to the state of the
201 job as recorded by the service. Both have a finite duration. The <i>lifetime</i> of the resource – i.e. the time from inception
202 until the service forgets the state – is generally finite and must
203 be at least as long the duration of the job.</p>
204 </div>
205 <div class="section"><h3><a id="JDL" shape="rect"><span class="secnum">1.3. </span>Job description language, service contracts and universality</a></h3>
206 <p>Consider the web-service operation
207 that starts off a job. This operation must express what is to be done
208 in the activity: it must carry parameters in some form.</p>
209 <p>The parameters may be expressed as a
210 list. For example, a cone search service takes a list of three parameters:
211 RA, DEC, RADIUS. Alternatively, the parameters may be arranged as an
212 XML document (e.g. CEA <cite>[<a href="#harrison05">harrison05</a>]</cite>). The rules for setting and arranging
213 the parameters for a job are called the<i> Job-Description Language </i>(JDL).</p>
214 <p>The combination of the UWS pattern, a
215 JDL and details of the job state visible to the client defines a
216 service contract. Changing the JDL changes the contract. Thus, it is not
217 meaningful to “implement UWS” in isolation; any implementation
218 standard must specify the rest of the contract.</p>
219 <p>If the JDL is very general, a single
220 service-contract can be reused for many kinds of service. AstroGrid’s
221 CEA<cite>[<a href="#harrison05">harrison05</a>]</cite>exploits this: one JDL covers all services offering parameterised
222 applications and even ADQL services. In the limit, a
223 sufficiently-general JDL turns a specialized worker service into a
224 universal worker service.</p>
225 </div>
226 <div class="section"><h3><a id="IVOARCH" shape="rect"><span class="secnum">1.4. </span>UWS in the IVOA Architecture</a></h3>
227 <p><img src="ivoaarchitecture.png" alt="ivoa architectures" /></p>
228 <p>With the IVOA Architecture above, UWS is a VO infrastructure standard, being used by other standards and services to enable the development of VO applications managing asynchronous and stateless execution of jobs on VO services. Examples of such jobs include the case where the response must be computed, and that computation time takes longer than the normal expectation in an interactive web session. Additionally the UWS pattern allows a simple form of data sharing of the results of a job that is suitable for "workflow" situations and can be used by Data Access Services (currently Table Access Protocol <cite>[<a href="#std:tap">std:tap</a>]</cite>, but potentially by other DAL standards). It utilizes IVOA standards for security <cite>[<a href="#std:ssoauth">std:ssoauth</a>]</cite> if it is desired that a non-public UWS be created. </p>
229 </div>
230 </div>
231 <div class="section"><h2><a id="UWSpattern" shape="rect"><span class="secnum">2. </span>Universal Worker Service Pattern (normative)</a></h2>
232 <div class="section"><h3><a id="UWSObjects" shape="rect"><span class="secnum">2.1. </span>Objects within a UWS</a></h3>
233 <p>A UWS consists logically of a set of
234 objects that may be read and written to in order to control jobs. The objects are represented by elements within the XML schema detailed in <span class="xref"><a href="#UWSSchema">B</a></span>. In a REST binding, these objects are addressed as distinct web-resources each with its own URI. </p>
235 <p> The following sub-sections explain the semantics of the objects. The
236 UML diagram below shows the relationships more succinctly.</p>
237 <p><img src="Class_Diagram__UWS__UWSObjects.png" alt="UWS Objects Class Diagram" width="460" height="390" id="graphics2" /></p>
238 <div class="section"><h4><a id="Joblist" shape="rect"><span class="secnum">2.1.1. </span>Job list</a></h4>
239 <p>The Job List is the outermost object:
240 it contains all the other objects in the UWS. The immediate children
241 of the job list are Job objects (see next sub-section).</p>
242 <p>The job list may be read to find the
243 extant jobs.</p>
244 <p>The job list may be updated to add a
245 new job.</p>
246 <p>The job list itself does not allow
247 jobs to be deleted. Instead, when a job is destroyed by an action on
248 its job object, then the list updates itself accordingly.</p>
249 </div>
250 <div class="section"><h4><a id="Job" shape="rect"><span class="secnum">2.1.2. </span>Job</a></h4>
251 <p>A Job object contains the state of
252 one job. The state is a collection of other objects. Each Job
253 contains:</p>
254 <ul><li>
255 <p>Exactly one Execution Phase.</p>
256 </li><li>
257 <p>Exactly one Execution Duration.</p>
258 </li><li>
259 <p>Exactly one Destruction Time</p>
260 </li><li>
261 <p>Zero or one Quote.</p>
262 </li><li>
263 <p>Exactly one Results List.</p>
264 </li><li><p>Exactly one Owner.</p></li><li>
265 <p>Zero or one Run Identifier.</p>
266 </li><li>
267 <p>Zero or one Error.</p>
268 </li>
269 </ul>
270 <p>In addition a job has a number of other properties (e.g. creationTime) which are set automatically by the UWS and are not able to be directly manipulated by the client, hence are not represented as separate object.</p>
271 </div>
272 <div class="section"><h4><a id="ExecutionPhase" shape="rect"><span class="secnum">2.1.3. </span>Execution Phase</a></h4>
273 <p>The job is treated as a state machine
274 with the Execution Phase naming the state (labelled simply as "Phase" in the UML diagram above). The phases are:</p>
275 <ul><li>
276 <p>PENDING: the job is accepted by
277 the service but not yet committed for execution by the client. In
278 this state, the job quote can be read and evaluated. This is the
279 state into which a job enters when it is first created.</p>
280 </li><li>
281 <p>QUEUED: the job is committed for
282 execution by the client but the service has not yet assigned it to a
283 processor. No Results are produced in this phase.</p>
284 </li><li>
285 <p>EXECUTING: the job has been
286 assigned to a processor. Results may be produced at any time during
287 this phase.</p>
288 </li><li>
289 <p>COMPLETED: the execution of the
290 job is over. The Results may be collected.</p>
291 </li><li>
292 <p>ERROR: the job failed to
293 complete. No further work will be done nor Results produced. Results
294 may be unavailable or available but invalid; either way the Results
295 should not be trusted.</p>
296 </li><li>
297 <p>ABORTED: the job has been
298 manually aborted by the user, or the system has aborted the job due
299 to lack of or overuse of resources.</p>
300 </li><li><p>UNKNOWN: The job is in an unknown state.</p></li><li>
301 <p>HELD: The job is HELD pending execution and
302 will not automatically be executed (cf, PENDING)</p>
303 </li><li><p>SUSPENDED: The job has been suspended by the system during execution. This might be because of temporary lack of resource. The UWS will automatically resume the job into the EXECUTING phase without any intervention when resource becomes available.</p></li>
304 <li>ARCHIVED: At destruction time the results associated with a job have been deleted to free up resource, but the metadata associated with the job have been retained. <span class="text">This is an alternative that the server may choose in contrast to completely destroying all record of the job to allow a longer historical record of the existence of the job to be kept that would otherwise be the case if limited result storage resources forces destruction.</span></li>
305 </ul>
306 <p>A successful job will normally progress through the PENDING, QUEUED, EXECUTING, COMPLETED phases in that order. At any time before the COMPLETED phase a job may either be ABORTED or may suffer an ERROR. If the UWS reports an UNKNOWN phase, then all the client can do is re-query the phase until a known phase is reported. A UWS may place a job in a HELD phase on receipt of a PHASE=RUN request if for some reason the job cannot be immediately queued - in this case it is the responsibility of the client to request PHASE=RUN again at some later time. The state diagram below represents these states, where the blue transitions are ones that can be initiated by the client, and the black transitions are ones that the server may make.</p>
307 <p><img src="UWSStates.png" alt="UWS state diagram" /></p>
308
309 </div>
310 <div class="section"><h4><a id="ExecutionDuration" shape="rect"><span class="secnum">2.1.4. </span>Execution Duration</a></h4>
311 <p>An Execution Duration object defines
312 the duration for which a job shall run. This represents the
313 “computation time” that a job is to be allowed, although because
314 a specific measure of CPU time may not be available in all
315 environments, this duration is defined in real clock seconds. An
316 execution duration of 0 implies unlimited execution duration.</p>
317 <p>When the execution duration has been
318 exceeded the service should automatically abort the job, which has the
319 same effect as when a manual “Abort” is requested.</p>
320 <p>Specifically, when a job is aborted:</p>
321 <ul><li>
322 <p>if the job is still executing,
323 the execution is aborted.</p>
324 </li><li>
325 <p>any previously generated results
326 of the job are retained.</p>
327 </li></ul>
328 <p>When a job is created, the service
329 sets the initial execution duration. The client may write to an
330 Execution Duration to try to change the job's cpu time allocation.
331 The service may forbid changes, or may set limits on the allowed
332 execution duration.</p>
333 </div>
334 <div class="section"><h4><a id="DestructionTime" shape="rect"><span class="secnum">2.1.5. </span>Destruction Time</a></h4>
335 <p>The Destruction Time object
336 represents the instant when the job shall be destroyed. The
337 Destruction Time is an absolute time.</p>
338 <p>Destroying a job implies:</p>
339 <ul><li>
340 <p>if the job is still executing,
341 the execution is aborted.</p>
342 </li><li>
343 <p>any results from the job are
344 destroyed and storage reclaimed.</p>
345 </li><li>
346 <p>the service forgets that
347 the job existed.</p>
348 </li></ul>
349 <p>The Destruction Time should be viewed as
350 a measure of the amount of time that a service is prepared to
351 allocate storage for a job – typically this will be a longer
352 duration that the amount of CPU time that a service would allocate.</p>
353 <p>When a job is created the service
354 sets the initial Destruction Time. The client may write to the
355 Destruction Time to try to change the life expectancy of the job. The
356 service may forbid changes, or may set limits on the allowed
357 destruction time. If there is no destruction time set by the service then this should be indicated in the job XML as an <span class="xmlelement">xsi:nil</span> element and as a null string in the returned value for the resource.</p>
358 </div>
359 <div class="section"><h4><a id="Quote" shape="rect"><span class="secnum">2.1.6. </span>Quote</a></h4>
360 <p>A Quote object predicts when the job
361 is likely to complete. The intention is that a client creates the
362 same job on several services, compares the quotes and then accepts
363 the best quote. From the server perspective it is possible to indicate that a job will not be run by specifying a Quote that is greater than the Destruction time.</p>
364 <p>Quoting for a computational job is
365 notoriously difficult. A UWS implementation should provide a
366 quote object, in order that the two-phase committal of jobs be
367 uniform across all UWS, but it may supply a “don't know” answer
368 for the completion time, indicated by an XML <span class="xmlelement">xsi:nil</span> element in an XML representation of the quote object.</p>
369 </div>
370 <div class="section"><h4><a id="Error" shape="rect"><span class="secnum">2.1.7. </span>Error</a></h4>
371 <p>The error object gives a human-readable error message for the underlying job. This object
372 is intended to be a detailed error message, and consequently might be
373 a large piece of text such as a stack trace. When there is an error
374 running a job, a summary of the error should also be given using the
375 optional errorSummary element of the Job element.</p>
376 </div>
377 <div class="section"><h4><a id="ownerId" shape="rect"><span class="secnum">2.1.8. </span>Owner</a></h4>
378 <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
379 <span class="xref"><a href="#security">3</a></span>. </p>
380 </div>
381 <div class="section"><h4><a id="runId" shape="rect"><span class="secnum">2.1.9. </span>RunId</a></h4>
382 <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>
383 </div>
384 <div class="section"><h4><a id="ResultsList" shape="rect"><span class="secnum">2.1.10. </span>Results List</a></h4>
385 <p>The Results List object is a
386 container for formal results of the job. Its children may be any
387 objects resulting from the computation that may be fetched from the
388 service when the job has completed.</p>
389 <p>Reading the Results List itself
390 enumerates the available or expected result objects.</p>
391 <p>The children of the Results List may
392 be read but not updated or deleted. The client cannot add anything
393 to the Results List.</p>
394 </div>
395 <div class="section"><h4><a id="ResultsList2" shape="rect"><span class="secnum">2.1.11. </span>Parameter List</a></h4>
396 <p>The Parameter List is an
397 enumeration of 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 "parameter" that was that XML document. For services where the JDL consists of a list of name/value pairs (typical of the standard IVOA "simple" access protocols), then these would naturally be expressed in the parameter list. Each parameter value may be expressed either directly as the content of the parameter element, or the value expressed "by reference", where there returned parameter value is a URL that points to the location where the actual parameter value is stored.</p>
398 <p>A particular implementation of UWS may choose to allow the parameters to be updated (but not created) after the initial job creation step, whilst the PHASE is in the PENDING state. It is up to the individual implementation to specify exactly how these parameters may be updated, but good practice (in the REST binding) would be to choose one of the following options.</p>
399 <ol><li>HTTP POST an <i>application/x-www-form-urlencoded</i><b> </b>parameter name, value pair to either
400 <ol><li>/{jobs}/{job-id}</li><li>/{jobs}/{job-id}/parameters</li></ol>
401 </li><li>HTTP PUT the parameter value to /{jobs}/{job-id}/parameters/(parameter-name)</li></ol>
402 <p>Additionally a particular implementation of UWS may allow the "job control" parameters (see section <span class="xref"><a href="#jobcontrol">2.2.3</a></span>) to be specified as part of the JDL. If doing this then the implementation must document the possibility and must use the standard parameter names (which may cause a conflict with parameters in the JDL, which is one of the reasons for the two stage job creation pattern of UWS).</p>
403 </div>
404 </div>
405 <div class="section"><h3><a id="RESTbinding" shape="rect"><span class="secnum">2.2. </span>The REST Binding</a></h3>
406 <p>In order to create a usable service the objects discussed in the section above must be exposed in a particular interface which can be addressed over a particular transport mechanism - this combination is known as a "binding". In this version of the UWS pattern only a REST (Representational State
407 Transfer) style binding <cite>[<a href="#fielding00">fielding00</a>]</cite>is presented, however, future versions of this document may add other bindings. It should be noted that REST is based on HTTP <cite>[<a href="#std:http">std:http</a>]</cite> and as such the REST binding inherits standard HTTP behaviours. In particular it should be noted that the REST binding makes use of HTTP status codes to control the behaviour of the client, especially the "300" class redirection codes to ensure that the client requests particular resources after state changing operations. If a request is made to a resource that does not exist (e.g. an non-existent job-id) then a 404 error should be returned, or if a request is made that is illegal for the current state of the UWS then a 403 status should be returned. If for some reason there is a complete failure in the underlying UWS machinery then a 500 "internal server error" status should be returned. However individual job failures are indicated by setting the appropriate parts of the job representation to error statuses and a request for the individual job object representation at /{jobs}/{job-id} should have a normal 200 status code response.</p>
408
409 <div class="section"><h4><a id="resourceuri" shape="rect"><span class="secnum">2.2.1. </span>Resources and URIs</a></h4>
410 <p>In a REST (Representational State
411 Transfer) binding of UWS, each of the objects defined above is
412 available as a web resource with its own URI. These URIs must form a
413 hierarchy as shown in the table below:</p>
414 <table border="1" cellpadding="2" cellspacing="0">
415 <tr>
416 <th scope="col" rowspan="1" colspan="1">URI</th>
417 <th scope="col" rowspan="1" colspan="1">Description</th>
418 <th scope="col" rowspan="1" colspan="1">Representation</th>
419 </tr>
420 <tr>
421 <td rowspan="1" colspan="1">/{jobs}</td>
422 <td rowspan="1" colspan="1">the Job List</td>
423 <td rowspan="1" colspan="1">the <span class="xmlelement">&lt;jobs&gt;</span>
424 element in the UWS schema </td>
425 </tr>
426 <tr>
427 <td rowspan="1" colspan="1">/{jobs}/{job-id}</td>
428 <td rowspan="1" colspan="1">a Job</td>
429 <td rowspan="1" colspan="1"><p>
430 the <span class="xmlelement">&lt;job&gt;</span> element in the
431 UWS schema<br clear="none" />
432 </p></td>
433 </tr>
434 <tr>
435 <td rowspan="1" colspan="1">/{jobs}/{job-id}/phase</td>
436 <td rowspan="1" colspan="1">the Phase of job {job-id}</td>
437 <td rowspan="1" colspan="1">One of the fixed strings</td>
438 </tr>
439 <tr>
440 <td rowspan="1" colspan="1">/{jobs}/{job-id}/executionduration</td>
441 <td rowspan="1" colspan="1">the maximum execution duration
442 of {job-id}</td>
443 <td rowspan="1" colspan="1">Integer number of seconds.</td>
444 </tr>
445 <tr>
446 <td rowspan="1" colspan="1">/{jobs}/{job-id}/destruction</td>
447 <td rowspan="1" colspan="1">the destruction instant for
448 {job-id}</td>
449 <td rowspan="1" colspan="1"><cite>[<a href="#std:iso8601">std:iso8601</a>]</cite>. If no destruction time then return empty string.</td>
450 </tr>
451 <tr>
452 <td rowspan="1" colspan="1">/{jobs}/{job-id}/error</td>
453 <td rowspan="1" colspan="1">any error message associated
454 with {job-id}</td>
455 <td rowspan="1" colspan="1">any representation appropriate
456 to the implementing service</td>
457 </tr>
458 <tr>
459 <td rowspan="1" colspan="1">/{jobs}/{job-id}/quote</td>
460 <td rowspan="1" colspan="1">the Quote for {job-id}</td>
461 <td rowspan="1" colspan="1"><cite>[<a href="#std:iso8601">std:iso8601</a>]</cite> If no quote available then return empty string.</td>
462 </tr>
463 <tr>
464 <td rowspan="1" colspan="1">/{jobs}/{job-id}/results</td>
465 <td rowspan="1" colspan="1">any results of the job {job-id}</td>
466 <td rowspan="1" colspan="1">the <span class="xmlelement">&lt;results&gt;</span>
467 element in the UWS schema. </td>
468 </tr>
469 <tr>
470 <td rowspan="1" colspan="1">/{jobs}/{job-id}/parameters</td>
471 <td rowspan="1" colspan="1">any parameters for the job
472 {job-id}</td>
473 <td rowspan="1" colspan="1">the <span class="xmlelement">&lt;parameters&gt;</span>
474 element in the UWS schema. </td>
475 </tr>
476 <tr>
477 <td rowspan="1" colspan="1">/{jobs}/{job-id}/owner</td>
478 <td rowspan="1" colspan="1">the owner of the job {job-id}</td>
479 <td rowspan="1" colspan="1">an appropriate identifier as
480 discussed in section <span class="xref"><a href="#security">3</a></span> </td>
481 </tr>
482 </table>
483 <p>The service implementer is free to
484 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
485 of the UWS standard.</p>
486 <p>The URI for the Job List, in its
487 absolute form is the root URI for the whole UWS. This URI should be
488 given as the access URL in the UWS registration.</p>
489 <p>The string representation of instants of time follow <cite>[<a href="#std:iso8601">std:iso8601</a>]</cite> with the following additional constraints;</p>
490 <ol>
491 <li>A character 'T' must be used to separate the date and the time.</li>
492 <li>Times must be expressed in the UTC timezone, and this is signified with the 'Z' timezone designator.</li>
493 </ol>
494 <div class="section"><h4><a id="versioning" shape="rect"><span class="secnum">2.2.1.1. </span>Determining the Protocol Version</a></h4>
495 <p> A client may determine the UWS protocol version of the server using VOSI mechanisms (see <cite>[<a href="#std:vosi">std:vosi</a>]</cite> and <cite>[<a href="#std:stdregext">std:stdregext</a>]</cite>) where the standardID has the value <span class="xmlelement">ivo://ivoa.net/std/UWS#rest-1.1</span> for the REST interface of UWS 1.1 as defined in this document. UWS 1.0 did not explicitly define the standardID to be used, but if desired to use VOSI mechanisms with an existing 1.0 server then the above standardID with "1.1" replaced by "1.0" should be used.</p>
496 <p>In addition it is possible for a client to examine the version attribute on the topmost element that is returned in the UWS xml responses at /{jobs} and /{jobs}/{job-id}. Note that although this version attribute is marked as "optional" in the schema (for maintaining formal backwards compatibility), a UWS 1.1 compliant server must set the attribute value to "1.1" so that a client may deduce that absence of the attribute implies that it is communicating with a UWS 1.0 compliant server.</p>
497 </div>
498 <div class="section"><h4><a id="blocking" shape="rect"><span class="secnum">2.2.1.2. </span>Blocking Behaviour</a></h4>
499 <p>UWS 1.1 introduces blocking behaviour where the server may defer returning the result of a request (i.e. block) under certain circumstances. The purpose of this functionality is to allow the client to be able to do a
500 "slow poll" of the Job status whilst the job is running. The advantage for the client is that it can know almost immediately when a job has results without having to execute polling
501 with a very short timescale - this also has advantages for the server in terms of reduced network traffic. The blocking behaviour is restricted to the <code> /{jobs}/{job-id} </code>endpoint, and is invoked by adding a <code>?WAIT</code> query parameter to the GET request to that endpoint. When the server receives such a request it should not return a response (i.e. it should block)
502 until there is some significant change in the job status, which means that, at a minimum, it must return when the Job Phase changes. The server, however, may block only when in one of the "active" phases (PENDING, QUEUED or EXECUTING), and otherwise must return immediately, even if a blocking request is made, to avoid the possibility of a client waiting indefinitely. The <code>?WAIT</code> query parameter must be assigned an integer value e.g. <code>?WAIT=60</code> which is be interpreted as a maximum time to block in seconds - in this case the server must return after the given value of seconds whether there has been a significant change of Job status or not.
503 A <code>?WAIT=-1</code> should be interpreted as block indefinitely until Job status change.</p>
504 <p>The server must support an additional mechanism which uses a ?PHASE query parameter to avoid any possible race conditions where the job has changed PHASE from what the client last polled before issuing a blocking request. If the client uses a ?PHASE query parameter in the blocking request e.g. <code>/{jobs}/{job-id}?WAIT=30&amp;PHASE=QUEUED</code> then the server must return immediately (i.e. not block intentionally) if the PHASE is not in specified state.</p>
505 <p>As one of the primary goals of UWS is to provide support for long running processes that might outlive the typical TCP connection timeouts (see section <span class="xref"><a href="#Introduction">1</a></span>),
506 a UWS server should respond to a blocking request within the typical TCP connection timeout even when an indefinite wait time has been specified. In addition the UWS server may impose a maximum blocking time (which it does by simply returning when this time is reached whatever the request) if it detects that it is running out of resouces because of a high load imposed by a large number of clients - i.e. a client must not assume that the server will definitely block unitl there is a PHASE change, it may return earlier.</p>
507 <p>A client that is UWS1.1 compliant should also be aware that it will receive immediate responses if it attempts to
508 perform this operation on a UWS 1.0 server.</p>
509 </div>
510
511 <p>&nbsp;</p>
512 </div>
513 <div class="section"><h4><a id="d1e603" shape="rect"><span class="secnum">2.2.2. </span>Representations of resources</a></h4>
514 <p>Each of the UWS objects is mapped to a resource URI as detailed in the table above, and for each URI, a HTTP GET
515 fetches a representation of that resource. In general where an object is a container for other objects (Job List, Job, Result List, Parameter List) then an XML representation of the object should be returned, otherwise for simple atomic types (Quote, Execution Duration etc.) a textual (mime type "text/plain") representation should be returned. The XML schema for the various objects described above is
516 detailed in appendix
517 <span class="xref"><a href="#UWSSchema">B</a></span>
518 of this specification. This schema is the definitive description of the exact form of the XML returned by a UWS and must not vary between implementations.</p>
519 <p>HTTP allows multiple representations
520 of a resource distinguished by their MIME types and selected by the
521 HTTP "Accept" headers of a GET request. A UWS implementation can exploit this to support both web
522 browsers and rich clients in the same tree of resources. Although the default behaviour is to return XML, a UWS could return HTML or XHTML to
523 clients that accept these types. These clients are assumed to be web
524 browsers and the UWS is generating its own user interface. The HTML
525 interface generated should allow full control of the UWS via the use
526 of HTML forms and appropriate links.</p>
527 <p>Clients which are assumed to be part
528 of remote applications that drive UWS without showing the details to
529 their users should accept only "application/xml,text/plain". A UWS must therefore
530 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>
531 <p>More detail for some of the UWS objects is provided below.</p>
532 <div class="section"><h4><a id="jobList" shape="rect"><span class="secnum">2.2.2.1. </span>Job List</a></h4>
533 <p>The representation of the Job List is
534 a list <span class="xmlelement">ShortJobDescription</span> type, which consists of a link to an existing job as well as optional runId (section <span class="xref"><a href="#runId">2.1.9</a></span>) and ownerId (section <span class="xref"><a href="#ownerId">2.1.8</a></span>) elements. The service should return a list (which may be empty) of all the jobs (except for jobs in the "ARCHIVED" phase for backward compatibility) that the client can see in the current security context (see section <span class="xref"><a href="#security">3</a></span>), however large the number of jobs. In order possibly to reduce such a large number of jobs in the job list,
535 the server should respond to a request from the client to filter the jobs shown by using URL query parameter on the PHASE for example</p>
536 <pre xml:space="preserve"><code>/{jobs}?PHASE=EXECUTING</code>
537 </pre>
538 <p>would list only the jobs in an EXECUTING state. If the PHASE filtering parameter is repeated, then the service should list all the jobs in the union of the repeated PHASEs.
539 The only way to list any jobs in the "ARCHIVED" phase is to use this mechanism.</p>
540 <p>Other filters based on time base propertied of a job that that server should recognise on the job list are</p>
541 <ul>
542 <li><code>/{jobs}?AFTER=2014-09-10T10:01:02.000Z</code> The server should only list jobs with creationTimes after the given <cite>[<a href="#std:iso8601">std:iso8601</a>]</cite> date and time in UTC.</li>
543 <li><code>/{jobs}?LAST=100</code> The server should list only the given number (an integer greater than 0) of most recent jobs ordered by descending creationTimes.</li>
544 </ul>
545 <p>If multiple filters are specified by the client, then the server should return a jobs list which is the result of a logical AND of the various filter conditions. A server may use the LAST filter in a 303 redirection response if it is desired to limit the size of the default returned list after operations that result in a return to the job list (see section <span class="xref"><a href="#RESTbinding">2.2</a></span>). The size of the returned list should be large enough that all active jobs are likely to be returned. A client can deduce that there might be further jobs in the job list by parsing this returned URL.</p>
546 </div>
547 <div class="section"><h4><a id="jobobj" shape="rect"><span class="secnum">2.2.2.2. </span>Job</a></h4>
548 <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 appendix <span class="xref"><a href="#UWSSchema">B</a></span>.
549 An example of such a job instance is shown below</p>
550 <div><!--The contents of this div are automatically generated from the following processing instruction when processed with ivoarestructure.xsl-->
551 <?incxml href="../UWSJobInstance.xml" ?><h:div xmlns:h="http://www.w3.org/1999/xhtml" class="viewxml"><div class="element"><span class="markup">&lt;</span><span class="start-tag">uws:job</span> <span class="attribute-name">version</span><span class="markup">=</span><span class="attribute-value">"1.1"</span> <span class="attribute-name">xsi:schemaLocation</span><span class="markup">=</span><span class="attribute-value">"http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd"</span> <span class="attribute-name">xmlns:xml</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/XML/1998/namespace"</span> <span class="attribute-name">xmlns:uws</span><span class="markup">=</span><span class="attribute-value">"http://www.ivoa.net/xml/UWS/v1.0"</span> <span class="attribute-name">xmlns:xlink</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/1999/xlink"</span> <span class="attribute-name">xmlns:xsi</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/2001/XMLSchema-instance"</span> <span class="attribute-name">xmlns:uwsc</span><span class="markup">=</span><span class="attribute-value">"urn:uwscustom"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><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="element"><span class="markup">&lt;</span><span class="start-tag">uws:runId</span><span class="markup">&gt;</span><span class="text">myjobref</span><span class="markup">&lt;/</span><span class="end-tag">uws:runId</span><span class="markup">&gt;</span></div><div class="element"><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">"true"</span><span class="markup">/&gt;</span></div><div class="element"><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="element"><span class="markup">&lt;</span><span class="start-tag">uws:creationTime</span><span class="markup">&gt;</span><span class="text">2009-05-19T17:01:44.038Z</span><span class="markup">&lt;/</span><span class="end-tag">uws:creationTime</span><span class="markup">&gt;</span></div><div class="element"><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.038Z</span><span class="markup">&lt;/</span><span class="end-tag">uws:startTime</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">uws:endTime</span><span class="markup">&gt;</span><span class="text">2009-05-19T17:12:49.041Z</span><span class="markup">&lt;/</span><span class="end-tag">uws:endTime</span><span class="markup">&gt;</span></div><div class="element"><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="element"><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.035Z</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"><div class="element"><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">"scaleFactor"</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="element"><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">"image"</span> <span class="attribute-name">byReference</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">&gt;</span><span class="text">
552 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></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"><div class="element"><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">"correctedImage"</span> <span class="attribute-name">xlink:href</span><span class="markup">=</span><span class="attribute-value">"http://myserver.org/uws/jobs/jobid123/result/image"</span> <span class="attribute-name">size</span><span class="markup">=</span><span class="attribute-value">"3000960"</span> <span class="attribute-name">mime-type</span><span class="markup">=</span><span class="attribute-value">"image/fits"</span> <span class="attribute-name">uwsc:anyattribute</span><span class="markup">=</span><span class="attribute-value">"a custom attribute"</span><span class="markup">/&gt;</span></div></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">"transient"</span> <span class="attribute-name">hasDetail</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><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><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="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">any</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xml</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">thatyouwant</span><span class="markup">/&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xml</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">any</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">uws:jobInfo</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">uws:job</span><span class="markup">&gt;</span></div></h:div>
553 <!--end of autogenerated content--></div>
554
555
556
557
558
559
560
561 <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>
562 </div>
563 <div class="section"><h4><a id="resultList" shape="rect"><span class="secnum">2.2.2.3. </span>Results List</a></h4>
564 <p>The representation of a Results List
565 is a list of <span class="xmlelement">ResultReference</span> types, which consist of links to the actual resources which are the results as well as optional size and mime-type attribute which may be used to indicate result properties before actually fetching the result. The linked
566 resources may have any URI and any MIME type. A sensible default for
567 their URIs is to make them children of /{jobs}/{job-id}/results, but
568 this is not required. It may sometimes be easier for a service
569 implementer to point to a resource on some web server separate from
570 that running the UWS. Therefore, a client must always parse the
571 Results List to find the results. Each result in a result list must be given a unique identifier. Where a protocol applying UWS
572 specifies standard results it must do so fixing the identifier for those results and fixing the result URIs, however the UWS must still return a valid Results List at /{jobs}/{job-id}/results, even though in this case the identifiers and URIs could be precomputed by the client.</p>
573 </div>
574 <div class="section"><h4><a id="d1e1353" shape="rect"><span class="secnum">2.2.2.4. </span>Parameters List</a></h4>
575 The representation of the parameters list is a list of
576 <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 "true".</div>
577 <div class="section"><h4><a id="d1e1556" shape="rect"><span class="secnum">2.2.2.5. </span>Error</a></h4>
578 <p>When an error occurs in a job the UWS must signal this at a minimum by setting the PHASE to error. In addition the <span class="xmlelement">&lt;errorSummary&gt;</span> element, giving a brief summary of the error, should be included within the <span class="xmlelement">&lt;job&gt;</span> element. The UWS may include a more detailed error message for example an execution log or stack trace by providing such a resource at the /{jobs}/{job-id}/error URI. It is the responsibility of the implementing service to specify the form that such an error message may take.</p>
579 </div>
580 </div>
581 <div class="section"><h4><a id="jobcontrol" shape="rect"><span class="secnum">2.2.3. </span>State changing requests</a></h4>
582 <p>Certain of the UWS' resources accept
583 HTTP POST and DELETE messages to change the state of the service –
584 This is the fundamental way that a client controls the execution of a
585 job. In most of the cases where a job sub-object is set the response
586 will have a http 303 “See other” status and a Location header
587 that points back to the main job summary obtained at the <span style="font-weight: medium">/{jobs}/{job-id}
588 URI. The job summary contains the values of (or links to) all the UWS objects
589 within the returned XML (or XHTML). This mode of operation was chosen
590 (as opposed to returning only the sub-object being altered) as it
591 makes for a more natural user interface – especially in the case of
592 the XHMTL interface. A client that wants to obtain only the value of
593 a particular sub-object can at any time request that sub-object with
594 a HTTP GET.</span></p>
595 <div class="section"><h4><a id="jobCreation" shape="rect"><span class="secnum">2.2.3.1. </span>Creating a Job</a></h4>
596 <p>POSTing a request to the Job List
597 creates a new job (unless the service rejects the request). The
598 response when a job is accepted must have code 303 “See other”
599 and the Location header of the response must point to the created
600 job. The response when the job is rejected should be a HTTP 403 Forbidden status style response.</p>
601 <p>This initial POST will in most cases
602 carry parameters for the protocol that is using the UWS pattern, as
603 detailed in <span class="xref"><a href="#ApplicationsOfUWS">4</a></span>
604 .In addition for the initial post may contain job control parameters if allowed by the implementing protocol
605 (i.e. if UWS job control parameter names do not clash with the implementing protocol parameters). One use of this
606 facility might be to have the job placed into a potentially running state by adding ?PHASE=RUN query part to the job creation URL.</p>
607 <div class="section"><h4><a id="d2e1612" shape="rect"><span class="secnum">2.2.3.1.1. </span>Inline Parameters</a></h4>
608 <p>The JDL may allow parameter values to be uploaded in-line - in this case the UWS should accept the parameter content as multipart/form-data encoded in the POST with the formal value of the parameter being a "byReference" type using the special URI scheme "param" with the path part of the URI matching the name attribute of the multipart/form-data encoding content part. The content of such an in-line parameter should be made available as part of the job resource tree at /{jobs}/{job-id}/parameters/{parameter-name}, and then described as a "byReference" parameter in the <span class="xmlelement">&lt;job&gt;</span> XML description.</p>
609 </div>
610 <p>&nbsp;</p>
611 </div>
612 <div class="section"><h4><a id="d1e1390" shape="rect"><span class="secnum">2.2.3.2. </span>Deleting a Job</a></h4>
613 <p>Sending a HTTP DELETE to a Job
614 resource destroys that job, with the meaning noted in the definition
615 of the Job object, above. No other resource of the UWS may be
616 directly deleted by the client. The response to this request must
617 have code 303 “See other” and the Location header of the response
618 must point to the Job List at the /{jobs} URI.</p>
619 <p>Posting a request with a parameter
620 ACTION=DELETE to the Job also destroys the job, the response being as
621 for a deletion. This action supports web browsers which typically
622 cannot send DELETE requests.</p>
623 </div>
624 <div class="section"><h4><a id="d1e1402" shape="rect"><span class="secnum">2.2.3.3. </span>Changing the Destruction Time</a></h4>
625 <p>The Destruction Time may be changed
626 by POSTing to /{jobs}/{job-id}/destruction. In this case, the body
627 of the posted request is of type <i>application/x-www-form-urlencoded</i><b> </b><span style="font-weight: medium">and
628 contains the parameter named DESTRUCTION whose value is the new
629 destruction time in ISO8601 format; i.e. this request is what an HTML
630 form sends.</span></p>
631 <p style="font-weight: medium">The
632 response to this request must have code 303 “See other” and the
633 Location header of the response must point to the /{jobs}/{job-id}
634 URI so that the client receives the value that the service has
635 actually set the Destruction Time to within the Job summary response. The service may override the requested Destruction Time and substitute a value of its choosing e.g. a job owner may have reached his storage quota and so the service only allows further data to be stored for shorter times than requested.</p>
636 </div>
637 <div class="section"><h4><a id="d1e1420" shape="rect"><span class="secnum">2.2.3.4. </span>Changing the Execution Duration</a></h4>
638 <p>The Execution Duration may be changed
639 by POSTing to /{jobs}/{job-id}/executionduration. In this case, the body
640 of the posted request is of type <i>application/x-www-form-urlencoded</i><b> </b><span style="font-weight: medium">and
641 contains the parameter named EXECUTIONDURATION whose value is the new
642 executionduration in seconds.</span></p>
643 <p style="font-weight: medium">The
644 response to this request must have code 303 “See other” and the
645 Location header of the response must point to the
646 /{jobs}/{job-id} so that the client receives the value that the
647 service has actually set the Execution Duration to. The service may to override the request and substitute a value of its choosing</p>
648 </div>
649 <div class="section"><h4><a id="d1e1439" shape="rect"><span class="secnum">2.2.3.5. </span>Starting a Job</a></h4>
650 <p style="font-weight: medium">A
651 job may be started by POSTing to the /{jobs}/{job-id}/phase URI. The
652 POST contains a single parameter PHASE=RUN which instructs the UWS to
653 attempt to start the job. The response to this request must have code
654 303 “See other” and the Location header of the response must
655 point to the /{jobs}/{job-id} URI so that the client receives the
656 phase that the job has been set to. Typically a UWS will put a job
657 into a QUEUED state on receipt of this command, but depending on how
658 busy the server is, the job might be put almost immediately (and
659 without client intervention) into an EXECUTING state.</p>
660 </div>
661 <div class="section"><h4><a id="d1e1448" shape="rect"><span class="secnum">2.2.3.6. </span>Aborting a Job</a></h4>
662 <p style="font-weight: medium">A
663 job may be aborted by POSTing to the /{jobs}/{job-id}/phase URI. The
664 POST contains a single parameter PHASE=ABORT which instructs the UWS
665 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
666 code 303 “See other” and the Location header of the response must
667 point to the /{jobs}/{job-id} URI so that the client receives the
668 phase that the job has been set to.</p>
669 </div>
670 </div>
671 <div><span class="section"><h4><a id="d1e708" shape="rect"><span class="secnum">2.2.4. </span>Message pattern</a></h4>
672 <p>The REST binding results in the
673 message pattern shown in figure 2.</p>
674 <p><i>Illustration 2:
675 Typical calling sequence for the REST binding of UWS</i></p>
676 <p><img src="Sequence_Diagram__UWS__Rest_Message_Pattern__Rest_Message_Pattern__Rest_Message_Pattern.png" width="100%" id="graphics3" alt="rest message pattern" /></p>
677 Note that UWS 1.1 introduces a blocking behavior on the polling (step 11 in the diagram) that is described further in section </span><span class="xref"><a href="#blocking">2.2.1.2</a></span><span class="section">.<br style="clear: both;" clear="none" />
678 </span></div>
679 </div>
680 </div>
681 <div class="section"><h2><a id="security" shape="rect"><span class="secnum">3. </span>Security Considerations (normative)</a></h2>
682 <p>A UWS should follow IVOA standards for security <cite>[<a href="#std:ssoauth">std:ssoauth</a>]</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 <span class="xref"><a href="#RESTbinding">2.2</a></span>
683 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>
684 <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>
685 </div>
686 <div class="section"><h2><a id="ApplicationsOfUWS" shape="rect"><span class="secnum">4. </span>Applications of UWS (informative)</a></h2>
687 <p>The UWS pattern leaves undefined two
688 essential parts of the service contract: the content that must be
689 posted to create a job; and the pattern of results made available by
690 a completed job. An application of UWS completes a service contract
691 by defining these matters.</p>
692 <p>There follow some use cases applying
693 the UWS pattern. The descriptions are neither formal nor complete.
694 The intention is to show a range of ways that the pattern can be
695 applied without burdening the reader with the level of detail needed
696 for a standard implementation.</p>
697 <p>Any of these cases could be worked up
698 into a full IVOA standard by formalizing the description, adding
699 detail and generally making the specification more
700 exact and complete.</p>
701 <div class="section"><h3><a id="Imageservice" shape="rect"><span class="secnum">4.1. </span>Image service with data staging</a></h3>
702 <p>Consider a service that computes
703 images from archive data. The computation takes significant time, so
704 the service is asynchronous. The service keeps the computed images in
705 its own storage until the user downloads them; this is essentially
706 the model of SIAP <cite>[<a href="#std:siap">std:siap</a>]</cite>.</p>
707 <p>The asynchronous image-service is a
708 logical extension of a synchronous SIA service. Therefore it uses the
709 REST binding of UWS.</p>
710 <p>The parameters for posting a new job
711 are as for SIAP 1.0:</p>
712 <ul><li>
713 <p>POS, the position on the sky to
714 be searched.</p>
715 </li><li>
716 <p>SIZE, the size of the search
717 box.</p>
718 </li><li>
719 <p>FORMAT: the type of images to be
720 computed.</p>
721 </li></ul>
722 <p>Particular implementations are free
723 to add extra parameters.</p>
724 <p>These parameters are posted in a
725 document of type <i>application/x-www-form-urlencoded</i><span style="font-style: normal">:
726 i.e. they can be sent from an HTML form.</span></p>
727 <p style="font-style: normal">The
728 images generated by the job are accessible as results. Each
729 image has its own URI and can be downloaded over HTTP at any time
730 until the destruction time of the job. The URIs for the images may be
731 discovered from the Results List in the normal UWS way.</p>
732 <p style="font-style: normal">SIAP
733 1.0 produces, for each query, a table of metadata describing the
734 images. The asynchronous image-service produces a table to the same
735 schema as a result with a fixed identifier, called “table”.</p>
736 <p><span style="font-style: normal">Image
737 results are added to the results list, and to the “table” result,
738 as they are generated. Hence, a client that polls the service can
739 discover, download and use some of the images before the job is
740 finished. </span>If the client is satisfied with
741 these early images, the client can cancel the rest of the job by
742 destroying the job. However, destroying the job deletes the cached
743 images so the client has to download them <i>first</i>.</p>
744 </div>
745 <div class="section"><h3><a id="ADQLservice" shape="rect"><span class="secnum">4.2. </span>ADQL service with cursor</a></h3>
746 <p>ADQL <cite>[<a href="#std:adql">std:adql</a>]</cite> can serve as a JDL. Consider
747 an ADQL service that supports long-running queries as asynchronous
748 operations. In general, the results of the query may be a large set
749 of data. They may be too large to download comfortably. We might like
750 to cache these results on the service and to operate a cursor,
751 drawing down from the resource a few rows of the table at a time.</p>
752 <p>The parameters of a job are as
753 follows:</p>
754 <ul><li>
755 <p>ADQL: the query text</p>
756 </li><li>
757 <p>FORMAT: the format for the
758 results</p>
759 </li></ul>
760 <p>These parameters are posted in a
761 document of type <i>application/x-www-form-urlencoded</i><span style="font-style: normal">:
762 i.e. they can be sent from an HTML form.</span></p>
763 <p style="font-style: normal">A
764 successful query generates the following results:</p>
765 <ul><li>
766 <p style="font-style: normal"><i>table</i>:
767 the whole result set as one file resource.</p>
768 </li><li>
769 <p style="font-style: normal"><i>header</i>:
770 the metadata for the output table.</p>
771 </li><li>
772 <p style="font-style: normal"><i>cursor</i>:
773 a selection of rows of output.</p>
774 </li></ul>
775 <p>The <i>cursor</i> result is
776 parameterised by the query parameters FIRST and LAST in the query
777 string of its URI: these parameters state the index of the first and
778 last row to be returned; e.g.</p>
779 <p> http://whatever.org/adlqService/results/cursor?FIRST=1&amp;LAST=100</p>
780 <p>If the parameters are missing, the
781 service decides which rows to return.</p>
782 </div>
783 <div class="section"><h3><a id="ParameterizedApplications" shape="rect"><span class="secnum">4.3. </span>Parameterised applications</a></h3>
784 <p>There is a class of applications on
785 which a job may be defined by a list of simple parameters. “Simple”
786 here means unstructured: a scalar value such as a number, a string of
787 text or a boolean value. If the parameters are allowed to be file name,
788 so that structured data are passed indirectly, then the class of
789 applications is very large indeed. Almost any non-interactive
790 application can be driven in this way.</p>
791 <p>Turning each application of choice
792 into a service (with or without UWS semantics) would be onerous.
793 However, if the application’s interface is entirely characterized,
794 through the JDL, in terms of typed input and output parameters, then
795 one service contract will work for all the applications and a single
796 implementation of the contract can be reused for all cases.</p>
797 <p>AstroGrid’s Common Execution
798 Architecture (CEA) <cite>[<a href="#harrison05">harrison05</a>]</cite> works in this way. It has just one service
799 contract for all applications (including ADQL services; the ADQL
800 query is passed in the list of parameters). It has four
801 implementations, one for each of the possible interfaces between the
802 service and a kind of job (jobs can be implemented with Java classes,
803 command-line applications, HTTP-get services or JDBC databases). CEA
804 also specifies stateful, asynchronous services and makes use of
805 VOSpace.</p>
806 <p>Consider a CEA reworked to use the
807 UWS pattern for consistency with other (future) IVOA standards. Call
808 it CEA v2 to distinguish it from CEA v1 as currently maintained by
809 AstroGrid. For this example, consider the particular kind of CEA
810 service that runs applications supplied as executable binaries.</p>
811 <p>A binary application-server has a
812 library of applications co-located with its service and defined in
813 the service configuration set by the service provider. It does not
814 accept code from the client for local execution.</p>
815 <p>The JDL in CEA v2 is similar to that
816 in CEA v1. It is a formal XML vocabulary for expressing choice
817 of application and parameter lists <cite>[<a href="#std:vocea">std:vocea</a>]</cite>. Parameters may be inputs or
818 outputs of the job.</p>
819 <p>To start a job, a document in this
820 JDL is posted to the UWS. The document is sent in its native
821 MIME-type, application/xml, so this is not an interface that can be
822 driven directly from an HTML form, although it can be driven from the
823 other markup such as XForms technology<cite>[<a href="#std:xform">std:xform</a>]</cite>.</p>
824 <p>The results of the job depend on the
825 choice of application. They are all results whose identifiers and
826 types are defined in the definition of the application. That
827 application-definition is registered, so the client knows before
828 running the job what results to expect.</p>
829 <p>CEA input-parameters may be indirect:
830 i.e. they may refer to data in on-line storage. In this case, the JDL
831 document contains the URIs for those data objects Alternatively, the
832 parameters may be direct, in which case the JDL contains the actual
833 value of the parameters.</p>
834 <p>Similarly, CEA results may be made
835 indirect. In this case, the results are named as parameters in the
836 JDL where the values are the URIs to which the results are delivered.
837 The application server can then stream the results to the specified
838 destination as they become available and need not cache them locally.
839 If a job result is indirect, then the server can choose whether or
840 not to keep a local copy. If it chooses not to cache locally, then
841 the result URI in the UWS is set to the external location named in
842 the URI.</p>
843 </div>
844 </div>
845 <div class="section"><h2><a id="SynchronousService" shape="rect"><span class="secnum">5. </span>Implementing a Synchronous Service on top of UWS (informative)</a></h2>
846 <p>Whilst the provision of synchronous
847 services is not one of the design aims of the UWS pattern, there is
848 clearly a desire in second generation IVOA services still to allow a
849 simple synchronous calling pattern to be available to simple clients.
850 What follows is a recommended recipe for putting a synchronous facade
851 on UWS;</p>
852 <p>It is assumed that the core of the
853 service does provide a true UWS compliant set of endpoints rooted at
854 /async (equivalent to the /{jobs} endpoint in the nomenclature used
855 above). The desired synchronous service is to be rooted at /sync.</p>
856 <ol><li>
857 <p>The job is started by either a
858 GET (for compatibility with existing IVOA standards) or a POST
859 (preferably) of form encoded parameters to the /sync endpoint.</p>
860 </li><li>
861 <p>Internally the service creates a
862 job in the standard UWS system with the given parameters and sets
863 the PHASE to RUN, noting the returned job identifier which we will
864 call {job-id}. The /sync endpoint then responds with a STATUS 303
865 (redirection) response to the URL /sync/{job-id}.</p>
866 </li><li>
867 <p>The /sync/{job-id} endpoint then
868 blocks until it detects that the underlying job has finished at
869 which point it responds with a STATUS 303 (redirection) to the
870 /{jobs}/{job-id}/results/mainresult URL, where “mainresult” is
871 the name of the primary result of the job.</p>
872 </li></ol>
873 <p>In this way the service appears to be
874 a synchronous to the original client – assuming it obeys standard
875 HTTP redirection semantics, so a simple client like a web browser
876 could obtain the result with a single “click”. At the same time a
877 more sophisticated, UWS aware, client could control the same job from
878 the standard /{jobs} endpoint – indeed if the synchronous call
879 timed out for some reason, then it would be possible for the original
880 client to retrieve the results by looking at the /{jobs}/{job-id} URL
881 tree, because it could make the association of the job-Id from the
882 URL it receives in step 2 above.</p>
883 <p>The purely synchronous client is
884 restricted compared with the full UWS pattern in that there can only
885 be one result directly returned to the client, as noted in stage 3
886 above. This is usually not a problem for compatibility with existing
887 version 1.0 DAL services as they typically return a single VOTable
888 containing references to the desired data.</p>
889 </div>
890
891 <div class="appendices"><h2><a name="Appendices" id="Appendices" shape="rect"></a>Appendices</h2>
892
893 <div class="section"><h2><a id="Updates" shape="rect"><span class="secnum">A. </span>Updates from previous versions</a></h2>
894 <div class="section"><h3><a id="d1e1112" shape="rect"><span class="secnum">A.1. </span>At Version 0.5</a></h3>
895 <ul><li>
896 changed the POST parameter names
897 to be the same as the resource paths.
898 </li><li>
899 added synchronous section.
900 </li><li>
901 updated SOAP binding section
902 </li></ul>
903 </div>
904 <div class="section"><h3><a id="d1e1775" shape="rect"><span class="secnum">A.2. </span>At Version 1.0</a></h3>
905 <ul>
906 <li>Removed all SOAP binding.</li>
907 <li>Added parameterList</li><li>Added ownerId and jobId as subsidiary job object</li></ul>
908 </div>
909 <div class="section"><h3><a id="ver11" shape="rect"><span class="secnum">A.3. </span>At Version 1.1</a></h3>
910 <p>This version is intended to clarify use, and add a small number of facilities that should not break existing 1.0 clients.
911 The enhancements that have been added are</p>
912 <ul>
913 <li>Informative section on how to start a job in a
914 running state - <span class="xref"><a href="#jobCreation">2.2.3.1</a></span> </li>
915 <li>Added the ability to filter on the job list - <span class="xref"><a href="#jobList">2.2.2.1</a></span></li>
916 <li>Added a new phase "ARCHIVED" - <span class="xref"><a href="#ExecutionPhase">2.1.3</a></span> and <span class="xref"><a href="#jobList">2.2.2.1</a></span></li>
917 <li>Added blocking behaviour to allow "slow poll" by clients - <span class="xref"><a href="#blocking">2.2.1.2</a></span>.</li>
918 <li>Added optional size and mime-type attributes to the <span class="xmlelement">ResultReference</span> - <span class="xref"><a href="#resultList">2.2.2.3</a></span></li>
919 <li>Added a version attribute to UWS responses - <span class="xref"><a href="#versioning">2.2.1.1</a></span></li>
920 <li>Added the creationTime property which represents the instant that a job is created - Appendix <span class="xref"><a href="#UWSSchema">B</a></span></li>
921 <li>Added optional runId, ownerId and creationTime elements to the job list - <span class="xref"><a href="#jobList">2.2.2.1</a></span></li>
922 <li>Clarified timezone handling - <span class="xref"><a href="#resourceuri">2.2.1</a></span></li>
923 </ul>
924 </div>
925 </div>
926
927 <div class="section"><h2><a id="UWSSchema" shape="rect"><span class="secnum">B. </span>UWS Schema</a></h2>
928 <p>Note that this schema can be found on-line at <a href="http://www.ivoa.net/xml/UWS/v1.0" shape="rect">http://www.ivoa.net/xml/UWS/v1.0</a> (i.e. the target namespace
929 can also be used as a URL for the schema.) This location should
930 represent the definitive source, the schema is reproduced below only for
931 completeness of this document.</p>
932 <div><!--The contents of this div are automatically generated from the following processing instruction when processed with ivoarestructure.xsl-->
933 <?incxml href="../UWS.xsd"?><h:div xmlns:h="http://www.w3.org/1999/xhtml" class="viewxml"><div class="comment">&lt;!-- $Revision$ $Date$ $HeadURL$ --&gt;</div><div class="comment">&lt;!-- UWS schema - Paul Harrison May 2008 --&gt;</div><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">"http://www.ivoa.net/xml/UWS/v1.0"</span> <span class="attribute-name">elementFormDefault</span><span class="markup">=</span><span class="attribute-value">"qualified"</span> <span class="attribute-name">attributeFormDefault</span><span class="markup">=</span><span class="attribute-value">"unqualified"</span> <span class="attribute-name">version</span><span class="markup">=</span><span class="attribute-value">"1.1-REC-20161024"</span> <span class="attribute-name">xmlns:xml</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/XML/1998/namespace"</span> <span class="attribute-name">xmlns:xs</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/2001/XMLSchema"</span> <span class="attribute-name">xmlns:uws</span><span class="markup">=</span><span class="attribute-value">"http://www.ivoa.net/xml/UWS/v1.0"</span> <span class="attribute-name">xmlns:xlink</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/1999/xlink"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><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">"http://www.w3.org/1999/xlink"</span> <span class="attribute-name">schemaLocation</span><span class="markup">=</span><span class="attribute-value">"http://www.ivoa.net/xml/Xlink/xlink.xsd"</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">"ShortJobDescription"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:sequence</span><span class="markup">&gt;</span><div class="indent"><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">"phase"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ExecutionPhase"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
934 the execution phase - returned at
935 /{jobs}/{job-id}/phase
936 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"runId"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
937 this is a client supplied identifier - the UWS system
938 does nothing other than to return it as part of the
939 description of the job
940 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"ownerId"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
941 the owner (creator) of the job - this should be
942 expressed as a string that can be parsed in accordance
943 with IVOA security standards. If there was no
944 authenticated job creator then this should be set to
945 NULL.
946 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"creationTime"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"false"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
947 The instant at which the job was created.
948 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:element</span><span class="markup">&gt;</span></div></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">"id"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:JobIdentifier"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"required"</span><span class="markup">&gt;</span><span class="text">
949 </span><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:attributeGroup</span> <span class="attribute-name">ref</span><span class="markup">=</span><span class="attribute-value">"uws:reference"</span><span class="markup">/&gt;</span></div></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">"reference"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">standard xlink references
950 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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">ref</span><span class="markup">=</span><span class="attribute-value">"xlink:type"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"optional"</span> <span class="attribute-name">default</span><span class="markup">=</span><span class="attribute-value">"simple"</span><span class="markup">/&gt;</span></div><div class="element"><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">"xlink:href"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"optional"</span><span class="markup">/&gt;</span></div></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">"ExecutionPhase"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
951 Enumeration of possible phases of job execution
952 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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">"xs:string"</span><span class="markup">&gt;</span><div class="indent"><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">"PENDING"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
953 The first phase a job is entered into - this is where
954 a job is being set up but no request to run has
955 occurred.
956 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"QUEUED"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
957 A job has been accepted for execution but is waiting
958 in a queue
959 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"EXECUTING"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">A job is running</span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"COMPLETED"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
960 A job has completed successfully
961 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"ERROR"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
962 Some form of error has occurred
963 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"UNKNOWN"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
964 The job is in an unknown state.
965 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"HELD"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
966 The job is HELD pending execution and will not
967 automatically be executed - can occur after a
968 PHASE=RUN request has been made (cf PENDING).
969 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"SUSPENDED"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
970 The job has been suspended by the system during
971 execution
972 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"ABORTED"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
973 The job has been aborted, either by user request or by
974 the server because of lack or overuse of resources.
975 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"ARCHIVED"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
976 The job has been archived by the server at destruction time. An archived job
977 may have deleted the results to reclaim resources, but must have job metadata preserved.
978 This is an alternative that the server may choose in contrast to completely destroying all record of the job.
979 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:enumeration</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:restriction</span><span class="markup">&gt;</span></div></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">"JobSummary"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
980 The complete representation of the state of a job
981 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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"><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">"jobId"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:JobIdentifier"</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">"runId"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
982 this is a client supplied identifier - the UWS system
983 does nothing other than to return it as part of the
984 description of the job
985 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"ownerId"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
986 the owner (creator) of the job - this should be
987 expressed as a string that can be parsed in accordance
988 with IVOA security standards. If there was no
989 authenticated job creator then this should be set to
990 NULL.
991 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"phase"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ExecutionPhase"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
992 the execution phase - returned at
993 /{jobs}/{job-id}/phase
994 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"quote"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
995 A Quote predicts when the job is likely to complete -
996 returned at /{jobs}/{job-id}/quote "don't know" is
997 encoded by setting to the XML null value
998 xsi:nil="true"
999 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"creationTime"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"false"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1000 The instant at which the job was created.
1001 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1002 Note that the version 1.1 of the specification requires that this element be present.
1003 It is optional only in versions 1.x of the schema for backwards compatibility.
1004 2.0+ versions of the schema will make this formally mandatory in an XML sense.
1005 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"startTime"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1006 The instant at which the job started execution.
1007 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"endTime"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1008 The instant at which the job finished execution
1009 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"executionDuration"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:int"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"false"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1010 The duration (in seconds) for which the job should be
1011 allowed to run - a value of 0 is intended to mean
1012 unlimited - returned at
1013 /{jobs}/{job-id}/executionduration
1014 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"destruction"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:dateTime"</span> <span class="attribute-name">nillable</span><span class="markup">=</span><span class="attribute-value">"true"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1015 The time at which the whole job + records + results
1016 will be destroyed. returned at
1017 /{jobs}/{job-id}/destruction
1018 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"uws:parameters"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1019 The parameters to the job (where appropriate) can also
1020 be retrieved at /{jobs}/{job-id}/parameters
1021 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"uws:results"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1022 The results for the job - can also be retrieved at
1023 /{jobs}/{job-id}/results
1024 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"errorSummary"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ErrorSummary"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><span class="text">
1025 </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">"jobInfo"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"1"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1026 This is arbitrary information that can be added to the
1027 job description by the UWS implementation.
1028 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:sequence</span><span class="markup">&gt;</span><div class="indent"><div class="element"><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">"##any"</span> <span class="attribute-name">processContents</span><span class="markup">=</span><span class="attribute-value">"lax"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"unbounded"</span><span class="markup">/&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:sequence</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:complexType</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:element</span><span class="markup">&gt;</span></div></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">"version"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:UWSVersion"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"optional"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">note that this attribute is actually required by the 1.1 specification - however remains optional in the schema
1029 for backwards compatibility. It will be formally required in the next major revision.</span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:attribute</span><span class="markup">&gt;</span></div></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">"JobIdentifier"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><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
1030 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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">"xs:string"</span><span class="markup">/&gt;</span></div></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:simpleType</span> <span class="attribute-name">name</span><span class="markup">=</span><span class="attribute-value">"UWSVersion"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">The version of the UWS standard that the server complies with.
1031 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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">"xs:string"</span><span class="markup">/&gt;</span></div></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">"job"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:JobSummary"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><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
1032 when a GET is made for a single job resource - i.e.
1033 /{jobs}/{job-id}</span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"jobs"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><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
1034 /(jobs)</span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">The list presented may be affected by the current security context and may be filtered</span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:sequence</span><span class="markup">&gt;</span><div class="indent"><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">"jobref"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ShortJobDescription"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"unbounded"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">&gt;</span><span class="text">
1035 </span><span class="markup">&lt;/</span><span class="end-tag">xs:element</span><span class="markup">&gt;</span></div></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">"version"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:UWSVersion"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"optional"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">note that this attribute is actually required by the 1.1 specification - however remains optional in the schema
1036 for backwards compatibility. It will be formally required in the next major revision.</span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:attribute</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:complexType</span><span class="markup">&gt;</span></div></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">"ResultReference"</span> <span class="attribute-name">mixed</span><span class="markup">=</span><span class="attribute-value">"false"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><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.
1037 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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">"id"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"required"</span><span class="markup">/&gt;</span></div><div class="element"><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">"uws:reference"</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">"size"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:long"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"optional"</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">"mime-type"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"optional"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:anyAttribute</span> <span class="attribute-name">namespace</span><span class="markup">=</span><span class="attribute-value">"urn:uwscustom"</span> <span class="attribute-name">processContents</span><span class="markup">=</span><span class="attribute-value">"lax"</span><span class="markup">/&gt;</span></div></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">"results"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text"> The element returned for
1038 /{jobs}/{job-id}/results</span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:sequence</span><span class="markup">&gt;</span><div class="indent"><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">"result"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ResultReference"</span> <span class="attribute-name">maxOccurs</span><span class="markup">=</span><span class="attribute-value">"unbounded"</span> <span class="attribute-name">minOccurs</span><span class="markup">=</span><span class="attribute-value">"0"</span><span class="markup">/&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:sequence</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:complexType</span><span class="markup">&gt;</span></div></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">"ErrorSummary"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1039 A short summary of an error - a fuller representation of the
1040 error may be retrieved from /{jobs}/{job-id}/error
1041 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></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"><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">"message"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:string"</span><span class="markup">/&gt;</span></div></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">"type"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"uws:ErrorType"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"required"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:annotation</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">xs:documentation</span><span class="markup">&gt;</span><span class="text">
1042 characterization of the type of the error
1043 </span><span class="markup">&lt;/</span><span class="end-tag">xs:documentation</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">xs:annotation</span><span class="markup">&gt;</span></div></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">"hasDetail"</span> <span class="attribute-name">type</span><span class="markup">=</span><span class="attribute-value">"xs:boolean"</span> <span class="attribute-name">use</span><span class="markup">=</span><span class="attribute-value">"required"</span><span class=<