/[volute]/trunk/projects/grid/vospace/doc/VOSpace2-1.html
ViewVC logotype

Contents of /trunk/projects/grid/vospace/doc/VOSpace2-1.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2606 - (show annotations)
Sat May 10 03:55:30 2014 UTC (6 years, 2 months ago) by major.brian
File MIME type: text/html
File size: 201543 byte(s)
Attempt to set correct content-type on VOSpace2-1.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?><!-- $Id$
2 VOSpace 2.1 WD -->
3 <!DOCTYPE html
4 PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
5
6
7 <html>
8 <head>
9 <title>VOSpace 2.0 Recommendation</title>
10 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
11 <meta name="keywords" content="IVOA, International, Virtual, Observatory, Alliance" />
12 <!-- meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" / -->
13 <meta name="maintainedBy" content="IVOA Document Coordinator, ivoadoc@ivoa.net" />
14 <link rel="stylesheet" href="http://ivoa.net/misc/ivoa_rec.css" type="text/css" />
15 <style type="text/css">
16 .issue {background-color: yellow}
17 .postponedissue {background-color: yellow}
18 .def code
19 .future {background-color: pink}
20 .draftedit {background-color: white}
21 .draftdelete {background-color: white}
22 .note { margin-left: 4em }
23 code { font-weight: bold;
24 font-family: monospace }
25
26 div.exampleInner pre { margin-left: 1em;
27 margin-top: 0em; margin-bottom: 0em}
28 div.exampleOuter {border: 4px double gray;
29 margin: 0em; padding: 0em}
30 div.exampleInner { border-top-width: 4px;
31 border-top-style: double;
32 border-top-color: white;
33 border-bottom-width: 4px;
34 border-bottom-style: double;
35 border-bottom-color: white;
36 padding: 0px; margin: 0em }
37 div.exampleWrapper { margin: 4px }
38 div.exampleHeader { font-weight: bold;
39 margin: 4px}
40
41 div.schemaInner pre { margin-left: 1em;
42 margin-top: 0em; margin-bottom: 0em;
43 }
44 div.schemaOuter {border: 4px double gray; padding: 0em}
45 div.schemaInner { background-color: #eeeeee;
46 border-top-width: 4px;
47 border-top-style: double;
48 border-top-color: #d3d3d3;
49 border-bottom-width: 4px;
50 border-bottom-style: double;
51 border-bottom-color: #d3d3d3;
52 padding: 4px; margin: 0em }
53 div.schemaHeader { font-weight: bold;
54 margin: 4px}
55 </style>
56
57 </head>
58
59 <body>
60 <div class="head">
61 <a href="http://www.ivoa.net/"><img alt="IVOA" src="http://www.ivoa.net/pub/images/IVOA_wb_300.jpg" width="300" height="169"/></a>
62 <h1>VOSpace specification<br/>
63 Version 2.10-20140505</h1>
64 <h2>IVOA Working Draft 05 May 2014</h2>
65
66 <dl>
67 <dt>This version:</dt>
68 <dd><a href="http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.1-20140505.html">
69 http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.1-20140505.html</a></dd>
70
71 <dt>Latest version:</dt>
72
73 <dd><a href="http://www.ivoa.net/Documents/latest/VOSpace-2.0">
74 http://www.ivoa.net/Documents/latest/VOSpace-2.0.html</a></dd>
75
76 <dt>Previous versions:</dt>
77 <dd><a href="http://www.ivoa.net/Documents/WD/GWS/REC-VOSpace-2.0-20130329.html">
78 http://www.ivoa.net/Documents/WD/GWS/REC-VOSpace-2.0-20130329.html</a></dd>
79 <dd><a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20121221.html">
80 http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20121221.html</a></dd>
81 <dd><a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20120824.html">
82 http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20120824.html</a></dd>
83 <dd>PR: <a href="http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20111202.html">http://www.ivoa.net/Documents/WD/GWS/PR-VOSpace-2.0-20111202.html</a></dd>
84 <dd>WD: <a href="http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20110628.html">
85 http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20110628.html</a></dd>
86 <dd>WD: <a href="http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20101112.html">
87 http://www.ivoa.net/Documents/WD/GWS/WD-VOSpace-2.0-20101112.html</a></dd>
88 <dd>WD: <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20100323.html">
89 http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20100323.html</a></dd>
90 <dd>WD: <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090904.html">
91 http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090904.html</a></dd>
92 </dl>
93 <dd>WD: <a href="http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090513.doc">
94 http://www.ivoa.net/Documents/GWS/WD-VOSpace-2.0-20090513.doc</a></dd>
95 </dl>
96
97 <dl>
98 <dt>Working Group:</dt>
99 <dd><a href="http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices"> http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices</a></dd>
100 <dt>Author(s):</dt>
101 <dd>
102 <a
103 href="http://www.ivoa.net/twiki/bin/view/IVOA/MatthewGraham">Matthew
104 Graham (editor) </a><br/>
105 <a
106 href="http://www.ivoa.net/twiki/bin/view/IVOA/DaveMorris">Dave
107 Morris</a><br/> <a
108 href="http://www.ivoa.net/twiki/bin/view/IVOA/GuyRixon">Guy
109 Rixon</a><br/>
110 <a
111 href="http://www.ivoa.net/twiki/bin/view/IVOA/PatDowler">Pat Dowler</a><br/>
112 <a
113 href="http://www.ivoa.net/twiki/bin/view/IVOA/AndreSchaaff">Andre
114 Schaaff</a><br/> <a
115 href="http://www.ivoa.net/twiki/bin/view/IVOA/DougTody">Doug
116 Tody</a><br/> <a
117 href="http://www.ivoa.net/twiki/bin/view/IVOA/DougTody">Brian Major</a>
118 </dd>
119 </dl>
120 <hr/></div>
121
122 <h2><a name="abstract" id="abstract">Abstract</a></h2>
123 <p>VOSpace is the IVOA interface to distributed storage. This specification presents the first RESTful version of the interface, which is functionally equivalent to the SOAP-based VOSpace 1.1 specification. Note that all prior VOSpace clients will not work with this new version of the interface.</p>
124
125 <div class="status">
126 <h2><a name="status" id="status">Status of this Document</a></h2>
127
128 <!-- Choose one of the following (and remove the rest)-->
129 <!--Note-->
130 <!--
131 <p>This is an IVOA Note expressing suggestions from and opinions of the authors.<br/>
132 It is intended to share best practices, possible approaches, or other perspectives on interoperability with the Virtual Observatory.
133 It should not be referenced or otherwise interpreted as a standard specification.</p>
134 <p>This is an IVOA Working Draft for review by IVOA members and other interested parties.<br/>
135 It is a draft document and may be updated, replaced, or obsoleted by other documents at any time.
136 It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than work in progress.</p>
137 -->
138
139 <!--Proposed Recommendation
140 <p>This is an IVOA Proposed Recommendation made available for public review.<br/>
141 It is appropriate to reference this document only as a recommended standard that is under review and which may be changed before it is accepted as a full recommendation.</p>
142 <p>The first release of this document was 2009 May 13 as a Working
143 Draft and 2011 December 2011 as a Proposed Recommendation.
144 </p>
145 -->
146
147 <!--Recommendation
148 -->
149 <p>This is an IVOA Working Draft for review by IVOA members and other interested parties.<br/>
150 It is a draft document and may be updated, replaced, or obsoleted by other documents at any time.
151 It is inappropriate to use IVOA Working Drafts as reference materials or to cite them as other than work in progress.</p>
152
153 A list of <a href="http://www.ivoa.net/Documents/">current IVOA Recommendations and other technical documents</a> can be found at http://www.ivoa.net/Documents/.
154
155 </div><br />
156
157 <h2><a name="acknowledgments" id="acknowledgments">Acknowledgments</a></h2>
158 <p>This document derives from discussions among the Grid and Web Services working group of the IVOA.<p></p>
159 This document has been developed with support from the National Science Foundation's Information Technology Research Program under Cooperative Agreement AST0122449 with the John Hopkins University, from the UK Science and Technology Facilities Council (STFC), and from the European Commission's Sixth Framework Program via the Optical Infrared Coordination Network (OPTICON).</p>
160
161
162 <h2><a name="conformance" id="conformance">Conformance related definitions</a></h2>
163 <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 [RFC 2119].</p><p>
164 The <strong>Virtual Observatory (VO)</strong> is a general term for a
165 collection of federated resources that can be used to conduct
166 astronomical research, education, and outreach. The <strong>International Virtual Observatory Alliance (IVOA)</strong> is a global collaboration of separately funded projects to develop standards and infrastructure that enable VO applications. The International Virtual Observatory (IVO) application is an application that takes advantage of IVOA standards and infrastructure to provide some VO service.
167 </p>
168
169 <h2><a id="contents" name="contents">Contents</a></h2>
170 <div class="head">
171 <ul class="toc">
172 <li><a href="#abstract">Abstract</a></li>
173 <li><a href="#status">Status</a></li>
174 <li><a href="#acknowledgments">Acknowledgments</a></li>
175 <li><a href="#contents">Contents</a></li>
176 <li><a href="#sec1">1. Introduction</a></li>
177 <ul class="toc"><li><a href="#sec1_1">1.1 Typical use of a VOSpace service</a></li>
178 <li><a href="#sec1_2">1.2 The role in the IVOA Architecture</a></li>
179 <li><a href="#sec1_3">1.3 Document roadmap</a></li></ul>
180 <li><a href="#sec2">2. VOSpace identifiers</a></li>
181 <ul class="toc"><li><a href="#sec2_1">2.1 Identifier resolution</a></li></ul>
182 <li><a href="#sec3">3. VOSpace data model</a></li>
183 <ul class="toc"><li><a href="#sec3_1">3.1 Node and node types</a></li>
184 <li><a href="#sec3_2">3.2 Properties</a></li>
185 <ul class="toc"><li><a href="#sec3_2_1">3.2.1 Property values</a></li>
186 <li><a href="#sec3_2_2">3.2.2. Property identifiers</a></li>
187 <li><a href="#sec3_2_3">3.2.3 Property descriptions</a></li>
188 <li><a href="#sec3_2_4">3.2.4 Standard properties</a></li></ul>
189 <li><a href="#sec3_3">3.3 Capabilities</a></li>
190 <ul class="toc"><li><a href="#sec3_3_1">3.3.1 Example use cases</a></li>
191 <li><a href="#sec3_3_2">3.3.2 Capability identifiers</a></li>
192 <li><a href="#sec3_3_3">3.3.3 Capability descriptions</a></li>
193 <li><a href="#sec3_3_4">3.3.4 UI display name</a></li>
194 <li><a href="#sec3_3_5">3.3.5 Standard capabilities</a></li></ul>
195 <li><a href="#sec3_4">3.4 Views</a></li>
196 <ul class="toc"><li><a href="#sec3_4_1">3.4.1 Example use cases</a></li>
197 <li><a href="#sec3_4_2">3.4.2 View identifiers</a></li>
198 <li><a href="#sec3_4_3">3.4.3 View descriptions</a></li>
199 <li><a href="#sec3_4_4">3.4.4 Default views</a></li>
200 <li><a href="#sec3_4_5">3.4.5 Container views</a></li></ul>
201 <li><a href="#sec3_5">3.5 Protocols</a></li>
202 <ul class="toc"><li><a href="#sec3_5_1">3.5.1 Protocol identifiers</a></li>
203 <li><a href="#sec3_5_2">3.5.2 Protocol descriptions</a></li>
204 <li><a href="#sec3_5_3">3.5.3 Standard protocols</a></li>
205 <li><a href="#sec3_5_4">3.5.4 Custom protocols</a></li></ul>
206 <li><a href="#sec3_6">3.6 Transfers</a></li>
207 <ul class="toc"><li><a href="#sec3_6_1">3.6.1 Service-initiated transfers</a></li>
208 <li><a href="#sec3_6_2">3.6.2 Client-initiated transfers</a></li></ul>
209 <li><a href="#sec3_7">3.7 Searches</a></li>
210 <li><a href="#sec3_8">3.8 REST bindings</a></li></ul>
211 <li><a href="#sec4">4. Access Control</a></li>
212 <li><a href="#sec5">5. Web service operations</a></li>
213 <ul class="toc"><li><a href="#sec5_1">5.1 Service metadata</a></li>
214 <ul class="toc"><li><a href="#sec5_1_1">5.1.1 getProtocols</a></li>
215 <li><a href="#sec5_1_2">5.1.2 getViews</a></li>
216 <li><a href="#sec5_1_3">5.1.3 getProperties</a></li></ul>
217 <li><a href="#sec5_2">5.2 Creating and manipulating data nodes</a></li>
218 <ul class="toc"><li><a href="#sec5_2_1">5.2.1 createNode</a></li>
219 <li><a href="#sec5_2_2">5.2.2 moveNode</a></li>
220 <li><a href="#sec5_2_3">5.2.3 copyNode</a></li>
221 <li><a href="#sec5_2_4">5.2.4 deleteNode</a></li></ul>
222 <li><a href="#sec5_3">5.3 Accessing metadata</a></li>
223 <ul class="toc"><li><a href="#sec5_3_1">5.3.1 getNode</a></li>
224 <li><a href="#sec5_3_2">5.3.2 setNode</a></li>
225 <li><a href="#sec5_3_3">5.3.3 findNodes</a></li></ul>
226 <li><a href="#sec5_4">5.4 Transferring data</a></li>
227 <ul class="toc"><li><a href="#sec5_4_1">5.4.1 pushToVoSpace</a></li>
228 <li><a href="#sec5_4_2">5.4.2 pullToVoSpace</a></li>
229 <li><a href="#sec5_4_3">5.4.3 pullFromVoSpace</a></li>
230 <li><a href="#sec5_4_4">5.4.4 pushFromVoSpace</a></li></ul>
231 <li><a href="#sec5_5">5.5 Fault arguments</a></li>
232 </ul>
233 <li><a href="#sec6">6. Changes since last version</a></li>
234 <li><a href="#appA">Appendix A: Machine readable definitions</a></li>
235 <ul class="toc">
236 <li><a href="#appA_1">A.1 Message schema</a></li></ul>
237 <li><a href="#appB">Appendix B: Compliance matrix</a></li>
238 <li><a href="#appC">Appendix C: Standard properties</a></li>
239 <li><a href="#references">References</a></li>
240 </ul>
241 </div>
242 <hr/>
243
244 <br/>
245 <h2><a name="sec1">1. Introduction</a></h2>
246 <p>VOSpace is the IVOA interface to distributed storage. It specifies how VO agents and applications can use network attached data stores to persist and exchange data in a standard way.</p><p>
247 A VOSpace web service is an access point for a distributed storage network. Through this access point, a client can:</p><p>
248 <ul><li> add or delete data objects
249 <li> manipulate metadata for the data objects
250 <li> obtain URIs through which the content of the data objects can be accessed
251 </ul>
252 </p><p>VOSpace does not define how the data is stored or transferred, only the control messages to gain access. Thus, the VOSpace interface can readily be added to an existing storage system.</p><p>
253
254 When we speak of "a VOSpace", we mean the arrangement of data accessible through one particular VOSpace service. </p><p>
255
256 Each data object within a VOSpace service is represented as a node and has a description called a representation. A useful analogy to have in mind when reading this document is that a node is equivalent to a file. </p><p>
257
258 Nodes in VOSpace have unique identifiers expressed as URIs in the 'vos' scheme, as defined below. </p><p>
259
260 VOSpace 2.0 did not introduce any new functionality to that already
261 offered by prior (SOAP-based) versions of the interface (<a href="#VOSpace11">VOSpace 1.1</a>) but defines a RESTful binding for the interface. VOSpace 2.1 introduces minor, backward compatible functional changes to VOSpace 2.0.
262 </p>
263
264 <h3><a name="sec1_1">1.1 Typical use of a VOSpace service</a></h3>
265 <p>A typical use case for VOSpace is uploading a local data file to a remote VOSpace service. This is a two-stage process: creating a description of the data file (representation) in the VOSpace including any metadata (its properties) that they want to associate with it (e.g., MIME type), and defining the transfer operation that will actually see the data file bytes uploaded to the VOSpace service. The order of the processes should not matter. The user may want to create the representation first and then perform the transfer or transfer the bytes first and then update the representation with the appropriate metadata. </p><p>
266
267 Let's consider the first sequence: the user provides a XML description
268 of the data file which they HTTP PUT to the appropriate VOSpace URI -
269 this will be the HTTP identifier for the data file in the VOSpace,
270 e.g. http://nvo.caltech.edu/vospace/myData/table123. The description
271 will resemble this:</p>
272 <pre>
273 &lt;node xmlns="http://www.ivoa.net/xml/VOSpaceTypes-v2.1"
274 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
275 uri="vos://nvo.caltech!vospace/mytable1"
276 xsi:type="vost:UnstructuredDataNode">
277 &lt;properties>
278 &lt;property uri="ivo://ivoa.net/vospace/core#mimetype">text/xml&lt;/property>
279 &lt;/properties>
280 &lt;/node>
281 </pre>
282 <p>
283 The service will reply with an amended version of the representation containing service-specific details in addition to the information supplied by the user. These will include data formats that the service can handle for the type of node created in the VOSpace, third-party interfaces (capabilities) to the data that the service offers and system metadata.
284 </p><p>
285 The user will then describe the data format (the view) they want to use in uploading the file, e.g. VOTable, and the transport protocol (the protocol) that they want to employ to upload the file, e.g. HTTP PUT. This will result in the HTTP POSTing of a XML description of the transfer request to the appropriate VOSpace URI, e.g. http://nvo.caltech.edu/vospace/myData/table123/transfers. The description will resemble this:
286 </p><pre>
287 &lt;transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1">
288 &lt;target>vos://nvo.caltech!vospace/mytable1&lt;/target>
289 &lt;direction>pushToVoSpace&lt;/direction>
290 &lt;view uri="ivo://ivoa.net/vospace/core#votable"/>
291 &lt;protocol uri="ivo://ivoa.net/vospace/core#http-put"/>
292 &lt;/transfer>
293 </pre><p>
294 The service will reply with the URL that the user will HTTP PUT the
295 data file to,
296 e.g. http://nvo.caltech.edu/bvospace/myData/table123/transfers/147516ab. The
297 user will then use a regular HTTP client to transfer (PUT) the local
298 file to the specified endpoint. This illustrates an important point
299 about VOSpace - it is only concerned with the server-side management of data storage and transfer. A client negotiates the details of a data transfer with a VOSpace service but the actual transfer of bytes across a network is handled by other tools.
300 </p><p>
301 Similarly, when a user wants to retrieve a data file from a VOSpace service, they will specify the data format (view) they want to use in downloading the file, e.g. VOTable, and the transport protocol (the protocol) that they want to employ to download the file, e.g. HTTP GET, and HTTP POST a XML description of this transfer request to the appropriate VOSpace URI - the transfer URI for the node in the VOSpace, e.g. http://nvo.caltech.edu/vospace/myDataNode/table123/transfers. The description will resemble this:
302 </p><pre>
303 &lt;transfer xmlns="http://www.ivoa.net/xml/VOSpace/v2.1">
304 &lt;target>vos://nvo.caltech!vospace/mytable1&lt;/target>
305 &lt;direction>pullFromVoSpace&lt;/direction>
306 &lt;view uri="ivo://ivoa.net/vospace/core#votable"/>
307 &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
308 &lt;/transfer>
309 </pre><p>
310 The service will reply with the URL for the user to use, e.g. http://nvo.caltech.edu/vospace/myDataNode/table123/transfers/3df89ab4. The user can then download the data file by pointing an HTTP client (e.g. web browser) at the specified endpoint.
311 </p>
312
313 <h3><a name="sec1_2">1.2 The role in the IVOA Architecture</a></h3>
314 <p>The IVOA Architecture [Arch] provides a high-level view of how IVOA
315 standards work together to connect users and applications with
316 providers of data and services, as depicted in the diagram in Fig. 1.
317 </p>
318
319 <p>
320 <center>
321 <font size="-1">
322 <img src="vospace-in-arch.png" width="756"/> <br />
323 <blockquote>
324 <strong>Figure 1. VOSpace in the IVOA Architecture.</strong>
325 This provides an interface to distributed storage. It specifies how
326 applications can use networked data stores to persist and exchange data in a standardized fashion.
327 </blockquote>
328 </font>
329 </center>
330 </p>
331
332 <p>In this architecture, users employ a variety of tools (from the
333 User Layer) to discover and access archives and services of interest
334 (represented in the Resource Layer). VOSpace provides an interface to
335 storage resources containing the results of using these archives and
336 services and also to other storage solutions, e.g., local disks, where
337 users might want to transfer these results for further work. Items in
338 these resources are referenced by a VOSpace identifier which is
339 related to the standard IVOA Resource Identifier (see section 2).
340 This version of VOSpace employs the UWS design pattern [UWS] to manage data
341 transfers (see section 3.6) and searches (see section 3.7). VOSpace
342 instances may also employ the IVOA Single-Sign-On standard [SSO] for
343 authentication purposes (see section 4) and IVOA Credential Delegation
344 Protocol [CDP] to delegate data transfers.
345 </p>
346
347
348 <h3><a name="sec1_3">1.3 Document roadmap</a></h3>
349 <p>The rest of this document is structured as follows:
350 </p><p>
351 In <a href="#sec2">Section 2</a>, we specify the URI syntax for identifying data objects (nodes) in VOSpace.
352 </p><p>
353 In <a href="#sec3">Section 3</a>, we present the data model that underpins the VOSpace architecture. This consists of a number of data structures, which have XML representations that are used across the wire in message exchanges with a VOSpace service. These structures represent:
354 </p>
355 <ul>
356 <li> the data objects themselves (nodes)
357 <li> metadata that can be associated with a data object (properties)
358 <li> third-party interfaces to the data (capabilities)
359 <li> the data format used when transferring data objects across the wire (views)
360 <li> the transport protocol employed in a data transfer (protocols)
361 <li> the data transfer itself (transfers)
362 <li> searches of data objects (searches)
363 </ul>
364 <p>
365 We also describe the REST bindings between these representations and their URIs (HTTP identifiers).
366 </p><p>
367 In <a href="#sec4">Section 4</a>, we outline how security and access control policies are currently handled in VOSpace.
368 </p><p>
369 In <a href="#sec5">Section 5</a>, we detail the operations that the VOSpace interface supports. These handle access to service-level metadata, the creation and manipulation of nodes within the VOSpace, access to node metadata (properties) and data transfer to and from the VOSpace.
370 </p><p>
371 In <a href="#appA">Appendix A</a>, we formally define the VOSpace
372 interface with a machine readable description of its requests and
373 responses and in <a href="#appB">Appendix B</a>, we present a
374 compliance matrix listing the mandatory behaviour required of a valid
375 VOSpace 2.1 service.
376 </p>
377
378
379 <br/>
380 <h2><a name="sec2">2. VOSpace identifiers</a></h2>
381 <p>The identifier for a node in VOSpace SHALL be a URI with the scheme <code>vos</code>.</p>
382 <p>
383 Such a URI SHALL have the following parts with the meanings and
384 encoding rules defined in RFC2396 <a href="#ref2">[RFC 2396]</a>.
385 </p><ul>
386 <li> scheme
387 <li> naming authority
388 <li> path
389 <li> (optional) query
390 <li> (optional) fragment identifier (with the expected semantics <a
391 href="#fragref">[see here]</a>)
392 </ul><p>
393 The naming authority for a VOSpace node SHALL be the VOSpace service
394 through which the node was created. The authority part of the URI
395 SHALL be constructed from the IVO registry identifier [IVORN] for that
396 service by deleting the ivo:// prefix and changing all forward-slash
397 characters('/') in the resource key to exclamation marks ('!') or
398 tildes ('~'). Note that a service SHALL be consistent in its use of
399 separator characters ('!' or '~') when referring to its own data but
400 SHALL accept either as valid in URIs in service requests. For the rest
401 of the document, we shall use '!' as the default character.
402 </p><p>
403 This is an example of a possible VOSpace identifier.
404 </p>
405 <pre>
406 vos://nvo.caltech!vospace/myresults/siap-out-1.vot
407 </pre>
408 <ul<li>The URI scheme is <em>vos</em>
409 </ul>
410 <p>
411 Using a separate URI scheme for VOSpace identifiers enables clients to distinguish between IVO registry identifiers and VOSpace identifiers.
412 </p><ul>
413 <li> nvo.caltech!vospace
414 </ul><p>
415 is the authority part of the URI, corresponding to the IVO registry identifier
416 </p><ul>
417 <li> ivo://nvo.caltech/vospace
418 </ul><p>
419 This is the IVO registry identifier of the VOSpace service that contains the node.
420 </p><ul>
421 <li> /siap-out-1.vot is the URI path
422 </ul><p>
423 Slashes in the URI path imply a hierarchical arrangement of data: the
424 data object identified by
425 vos://nvo.caltech!vospace/myresults/siap-out-1.vot is within the
426 container identified by vos://nvo.caltech!vospace/myresults.
427 </p>
428 Literal space characters are also not allowed in URIs.
429 </p><p>
430 All ancestors in the hierarchy SHALL be resolvable as containers (ContainerNodes), all the way up to the root node of the space (this precludes any system of implied hierarchy in the naming scheme for nodes with ancestors that are just logical entities and cannot be reified, e.g. the Amazon S3 system).
431 </p><p>
432 A VOSpace identifier is globally unique, and identifies one specific
433 node in a specific VOSpace service.
434 </p>
435
436 <p>
437 The standardID for this specification SHALL be: ivo://ivoa.net/std/VOSpace/v2.1.
438 </p>
439
440 <h3><a name="sec2_1">2.1 Identifier resolution</a></h3>
441 <p>A VOSpace identifier can be resolved to a HTTP endpoint for accessing representations of the node associated with it. A client SHOULD use the following procedure to resolve access to a VOSpace node from a VOSpace identifier: </p><ul>
442
443 <li> Resolve HTTP service endpoint of VOSpace service with registry
444 <li> Append "nodes/" and the path following the naming authority part of the VOSpace identifier to the service endpoint
445 </ul><p>
446 Given the example identifier
447 </p><pre>
448 vos://org.astrogrid.cam!vospace/container-6/siap-out-1.vot?foo=bar
449 </pre><p>
450 processing the URI to resolve the VOSpace service would involve :
451 </p><ul>
452 <li> Extract the IVO registry identifier of the VOSpace service by prepending an ivo scheme to the naming authority part:
453 <ul><li> ivo://org.astrogrid.cam/vospace</li></ul>
454 <li> Resolve the IVO identifier in a registry and retrieve the access URL of the service endpoint:
455 <ul><li> http://some.uni.ac.uk/vospace</li></ul>
456 <li> Append "nodes/" and the path part of the VOSpace identifier:
457 <ul><li>http://some.uni.ac.uk/vospace/nodes/container-6/siap-out-1.vot?foo=bar
458 </li></ul>
459 </li></ul>
460 </p><p>
461 Note that any fragment identifier in the identifier SHOULD be removed
462 when resolving the identifier to a HTTP endpoint, consistent with
463 the implied semantics of URI fragments <a
464 href="fragref">[see here]</a>.
465 </p>
466
467 <br/>
468 <h2><a name="sec3">3. VOSpace data model</a></h2>
469 <h3><a name="sec3_1">3.1 Nodes and node types</a></h3>
470 <p>We refer to the arrangement of data accessible through one particular VOSpace service as "a VOSpace".
471 </p><p>
472 Each data object within a VOSpace SHALL be represented as a node that is identified by a URI.
473 </p><p>
474 There are different types of nodes and the type of a VOSpace node determines how the VOSpace service stores and interprets the node data.
475 </p><p>
476 The types are arranged in a hierarchy (see Fig. 2), with more detailed types inheriting the structure of more generic types.
477 </p>
478
479 <p>
480 <center>
481 <font size="-1">
482 <img src="vospace-node-hierarchy.png" width="600"/> <br />
483 <blockquote>
484 <strong>Figure 2. Node hierarchy</strong>
485 This shows the inheritance structure for the different types of nodes
486 in VOSpace.
487 </blockquote>
488 </font>
489 </center>
490 </p>
491
492 <p>
493 The following types (and representations) are defined:
494 </p><ul>
495 <li> <i>Node</i> is the most basic type
496 <li> <i>ContainerNode</i> describes a data item that can contain other data items
497 <li> <i>DataNode</i> describes a data item stored in the VOSpace
498 <li> <i>UnstructuredDataNode</i> describes a data item for which the VOSpace does not understand the data format
499 <li> <i>StructuredDataNode</i> describes a data item for which the space understands the format and may make transformations that preserve the meaning of the data.
500 <li> <i>LinkNode</i> describes a node that points to another node.
501 </ul><p>
502 When data is stored and retrieved from an <i>UnstructuredDataNode</i>, the bit pattern read back SHALL be identical to that written.
503 </p><p>
504 When data is stored and retrieved from a <i>StructuredDataNode</i>, the bit pattern returned MAY be different to the original. For example, storing tabular data from a VOTable file will preserve the tabular data, but any comments in the original XML file may be lost.
505 </p><p>
506 A Node representation SHALL have the following elements:
507 </p><ul>
508 <li> <i>uri</i>: the vos:// identifier for the node, URI-encoded
509 according to <a href="#ref3">RFC2396</a>
510 <li> <i>properties</i>: a set of metadata properties for the node
511 <li> <i>capabilities</i>: a third-party interface to a data object
512 </ul>
513
514 <p>
515 In addition, a <i>DataNode</i> representation SHALL have the following elements:
516 </p><ul>
517 <li> <i>accepts</i>: a list of the views (data formats) that the node can accept
518 <li> <i>provides</i>: a list of the views (data formats) that the node can provide
519 <li> <i>busy</i>: a boolean flag to indicate that the data associated with the node cannot be accessed
520 </ul>
521 <p>
522 The <i>busy</i> flag is used to indicate that an internal operation is in progress, and the node data is not available.
523 </i>
524 <p>
525 A <i>ContainerNode</i> representation SHALL have the following
526 elements, in addition to those it inherits from the <i>Node</i>
527 representation:
528 </p><ul>
529 <li> <i>nodes</i>: a list of the direct children, if applicable,
530 that the container has. Each child is represented as a <i>node</i>
531 subelement containing its vos:// identifier, URI-encoded according
532 to <a href="#ref3">RFC2396</a>
533 </ul>
534 <p>
535 A <i>LinkNode</i> representation SHALL have the following elements, in addition to those it inherits from the <i>Node</i> representation:
536 </p><ul>
537 <li> <i>target</i>: the target URI, URI-encoded according to <a
538 href="#ref3">RFC2396</a>
539 </ul>
540 <p>
541 The link target can be a URI that points to any type of resource, including other VOSpace Nodes (within the same VOSpace service or in another service), or external resources outside VOSpace altogether.
542 </p><p>
543 The properties of a <i>LinkNode</i> do not propagate to the target of
544 the <i>LinkNode</i>, i.e., a property attached to a <i>LinkNode</i>
545 does not also get attached to the target node. One use case is to enable third-party annotations to be associated with a resource but without the resource itself getting cluttered with unnecessary metadata. In this case, the client creates a <i>LinkNode</i> pointing to the resource in question and then adds the annotations as properties of the LinkNode.
546 </p><p>
547 Both the <i>ContainerNode</i> and the <i>LinkNode</i> SHALL have no data bytes associated with them.
548 </p><p>
549 The set of node types defined by this standard is closed; new types may be introduced only via new versions of the standard.
550 </p><p>
551 To comply with the standard, a client or service SHALL be able to parse XML representations of all the node types defined in the current specification.
552 </p><p>
553 Note: This does not require all services to support all of the Node
554 types, just that it can process an XML request containing any of the
555 types. If the service receives a request for a type that it does not
556 support, the service SHOULD return a <i>TypeNotSupported</i> fault. The
557 service SHALL NOT throw an XML parser error if it receives a request
558 for a type that it does not support.
559 </p>
560
561 <h3><a name="sec3_2">3.2 Properties</a></h3>
562 <p><i>Properties</i> are simple string-based metadata properties associated with a node. </p>
563 <p>
564 Individual <i>Properties</i> should contain simple short string values, not large blocks of information. If a system needs to attach a large amount of metadata to a node, then it should either use multiple small <i>Properties</i>, or a single <i>Property</i> containing a URI or URL pointing to an external resource that contains the additional metadata.
565 </p><p>
566 A <i>Property</i> representation SHALL have the following elements:
567 <ul>
568 <li> <i>uri</i>: the <i>Property</i> identifier
569 <li> <i>value</i>: the string value of the <i>Property</i>
570 <li> <i>readOnly</i>: a boolean flag to indicate that the <i>Property</i> cannot be changed by the client
571 </ul>
572 <p>
573 Properties may be set by the client or the service.
574 </p>
575
576 <h4><a name="sec3_2_1">3.2.1 Property values</a></h4>
577 <p>Unless they have special meaning to the service or client,
578 <i>Properties</i> are treated as simple string values.</p>
579
580 <p>When a <i>Property</i> can take multiple values, e.g., a list of
581 groups which can access a particular resource, these SHOULD be
582 comma-separated, unless the property description
583 defines a specific delimiter.
584 </p>
585
586 <p>Some <i>Properties</i> may have meaning to the service; others may have meaning only to one specific type of client. A service implementation does not need to understand the meaning of all the <i>Properties</i> of a node. Any <i>Properties</i> that it does not understand can simply be stored as text strings.
587 </p>
588
589 <h4><a name="sec3_2_2">3.2.2 Property identifiers</a></h4>
590 <p>Every new type of <i>Property</i> SHALL require a unique URI to identify the <i>Property</i> and its meaning.
591 </p><p>
592 The rules for the <i>Property</i> identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
593 </p>
594 <ul>
595 <li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my­namespace
596 <li> Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema or a resource describing it
597 </ul><p>
598 The current VOSpace schema defines <i>Property</i> identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
599 </p><ul>
600 <li> A <i>Property</i> URI can be a simple URN, e.g. urn:my­property
601 </ul><p>
602 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
603 </p><p>
604 For a production system, any new Properties SHOULD have unique URIs that can be resolved into to a description of the Property.
605 </p><p>
606 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
607 </p><ul>
608 <li> ivo://my­registry/vospace/properties#my­property
609 </ul><p>
610 Using an IVO registry URI to identify Properties has two main advantages :
611 </p><ul>
612 <li> IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
613 <li> If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover what the Property means
614 </ul>
615
616 <h4><a name="sec3_2_3">3.2.3 Property descriptions</a></h4>
617 <p>If the URI for a particular Property is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the Property.
618 </p><p>
619 A Property description SHOULD describe the data type and meaning of a Property.
620 </p><p>
621 A PropertyDescription SHOULD have the following members :
622 </p><ul>
623 <li> <i>uri</i>: the formal URI of the Property
624 <li> <i>DisplayName</i>: A display name for the Property
625 <li> <i>Description</i>: A text block describing the meaning and validation rules of the <i>Property</i>
626 </ul><p>
627 A <i>PropertyDescription</i> MAY have the following OPTIONAL members :
628 </p><ul>
629 <li> <i>UCD</i>: the Universal Content Descriptor (in the UCD1+ scheme) for the <i>Property</i>
630 <li> <i>Unit</i>: the unit of measurement of the Property
631 </ul>
632 <p>
633 The information in a Property description can be used to generate a UI for displaying and modifying the different types of Properties.
634 </p><p>
635 Note that at the time of writing, the schema for registering PropertyDescriptions in the IVO registry has not been finalized.
636 </p>
637
638 <h5><a name="sec3_2_3_1">3.2.3.1 UI display name</a></h5>
639 <p>
640 If a client is unable to resolve a Property identifier into a description, then it may just display the identifier as a text string:
641 </p><ul>
642 <li> urn:modified­date
643 </ul><p>
644 If the client can resolve the Property identifier into a description, then the client may use the information in the description to display a human readable name and description of the Property:
645 </p><ul>
646 <li> Last modification date of the node data
647 </ul>
648 <h5><a name="sec3_2_3_2">3.2.3.2 Property editors</a></h5>
649 <p>If the client is unable to resolve a Property identifier into a description, or does not understand the type information defined in the description, then the client MAY treat the Property value as a simple text string.
650 </p><p>
651 If the client can resolve the Property identifier into a description, then the client MAY use the information in the description to display an appropriate editing tool for the Property.
652 </p><p>
653 In the current version of the specification the rules for editing Properties are as follows:
654 </p><ul>
655 <li> A service MAY impose validation rules on the values of specific types of Properties
656 <li> If a client attempts to set a Property to an invalid value, then the service MAY reject the change
657 <li> Where possible, the validation rules for a type of Property SHOULD be defined in the Property description
658 </ul><p>
659 Future versions of the VOSpace specification may extend the PropertyDescription to include more specific machine readable validation rules for a Property type.
660 </p><p>
661 Note that at the time of writing, the schema for registering validation rules in PropertyDescriptions has not been finalized.
662 </p>
663 <h4><a name="sec3_2_4">3.2.4 Standard properties</a></h4>
664 <p>
665 Property URIs and PropertyDescriptions for the core set of Properties
666 are registered under a StandardKeyEnumeration resource [VOStd] in the
667 IVOA registry with the resource identifier ivo://ivoa.net/vospace/core.
668 The following URIs SHOULD be used to represent the service
669 properties:</p><ul>
670 <li> ivo://ivoa.net/vospace/core#title SHALL be used as the
671 property URI denoting a name given to the resource
672 <li> ivo://ivoa.net/vospace/core#creator SHALL be used as the
673 property URI denoting an entity primarily responsible for making the resource
674 <li> ivo://ivoa.net/vospace/core#subject SHALL be used as the
675 property URI denoting the topic of the resource
676 <li> ivo://ivoa.net/vospace/core#description SHALL be used as the
677 property URI denoting an account of the resource
678 <li> ivo://ivoa.net/vospace/core#publisher SHALL be used as the
679 property URI denoting an entity responsible for making the resource available
680 <li> ivo://ivoa.net/vospace/core#contributor SHALL be used as the
681 property URI denoting an entity responsible for making contributions
682 to this resource
683 <li> ivo://ivoa.net/vospace/core#date SHALL be used as the
684 property URI denoting a point or period of time associated with an
685 event in the lifecycle of the resource
686 <li> ivo://ivoa.net/vospace/core#type SHALL be used as the
687 property URI denoting the nature or genre of the resource
688 <li> ivo://ivoa.net/vospace/core#format SHALL be used as the
689 property URI denoting the file format, physical medium, or
690 dimensions of the resource
691 <li> ivo://ivoa.net/vospace/core#identifier SHALL be used as the
692 property URI denoting an unambiguous reference to the resource
693 within a given context
694 <li> ivo://ivoa.net/vospace/core#source SHALL be used as the
695 property URI denoting a related resource from which the described
696 resource is derived
697 <li> ivo://ivoa.net/vospace/core#language SHALL be used as the
698 property URI denoting a language of the resource
699 <li> ivo://ivoa.net/vospace/core#relation SHALL be used as the
700 property URI denoting a related resource
701 <li> ivo://ivoa.net/vospace/core#coverage SHALL be used as the
702 property URI denoting the spatial or temporal topic of the resource,
703 the spatial applicability of the resource, or the jurisdiction under
704 which the resource is relevant
705 <li> ivo://ivoa.net/vospace/core#rights SHALL be used as the
706 property URI denoting information about rights held in and over the resource
707 <li> ivo://ivoa.net/vospace/core#availableSpace SHALL be used as the
708 property URI denoting the amount of space available within a container
709 <li> ivo://ivoa.net/vospace/core#groupread SHALL be used as the
710 property URI denoting the list of groups which can only read this
711 resource (read-only)
712 <li> ivo://ivoa.net/vospace/core#groupwrite SHALL be used as the
713 property URI denoting the list of groups which can read and write to
714 this resource (read-write)
715 <li> ivo://ivoa.net/vospace/core#publicread SHALL be used as the
716 property URI denoting whether this resource is world readable (anon-read-only)
717 <li> ivo://ivoa.net/vospace/core#quota SHALL be used as the
718 property URI denoting the value of a system quota on the resource
719 <li> ivo://ivoa.net/vospace/core#length SHALL be used as the
720 property URI denoting the length or size of a resource
721 <li> ivo://ivoa.net/vospace/core#mtime SHALL be used as the property
722 URI denoting the data modification time
723 <li> ivo://ivoa.net/vospace/core#ctime SHALL be used as the property
724 URI denoting status change (aka metadata modification) time
725 <li> ivo://ivoa.net/vospace/core#btime SHALL be used as the property
726 URI denoting initial creation time
727
728 </ul>
729 <p>However, this is not intended to be a closed list,
730 different implementations are free to define and use their own
731 Properties. </p>
732
733 <h3><a name="sec3_3">3.3 Capabilities</a></h3>
734 <p>A Capability describes a third-party interface to a node. One application of this would be to enable data access to a node or its contents using a 3rd party service interface.
735 </p><p>
736 A Capability representation SHALL have the following members:
737 </p><ul>
738 <li> uri: the Capability identifier
739 <li> endpoint: the endpoint URL to use for the third-party interface
740 <li> param: a set of parameters for the capability
741 </ul>
742
743 <h4><a name="sec3_3_1">3.3.1 Example use cases</a></h4>
744 <p>A ContainerNode containing image files may offer a DAL SIAP capability so that the images in the container can be accessed using a SIAP service. In this way, a user could create a (DAL enabled) Container in VOSpace, transfer some images into it and then query the set of images using the SIAP interface.
745 </p><p>
746 Another example is a DataNode that provides an iRODS capability so
747 that the data replication for this data object can be handled using
748 the iRODS service API.
749 </p>
750
751 <h4><a name="sec3_3_2">3.3.2 Capability identifiers</a></h4>
752 <p>Every new type of Capability SHALL require a unique URI to identify the Capability. The rules for the Capability identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.</p><ul>
753 <li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my-namespace
754 <li> Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it.
755 </ul>
756 <p>
757 The VOSpace schema defines Capability identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
758 </p><ul>
759 <li> A Capability URI can be a simple URN, e.g. urn:my-capability
760 </ul><p>
761 This may be sufficient for testing and development on a private system, but it is not suitable for use on a public service. For a production system, any new Capabilities SHOULD have unique URIs that can be resolved into a description of the Capability. Ideally, these SHOULD be IVO registry URIs that point to a description registered in the IVO registry:
762 </p><ul>
763 <li> ivo://my-registry/vospace/capabilities#my-capability
764 </ul>
765 <p>
766 Using an IVO registry URI to identify Capabilities has two main advantages:
767 </p>
768 <ul>
769 <li> IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
770 <li> If the IVO registry URI points to a description registered in the
771 IVO registry, this provides a mechanism to discover how to use the Capability.
772 </ul>
773
774 <h4><a name="sec3_3_3">3.3.3 Capability descriptions</a></h4>
775 <p>If the URI for a particular Capability is resolvable, i.e. an IVO registry identifier or a HTTP URL then it SHOULD point to an XML resource that describes the Capability.
776 </p><p>
777 A CapabilityDescription SHOULD describe the third-party interface and how it should be used in this context. A CapabilityDescription SHOULD have the following members:
778 </p><ul>
779 <li> <i>uri</i>: the formal URI of the Capability
780 <li> <i>DisplayName</i>: a simple display name of the Capability.
781 <li> <i>Description</i>: a text block describing the third-party interface and how it should be used in this context.
782 </ul><p>
783 Note that at the time of writing, the schema for registering CapabilityDescriptions in the IVO registry has not been finalized.
784 </p>
785
786 <h4><a name="sec3_3_4">3.3.4 UI display name</a></h4>
787 <p>If a client is unable to resolve a Capability identifier into a description then it may just display the identifier as a text string:
788 </p><ul>
789 <li> Access data using urn:edu.sdsc.irods
790 </ul><p>
791 If a client can resolve the Capability identifier into a description then the client may use the information in the description to display a human readable name and description of the Capability:
792 </p><ul>
793 <li> Access data using iRODS
794 </ul>
795
796 <h4><a name="sec3_3_5">3.3.5 Standard capabilities</a></h4>
797 <p>Capability URIs and CapabilityDescriptions for the core set of
798 Capabilities are registered under a StandardKeyEnumeration resource [VOStd] in the
799 IVOA registry with the resource identifier ivo://ivoa.net/vospace/core.. The following URIs SHALL be used to represent the service capabilities:
800 </p><ul>
801 <li> ivo://ivoa.net/vospace/core#vospace-1.0 SHALL be used as the capability URI for a VOSpace 1.0 service
802 <li> ivo://ivoa.net/vospace/core#vospace-1.1 SHALL be used as the capability URI for a VOSpace 1.1 service
803 <li> ivo://ivoa.net/vospace/core#vospace-2.0 SHALL be used as the capability URI for a VOSpace 2.0 service
804 </ul><p>
805 If a service implementation supports more than one version of the VOSpace interface then these capability URIs can be used with a VOSpace service to identify different VOSpace capabilities for a node.
806 </p><p>
807 One use case for this would be a VOSpace 1.1 client talking to a service that implements both VOSpace 1.0 and VOSpace 1.1, where the client is acting on behalf of a third party agent that only understands VOSpace 1.0. In this case, the client can use the information in the VOSpace 1.0 capability to direct the third party agent to the VOSpace 1.0 endpoint.
808 </p><p>
809 Other standard service interfaces will also be registered, e.g.
810 </p><ul>
811 <li> Cone Search
812 <li> SIAP
813 <li> SSAP
814 <li> TAP
815 </ul><p>
816 However, this is not intended to be a closed list and different implementations are free to define and use their own Capabilities.
817 </p>
818
819 <h3><a name="sec3_4">3.4 Views</a></h3>
820 <p>A View describes the data formats and contents available for importing or exporting data to or from a VOSpace node.
821 </p><p>
822 The metadata for a DataNode contains two lists of Views.
823 </p><ul>
824 <li> <i>accepts</i> is a list of Views that the service can accept for importing data into the Node
825 <li> <i>provides</i> is a list of Views that the service can provide for exporting data from Node
826 </ul><p>
827 A View representation SHALL have the following members:
828 </p><ul>
829 <li> <i>uri</i>: the View identifier
830 <li> <i>original</i>: an optional boolean flag to indicate that the View preserves the original bit pattern of the data
831 <li> <i>param</i>: a set of name-value pairs that can be used to
832 specify additional arguments for the View
833 </ul>
834
835 <h4><a name="sec3_4_1">3.4.1 Example use cases</a></h4>
836 <b>Simple file store</b>
837 <p>
838 A simple VOSpace system that stores data as a binary files can just return the contents of the original file. The client supplies a View identifier when it imports the data, and the service uses this information to describe the data to other clients.
839 </p><p>
840 A file based system can use the special case identifier 'ivo://ivoa.net/vospace/core#view­any' to indicate that it will accept any data format or
841 View for a Node.
842 </p><p>
843 For example:
844 </p><ul>
845 <li> A client imports a file into the service, specifying a View to describe the file contents
846 <li> The service stores the data as a binary file and keeps a record of the View
847 <li> The service can then use the View supplied by the client to describe the data to other clients
848 </ul><p>
849 This type of service is not required to understand the imported data, or to verify that it contents match the View, it treats all data as binary files.
850 </p>
851
852 <h5><a name="sec3_4_1_1">3.4.1.1 Database store</a></h5>
853 <p>A VOSpace system that stores data in database tables would need to be able to understand the data format of an imported file in order to parse the data and store it correctly. This means that the service can only accept a specific set of Views, or data formats, for importing data into the Node.
854 </p><p>
855 In order to tell the client what input data formats it can accept, the service publishes a list of specific Views in the accepts list for each Node.
856 </p><p>
857 On the output side, a database system would not be able to provide access to the original input file. The contents of file would have been transferred into the database table and then discarded. The system has to generate the output results from the contents of the database table.
858 </p><p>
859 In order to support this, the service needs to be able to tell the client what Views of the data are available.
860 </p><p>
861 A database system may offer access to the table contents as either VOTable or FITS files, it may also offer zip or tar.gz compressed versions of these. In which case the system needs to be able to express nested file formats such as 'zip containing VOTable' and 'tar.gz containing FITS'.
862 </p><p>
863 A service may also offer subsets of the data. For example, a work flow system may only want to look at the table headers to decide what steps are required to process the data. If the table contains a large quantity of data, then downloading the whole contents just to look at the header information is inefficient. To make this easier, a database system may offer a 'metadata only' View of the table, returning a VOTable or FITS file containing just the metadata headers and no rows.
864 </p><p>
865 So our example service may want to offer the following Views of a database table:
866 </p><ul>
867 <li> Table contents as FITS
868 <li> Table contents as VOTable
869
870 <li> Table contents as zip containing FITS
871 <li> Table contents as zip containing VOTable
872
873 <li> Table contents as tar.gz containing FITS
874 <li> Table contents as tar.gz containing VOTable
875
876 <li> Table metadata as FITS
877 <li> Table metadata as VOTable
878 </ul><p>
879 The service would publish this information as a list of Views in the provides section of the metadata for each Node.
880 </p><p>
881 The VOSpace specification does not mandate what Views a service must provide. The VOSpace specification is intended to provide a flexible mechanism enabling services to describe a variety of different Views of data. It is up to the service implementation to decide what Views of the data it can accept and provide.
882 </p>
883
884 <h4><a name="sec3_4_2">3.4.2 View identifiers</a></h4>
885 <p>Every new type of View SHALL require a unique URI to identify the View and its content.
886 </p><p>
887 The rules for the View identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI.
888 </p><ul>
889 <li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my­namespace
890 <li> Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it
891 </ul><p>
892 The current VOSpace schema defines View identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
893 </p><ul>
894 <li> A View URI can be a simple URN, e.g. urn:my­view
895 </ul><p>
896 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
897 </p><p>
898 For a production system, any new Views SHOULD have unique URIs that can be resolved into to a description of the View.
899 </p><p>
900 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry:
901 </p><ul>
902 <li> ivo://my­registry/vospace/views#my­view
903 </ul><p>
904 Using an IVO registry URI to identify Views has two main advantages :
905 </p><ul>
906 <li> IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
907 <li> If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover what the View contains
908 </ul>
909
910 <h4><a name="sec3_4_3">3.4.3 View descriptions</a></h4>
911 <p>If the URI for a particular View is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the View. </p>
912
913 <p>A ViewDescription SHOULD describe the data format and/or content of the view.</p>
914
915 <p>A ViewDescription SHOULD have the following members :
916 </p><ul>
917 <li> <i>Uri</i>: the formal URI of the View
918 <li> <i>DisplayName</i>: A simple text display name of the View
919 <li> <i>Description</i>: Text block describing the data format and content of the View
920 </ul>
921 <p>A ViewDescription MAY have the following optional members:</p>
922 <ul>
923 <li> MimeType : the standard MIME type of the View, if applicable
924 <li> Parameters : a list of required and option parameters the view accepts, if applicable
925 </ul><p>
926 However, at the time of writing, the schema for registering
927 ViewDescriptions in the IVO registry has not been finalized.</p>
928
929 <h5><a name="sec3_4_3_1">3.4.3.1 UI display name</a></h5>
930 <p>If a client is unable to resolve a View identifier into a description, then it MAY just display the identifier as a text string: </p>
931 <ul>
932 <li> Download as urn:table.meta.fits
933 </ul><p>
934 If the client can resolve the View identifier into a description, then the client MAY use the
935 information in the description to display a human readable name and description of the View:
936 </p><ul>
937 <li> Download table metadata as FITS header
938 </ul>
939 <h5><a name="sec3_4_3_2">3.4.3.2 MIME types</a></h5>
940 <p>If a VOSpace service provides HTTP access to the data contained in
941 a Node, then if the ViewDescription contains a MimeType field, this
942 SHOULD be included in the appropriate header field of the HTTP
943 response. </p>
944
945 <h4><a name="sec3_4_4">3.4.4 Default views</a></h4>
946 <p>The following standard URIs are registered under a StandardKeyEnumeration resource [VOStd] in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. They SHALL be used to refer to the default import and export views:
947 </p><ul>
948 <li> ivo://ivoa.net/vospace/core#anyview SHALL be used as the view URI to indicate that a service will accept any view for an import operation
949 <li> ivo://ivoa.net/vospace/core#binaryview SHALL be used as the view URI to import or export data as a binary file
950 <li> ivo://ivoa.net/vospace/core#defaultview SHALL be used by a client to indicate that the service should choose the most appropriate view for a data export
951 </ul>
952
953 <h5><a name="sec3_4_4_1">3.4.4.1 Default import view</a></h5>
954 <p>If a client imports data using this view, the data SHALL be treated as a binary BLOB, and stored as is with no additional processing. This is equivalent to the application/binary MIME type.
955 </p><p>
956 Note, this view is OPTIONAL, and the service may throw a ViewNotSupported exception if it does not accept this view. In particular, this view cannot be used to import data into a StructuredDataNode as the service needs to know about and understand the data format to be able to create the StructuredDataNode.
957 </p><p>
958 Note, this view is only valid for the data import operations, pullToVoSpace and pushToVoSpace. If this view is requested in an export operation, pullFromVoSpace and pushToVoSpace, then the service SHOULD throw a ViewNotSupported exception.
959 </p>
960 <h5><a name="sec3_4_4_1">3.4.4.2 Default export view</a></h5>
961 <p>If a client requests data using this view, the server SHALL choose whichever of the available views (the server) thinks is the most appropriate, based on how the data is stored. In a simple file-based system, this will probably be the same format that the data was originally imported in. In a database table system, this will probably either be VOTable or CVS, depending on the level of metadata available.
962 </p><p>
963 Note, this view is OPTIONAL, and the server may throw a ViewNotSupported exception if it does not provide this view. However, in most cases, it is expected that a service would be able to select an appropriate 'default' format for data held
964 within the service.
965 </p><p>
966 Note, this view is only valid for the data export operations, pullFromVoSpace and pushFromVoSpace. If this view is requested in an import operation, pullToVoSpace and pushToVoSpace, then the service SHOULD throw a ViewNotSupported fault.
967 </p>
968 <h4><a name="sec3_4_5">3.4.5 Container views</a></h4>
969 <p>In VOSpace 2.1, a view of a ContainerNode describes the data representation (format) of a file or data stream that represents the combined contents of the node and its children. If the view describes an archive format (tar, zip, etc.) then a service that accepts this view (format) for a ContainerNode SHALL provide access to the archive contents as children nodes of the container. Whether or not the service actually unpacks the archive is implementation dependent but the service SHALL behave as though it has done so. For example, a client may want to upload a tar file containing several images to a VOSpace service. If they associate it with (upload it to) a (Un)structuredDataNode then it will be treated as a blob and its contents will be not be available. However, if they upload it to a ContainerNode with an accepts view of "tar" then the image files within the tar file will be represented as children nodes of the ContainerNode and accessible like any other data object within the space.
970 </p><p>
971 If a service provides an archive format (tar, zip, etc.) view of a ContainerNode then the service SHALL package the contents of the container and all its child nodes in the specified format.</p>
972 <h3><a name="sec3_5">3.5 Protocols</a></h3>
973 <p>A Protocol describes the parameters required to perform a data transfer using a particular protocol.
974 </p><p>
975 A Protocol representation SHALL have the following members:
976 </p><ul>
977 <li> <i>uri</i>: the Protocol identifier
978 <li> <i>endpoint</i>: the endpoint URL to use for the data transfer
979 additional arguments required for the transfer
980 </ul>
981 <p>A protocol representation MAY have the following members:
982 </p><ul>
983 <li> <i>param</i>: A list of name-value pairs that specify any
984 additional arguments requried for the transfer
985 <li> <i>authType</i> The requested type of authentication method
986 to be used
987 </ul>
988 <p>Note: <i>endpoint</i> will only contain a value after the response
989 from the service is received.
990 </p>
991 <h4><a name="sec3_2_3_1">3.5.1 Protocol identifiers</a></h4>
992 <p>Every new type of Protocol requires a unique URI to identify the Protocol and how to use it. </p>
993
994 <p>The rules for the Protocol identifiers are similar to the rules for namespace URIs in XML schema. The only restriction is that it SHALL be a valid (unique) URI </p><ul>
995
996 <li> An XML schema namespace identifier can be just a simple URN, e.g. urn:my­namespace
997 <li> Within the IVOA, the convention for namespace identifiers is to use a HTTP URL pointing to the namespace schema, or a resource describing it
998 </ul><p>
999 The current VOSpace schema defines Protocol identifiers as anyURI. The only restriction is that it SHALL be a valid (unique) URI.
1000 </p><ul>
1001 <li> A Protocol URI can be a simple URN, e.g. urn:my­protocol
1002 </ul><p>
1003 This may be sufficient for testing and development on a private system, but it is not scalable for use on a public service.
1004 </p><p>
1005 For a production system, any new Protocols SHOULD have unique URIs that can be resolved into to a description of the Protocol.
1006 </p><p>
1007 Ideally, these should be IVO registry URIs that point to a description registered in the IVO registry :
1008 </p><ul>
1009 <li> ivo://my­registry/vospace/protocols#my­protocol
1010 </ul><p>
1011 Using an IVO registry URI to identify Protocols has two main advantages:
1012 </p><ul>
1013 <li> IVO registry URIs are by their nature unique, which makes it easy to ensure that different teams do not accidentally use the same URI
1014 <li> If the IVO registry URI points to a description registered in the IVO registry, this provides a mechanism to discover how to use the Protocol
1015 </ul>
1016
1017 <h4><a name="sec3_5_2">3.5.2 Protocol descriptions</a></h4>
1018 <p>If the URI for a particular Protocol is resolvable, i.e. an IVO registry identifier or a HTTP URL, then it SHOULD point to an XML resource that describes the Protocol. </p>
1019
1020 <p>A ProtocolDescription SHOULD describe the underlying transport protocol, and how it should be used in this context. </p>
1021
1022 <p>A ProtocolDescription SHOULD have the following members:</p>
1023 <ul>
1024 <li> <i>uri</i>: the formal URI of the Protocol
1025 <li> <i>DisplayName</i>: A simple display name of the Protocol
1026 <li> <i>Description</i>: Text block describing describing the underlying transport protocol, and how it should be used in this context
1027 </ul><p>
1028 However, at the time of writing, the schema for registering ProtocolDescriptions in the IVO registry has not been finalized.
1029 </p>
1030 <h5><a name="sec3_5_2_1">3.5.2.1 UI display name</a></h5>
1031 <p>If a client is unable to resolve a Protocol identifier into a description, then it MAY just display the identifier as a text string:
1032 </p><ul>
1033 <li> Download using urn:my­protocol
1034 </ul><p>
1035 If the client can resolve the Protocol identifier into a description, then the client MAY use the information in the description to display a human readable name and description of the Protocol:
1036 </p><ul>
1037 <li> Download using standard HTTP GET
1038 </ul>
1039 <h4><a name="sec3_5_3">3.5.3 Standard protocols and authentication types</a></h4>
1040 <p>Protocol URIs and ProtocolDescriptions for the core set of standard transport protocols are registered under a StandardKeyEnumeration resource [VOStd] in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. The following URIs SHALL be used to represent the standard protocols:</p>
1041 <ul>
1042 <li> ivo://ivoa.net/vospace/core#httpget SHALL be used as the protocol URI for a HTTP GET transfer
1043 <li> ivo://ivoa.net/vospace/core#httpput SHALL be used as the protocol URI for a HTTP PUT transfer
1044 </ul><p>
1045 <p>AuthenticationType URIs and AuthenticationTypeDescriptions for the core set of standard authentication types are registered under a StandardKeyEnumeration resource [VOStd] in the IVOA registry with the resource identifier ivo://ivoa.net/vospace/core. The following URIs SHALL be used to represent the standard authentication types:</p>
1046 <ul>
1047 <li> ivo://ivoa.net/vospace/core#anon SHALL be used as the authentication type URI for no client authentication
1048 <li> ivo://ivoa.net/vospace/core#httpauth SHALL be used as the authentication type URI for HTTP userid password authentication
1049 <li> ivo://ivoa.net/vospace/core#x509 SHALL be used as the authentication type URI for X.509 certification authentication
1050 <li> ivo://ivoa.net/vospace/core#cookie SHALL be used as the authentication type URI for session-based cookie authentication
1051 </ul><p>
1052 However, this is not intended to be a closed list, different
1053 implementations are free to define and use their own transfer
1054 Protocols and authentication types.</p>
1055
1056 <h4><a name="sec3_5_4">3.5.4 Custom protocols</a></h4>
1057 <p>There are several use cases where a specific VOSpace implementation may want to define and use a custom VOSpace transfer Protocol, either extending an existing Protocol, or defining a new one. </p>
1058
1059 <h5><a name="sec3_5_4_1">3.5.4.1 SRB gateway</a></h5>
1060 <p>One example would be a VOSpace service that was integrated with a SRB system. In order to enable the service to use the native SRB transport protocol to transfer data, the service providers would need to register a new ProtocolDescription to represent the SRB transport protocol.
1061 </p><p>
1062 The ProtocolDescription would refer to the technical specification for the SRB transport protocol, and define how it should be used to transfer data to and from the VOSpace service.
1063 </p><p>
1064 Clients that do not understand the SRB transport protocol would not recognize the URI for the SRB Protocol, and would ignore Transfer options offered using this Protocol.
1065 </p><p>
1066 Clients that were able to understand the SRB transport protocol would recognize the URI for the SRB Protocol, and could use the 'srb://..' endpoint address in a Protocol option to transfer data using the SRB transport protocol.
1067 </p><p>
1068 Enabling different groups to define, register and use their own custom Protocols in this way means that support for new transport protocols can be added to VOSpace systems without requiring changes to the core VOSpace specification.
1069 </p><p>
1070 In this particular example, it is expected that one group within the IVOA will work with the SRB team at SDSC to define and register the Protocol URI and ProtocolDescription for using the SRB protocol to transfer data to and from VOSpace systems. </p><p>
1071 Other implementations that plan to use the SRB transport protocol in the same way could use the same Protocol URI and ProtocolDescription to describe data transfers using the SRB transport protocol.
1072 </p><p>
1073 The two implementations would then be able use the common Protocol URI
1074 to negotiate data transfers using the SRB transport protocol.
1075 </p>
1076
1077 <h5><a name="sec3_5_4_2">3.5.4.2 Local NFS transfers</a></h5>
1078 <p>Another example of a custom Protocol use case would to transfer data using the local NFS file system within an institute.
1079 </p><p>
1080 If an institute has one or more VOSpace services co-located with a number of data processing applications, all located within the same local network, then it would be inefficient to use HTTP GET and PUT to transfer the data between the services if they could all access the same local file system.
1081 </p><p>
1082 In this case, the local system administrators could register a custom ProtocolDescription which described how to transfer data using their local NFS file system.
1083 </p><ul>
1084 <li> ivo://my.institute/vospace/protocols#internal­nfs
1085 </ul><p>
1086 Data transfers using this Protocol would be done using file:// URLs pointing to locations within the local NFS file system:
1087 </p><ul>
1088 <li> file:///net/host/path/file
1089 </ul><p>
1090 These URLs would only have meaning to services and applications located within the local network, and would not be usable from outside the network.
1091 </p><p>
1092 Services and applications located within the local network would be configured to recognize the custom Protocol URI, and to use local file system operations to move files within the NFS file system.
1093 </p><p>
1094 Services and applications located outside local network would not recognize the custom Protocol URI and so would not attempt to use the internal file URLs to transfer data.
1095 </p><p>
1096 Note that in this example the custom Protocol URI and the associated ProtocolDescription refer to data transfers using file URLs within a specific local NFS file system.
1097 </p><p>
1098 If a different institute wanted to use a similar system to transfer data within their own local network, then they would have to register their own custom Protocol URI and associated ProtocolDescription.
1099 </p><p>
1100 The two different Protocol URIs and ProtocolDescriptions describe how to use the same underlying transport protocol (NFS) in different contexts.
1101 </p><p>
1102 Enabling different groups to define, register and use their own custom
1103 Protocols in this way means that systems can be configured to use the
1104 best available transport protocols for transferring data, without
1105 conflicting with other systems who may be using similar a transport
1106 protocol in a different context.
1107 </p>
1108 <h3><a name="sec3_6">3.6 Transfers</a></h3>
1109 <p>A Transfer describes the details of a data transfer to or from a
1110 space.
1111 </p><p>
1112 A UWS Job representation [UWS] of a Transfer SHALL have the following parameters:
1113 </p><ul>
1114 <li> <i>target</i>: denotes the VOSpace node to/from which data is to be transferred
1115 <li> <i>direction</i>: denotes the direction of a data transfer
1116 <ul><li> It can be a URI for internal data transfers (move and copy operations) or one of: pushToVoSpace, pullToVoSpace, pushFromVoSpace or pullFromVoSpace - for an external data transfer.</ul>
1117 <li> <i>view</i>: denotes the requested View
1118 <ul><li> For the transfer to be valid, the specified View must match
1119 one of those listed in the accepts or provides list of the Node.
1120 <li>For an internal data transfer, this parameter is not required.</ul>
1121 <li> <i>protocol</i>: denotes the transfer protocol(s) to use
1122 <ul><li> A transfer may contain more than one protocol with different
1123 Protocol URIs.
1124 <li> For an internal data transfer, this parameter is not required.
1125 </ul>
1126 <li> <i>keepBytes</i>: denotes whether the source object is to be kept
1127 in an internal data transfer, i.e. distinguishes between a move and a copy
1128 <ul><li> For an external data transfer, this parameter is not required.</ul>
1129 </ul>
1130 <p>This representation will be used as a child of the <i>jobInfo</i>
1131 element in a UWS Job representation.</p>
1132
1133
1134 <p>The representation of the results of a Transfer SHALL have the following members:
1135 </p><ul>
1136 <li> <i>target</i>: denotes the VOSpace node to/from which data is to be transferred
1137 <li> <i>direction</i>: denotes the direction of a data transfer
1138 <ul><li> It can be a URI for internal data transfers (move and copy operations) or one of: pushToVoSpace, pullToVoSpace, pushFromVoSpace or pullFromVoSpace - for an external data transfer.</ul>
1139 <li> <i>view</i>: A View specifying the requested View
1140 <ul><li> For the transfer to be valid, the specified View must match
1141 one of those listed in the accepts or provides list of the Node
1142 <li>For an internal data transfer, this parameter is not required.</ul>
1143 <li> <i>protocol</i>: one or more Protocols specifying the transfer protocols to use
1144 <ul><li> A Transfer may contain more than one Protocol element with different Protocol URIs
1145 <li> A Transfer may contain more than one Protocol element with the
1146 same Protocol URI with different endpoints
1147 <li>For an internal data transfer, this parameter is not required.</ul></ul>
1148
1149
1150
1151 <h4><a name="sec3_6_1">3.6.1 Service-initiated transfers</a></h4>
1152 <p>Two of the external data transfers (pullToVoSpace and pushFromVoSpace) rely on the server performing the data transfer itself.
1153 </p><p>
1154 The client constructs a Job request containing details of the View and one or more Protocol elements with valid endpoint addresses.
1155 </p><p>
1156 The service MAY ignore Protocols with URIs that it does not recognize.
1157 </p><p>
1158 If the server is unable to handle any of the requested Protocols in a Transfer request, then it SHALL respond with a fault.
1159 </p><p>
1160 The order of the Protocols in the request indicates the order of preference that the client would like the server to use. However, this is only a suggestion, and the server is free to use its own preferences to select which Protocol it uses first.
1161 </p><p>
1162 The service selects the first Protocol it wants to use from the list and attempts to transfer the data using the Protocol endpoint.
1163 </p><p>
1164 If the first attempt fails, the server may choose another Protocol from the list and re-try the transfer using that Protocol endpoint. The status flag will be updated to reflect this.
1165 </p><p>
1166 The server may attempt to transfer the data using any or all of the Protocols in the list until either, the data transfer succeeds, or there are no more Protocol options left.
1167 </p><p>
1168 The server SHALL be allowed to only use each Protocol option once. This allows a data source to issue one time URLs for a Transfer, and cancel each URL once it has been used.
1169 </p><p>
1170 Once one of the Protocol options succeeds the transfer SHALL be considered to have completed - the status flag needs to be updated to reflect this -, and the server is not allowed to use any of the remaining Protocol options. This allows a data source to issue a set of one time URLs for a transfer, and to cancel any unused URLs once the transfer has been completed.
1171 </p><p>
1172 Some Protocols MAY require the service to call a callback address when a data transfer completes. This behavior is specific to the Protocol, and SHOULD be defined in the ProtocolDescription.
1173 </p><p>
1174 If none of the Protocol options succeed, then the transfer SHALL be considered to have failed, and the service SHALL return a fault containing details of the Protocol options it tried. The status flag will be updated to reflect this.
1175 </p>
1176 <h4><a name="sec3_6_2">3.6.2 Client-initiated transfers</a></h4>
1177 <p>Two of the VOSpace external transfer methods rely on an external actor performing the data transfer outside the scope of the service call.
1178 </p><p>
1179 In these methods, the client sends a Job request to the server which SHOULD contain details of the View and one or more protocol parameters.
1180 </p><p>
1181 In effect, the client is sending a list of Protocols that it (the client) wants to use for the transfer.
1182 </p><p>
1183 The service MAY ignore Protocols with URIs that it does not recognize.
1184 </p><p>
1185 The service selects the Protocols from the request that it is capable of handling, and builds a Transfer results response containing the selected Protocol elements filling in valid endpoint addresses for each of them.
1186 </p><p>
1187 If available, the service may choose to consult the authType in the Protocols to construct correct endpoints.
1188 </p><p>
1189 The order of the Protocol elements in the request indicates the order of preference that the client would like to use. However, this is only a suggestion, and the server is free to use its own preferences when generating the list of Protocols in the response.
1190 </p><p>
1191 In effect, the server is responding with the subset of the requested Protocols that it (the server) is prepared to offer.
1192 </p><p>
1193 If the server is unable to accept any of the requested Protocols, then it SHALL respond with a fault.
1194 </p><p>
1195 On receipt of the response, the client can use the list of Protocols itself, or pass them on to another agent to perform the data transfer on its behalf.
1196 </p><p>
1197 The agent MAY ignore Protocols URIs that it does not recognize.
1198 </p><p>
1199 The agent selects the first Protocol it wants to use from the list and attempts to transfer the data using the Protocol endpoint. The status flag will be updated to reflect this.
1200 </p><p>
1201 If the first attempt fails, the agent MAY choose another Protocol from the list and re-try the transfer using that Protocol endpoint.
1202 </p><p>
1203 The agent MAY attempt to transfer the data using any or all of the Protocols in the list until either, the data transfer succeeds, or there are no more Protocol options left.
1204 </p><p>
1205 The agent SHALL be allowed to only use each Protocol option once. This allows a data source to issue one time URLs for a Transfer, and cancel each URL once it has been used.
1206 </p><p>
1207 Once one of the Protocol options succeeds the transfer SHALL be considered to have completed and the status flag will be updated correspondingly. The agent is not allowed to use any of the remaining unused Protocol options. This allows a data source to issue a set of one time URLs for a transfer, and to cancel any unused URLs once the transfer has been completed.
1208 </p><p>
1209 Some Protocols MAY require the agent to call a callback address when a data transfer completes. This behavior is specific to the Protocol, and SHOULD be defined in the ProtocolDescription.
1210 </p><p>
1211 If none of the Protocol options succeed, then the transfer SHALL be
1212 considered to have failed and the status will be updated. </p>
1213
1214 <h3><a name="sec3_7">3.7 Searches</a></h3>
1215 <p>A Search describes the details of data objects in the space which
1216 meet specified search criteria, i.e. that are the results of a
1217 submitted search request.</p>
1218 <p>
1219 A UWS Job representation of a Search SHALL have the following parameters:
1220 </p><ul>
1221 <li> <i>uri</i>: An OPTIONAL identifier indicating from which item to
1222 continue a search
1223 <li> <i>limit</i>: An OPTIONAL limit indicating the maximum number of results in the response
1224 <ul><li> No limit indicates a request for an unpaged list. However the server MAY still impose its own limit on the size of an individual response, splitting the results into more than one page if required</ul>
1225 <li> <i>detail</i>: The level of detail in the results
1226 <ul><li> min : The list contains the minimum detail for each Node with all optional parts removed - the node type should be returned
1227 <ul><li> e.g. &lt;node uri="vos://service/name" xsi:type="Node"/></ul>
1228 <li> max : The list contains the maximum detail for each Node, including any xsi:type specific extensions
1229 <li> properties : The list contains a basic node element with a list of properties for each Node with no xsi:type specific extensions. </ul>
1230 <li> <i>matches</i>: An OPTIONAL search string consisting of
1231 properties and values to match against and joined in conjunction (and) or disjunction (or).
1232 <ul><li>Each property-value pair consists of the uri identifying a
1233 particular property and a regular expression against which the
1234 property values are to be matched: 'uri' = 'regex'
1235 <li> The match pairs can be combined in conjunction and/or disjunction
1236 using 'and' and 'or' respectively. For example: "(property1 =
1237 'value1' and property2 = 'value2') or property3 = 'value3'".
1238 <li> The regex syntax SHALL comply with POSIX conventions.</ul>
1239 <li> <i>node </i>: An OPTIONAL URI(s) identifying the starting node
1240 for a search, i.e., the <i>matches</i> constraints are applied to this
1241 node and its children</ul>
1242 <p>This representation will be used as a child of the <i>jobInfo</i>
1243 element in a UWS Job representation. For example:</p>
1244 <pre>
1245 &lt;uws:jobInfo>
1246 &lt;vos:search>
1247 &lt;vos:detail>properties&lt;/vos:detail>
1248 &lt;vos:matches>ivo://ivoa.net/vospace/core#description='galax'&lt;/vos:matches>
1249 &lt;vos:search>
1250 &lt;uws:jobInfo>
1251 </pre>
1252
1253
1254 <p>The representation of the results of a Search SHALL have the
1255 following members:</p>
1256 <ul><li> <i>nodes</i>: A list containing zero or more Nodes of appropriate
1257 detail identifying the target URIs meeting the search criteria </ul>
1258 </ul>
1259
1260 <h3><a name="sec3_8">3.8 REST bindings</a></h3>
1261 <p>In a REST (Representational State Transfer) binding of VOSpace, each of the objects defined below is available as a web resource with its own URI. </p>
1262 </p>
1263 <table>
1264 <tr>
1265 <td>/properties</td><td>the properties employed in the space</td></tr>
1266 <tr><td>/views</td><td>the views employed in the space</td></tr>
1267 <tr><td>/protocols</td><td>the protocols employed in the space</td></tr>
1268 <tr><td>/searches</td><td>the searches of the space</td></tr>
1269 <tr><td>/nodes/(node-path)</td><td>a Node under the nodes of the space</td></tr>
1270 <tr><td>/transfers</td><td>the transfers for the space</td></tr>
1271 <tr><td>/transfers/(job-id)/results/transferDetails</td><td>the transfer details for
1272 synchronous jobs</td></tr>
1273 </table>
1274 <p>
1275 The service implementor is free to choose the names given in
1276 parentheses above; the other names are part of the VOSpace 2.0
1277 standard.
1278 </p><p>
1279 The endpoint /sync is also defined to receive HTTP POST requests of
1280 synchronous transfer jobs. This should respond with a redirect to the transfer
1281 details for synchronous jobs resource: http://rest-endpoint/transfers/(jobid)/results/transferDetails. Synchronous transfers are
1282 limited to pushToVoSpace and pullFromVoSpace operations only where the
1283 client is requesting endpoint URLs where it can read or write data.
1284 </p><p>
1285 As an optimization, the /sync endpoint should support parameter-based
1286 HTTP GET transfer requests. Instead of returning a redirect to the transferDetails,
1287 the GET to /sync immediately returns the endpoint for performing the data transfer.
1288 Since there is no job created and persisted in this process, there is very little
1289 error reporting that can occur. In the case of an error, clients may wish to fall
1290 back to the HTTP POST to /sync and step through the entire transfer negotiation.
1291 This is an optimized route because it reduces two redirects that the client has to
1292 perform in order to start the data transfer.
1293 </p><p>
1294 In addition, the following Nodes, appearing as part of a
1295 node-path, are reserved:
1296 </p>
1297 <ul>
1298 <li> .auto indicates that the service should auto-generate an endpoint
1299 URI to replace this placeholder (Note: that this is an OPTIONAL
1300 feature of a service)
1301 <li> .null indicates an endpoint that discards all data
1302 written to it and provides no data when read from, i.e. a bit
1303 bucket
1304 </ul>
1305 <p>
1306 The standardID for the service is:
1307 ivo://ivoa.net/std/VOSpace/v2.0. Available resources will then just be
1308 ivo://ivoa.net/std/VOSpace/v2.0#&lt;resourceName>, e.g., ivo://ivoa.net/std/VOSpace/v2.0#nodes.
1309 </p>
1310 <br/>
1311 <h2><a name="sec4">4 Access Control</a></h2>
1312 <p>
1313 VOSpace implementations may support any of the following authentication methods:
1314 <ul>
1315 <li>no authentication (anonymous clients)</li>
1316 <li>digital signatures with X.509 client certificates</li>
1317 <li>user ID and password HTTP authentication</li>
1318 <li>cookies</li>
1319 </ul>
1320 When a client is requesting a transfer from the service, the authentication type (authType) may be supplied along side the list of transfer protocols.
1321 If the service supports the requested authentication type, it may use the authType information to construct the endpoint URL for data transfer, for services may
1322 encounter situations when the URL for data transfer will depend on the authentication type the client wished to use.
1323 </p><p>
1324 The access control policy for a VOSpace is defined by the implementor of that space according to the use cases for which the implementation is intended.
1325 </p><p>
1326 A human-readable description of the implemented access policy must be declared in the registry metadata for the space.
1327 </p><p>
1328 These are the most probable access policies:
1329 </p><ul>
1330 <li> No access control is asserted. Any client can create, read, write and delete nodes anonymously
1331 <li> No authorization is required, but clients must authenticate an identity (for logging purposes) in each request to the space
1332 <li> Clients may not create or change nodes (i.e. the contents of the space are fixed by the implementation or set by some interface other than VOSpace), but any client can read any node without authentication
1333 <li> Nodes are considered to be owned by the user who created them. Only the owner can operate on a node
1334 </ul><p>
1335 No operations to modify the access policy (e.g. to set permissions on an individual node) are included in this standard. Later versions may add such operations. </p><p>
1336 Where the access policy requires authentication of callers, the VOSpace service SHALL support one of the authentication methods defined in the IVOA Single Sign On profile. </p>
1337 <br/>
1338 <h2><a name="sec4">5 Web service operations</a></h2>
1339 <p>A VOSpace 2.1 service SHALL be a REST service with the following operations:
1340 </p><p>
1341 Note: The URL http://(rest-endpoint)/nodes denotes the URL of the top node in the VOSpace. The URL http://(rest-endpoint)/nodes/(path) denotes a specific node within the VOSpace.
1342 </p><p>
1343 Note: When representing a Fault, the exact specified fault name SHALL
1344 be used. If this is followed by some details, the fault SHALL be
1345 separated from the subsequent characters by whitespace.
1346 </p>
1347 <p>
1348 Note: If the service is able to detect an internal system failure
1349 (associated with an HTTP 500 status code) then it should indicate this
1350 as described below if possible.
1351 </p>
1352 <h3><a name="sec5_1">5.1 Service metadata</a></h3>
1353 <p>These operations return comprehensive lists of service-level
1354 metadata, e.g. all protocols supported by the service. Individual
1355 nodes within a service, however, may not necessarily support all of
1356 these, i.e. only container nodes may support archive formats such as
1357 zip or tar.
1358 </p>
1359 <h4><a name="sec5_1_1">5.1.1 getProtocols</a></h4>
1360 <p>Get a list of the transfer Protocols supported by the space
1361 service</p>
1362 <h5><a name="sec5_1_1_1">5.1.1.1 Request</a></h5>
1363 <ul><li>A HTTP GET to http://rest-endpoint/protocols</ul>
1364 <h5><a name="sec5_1_1_2">5.1.1.2 Response</a></h5>
1365 <ul><li> A HTTP 200 status code
1366 <li> A Protocols representation giving:
1367 <ul><li> accepts: A list of Protocols that the service SHALL accept
1368 <ul><li> In this context 'accepting a protocol' means that the service SHALL act as a client for the protocol
1369 <li> e.g. 'accepting httpget' means the service can read data from an external HTTP web server </ul>
1370 <li> provides: A list of Protocols that the service SHALL provide
1371 <ul><li> In this context 'providing a protocol' means that the service SHALL act as a server for the protocol
1372 <li> e.g. 'providing httpget' means the service can act as a http web server </ul>
1373 </ul>
1374 </ul>
1375 <h5><a name="sec5_1_1_3">5.1.1.3 Faults</a></h5>
1376 <ul>
1377 <li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1378 </ul>
1379 <!-- 5.1.1.4 Example -->
1380 <div class="exampleOuter">
1381 <div class="exampleHeader">Example: getProtocols</div>
1382 <div class="exampleWrapper">
1383 <pre>> <b>curl -v http://localhost:8000/vospace-2.0/protocols</b></pre>
1384 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1385 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
1386 > GET /protocols HTTP/1.1
1387 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1388 > Host: localhost:8000
1389 > Accept: */*
1390 >
1391 < HTTP/1.1 200 OK
1392 < Date: Tue, 09 Mar 2010 04:59:12 GMT
1393 < Content-Length: 309
1394 < Content-Type: text/html
1395 < Allow: GET, HEAD, POST, PUT
1396 < Server: CherryPy/3.1.2
1397 <
1398 &lt;protocols xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
1399 &lt;accepts>
1400 &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
1401 &lt;protocol uri="ivo://ivoa.net/vospace/core#httpput"/>
1402 &lt;/accepts>
1403 &lt;provides>
1404 &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget"/>
1405 &lt;protocol uri="ivo://ivoa.net/vospace/core#httpput"/>
1406 &lt;/provides>
1407 &lt;/protocols>
1408 * Connection #0 to host localhost left intact
1409 * Closing connection #0</pre>
1410 </div></div>
1411 <h4><a name="sec5_1_2">5.1.2 getViews</a></h4>
1412 <p>Get a list of the <i>Views</i> and data formats supported by the
1413 space service</p>
1414 <h5><a name="sec5_1_2_1">5.1.2.1 Request</a></h5>
1415 <ul><li> A HTTP GET to http://rest-endpoint/views
1416 </ul>
1417 <h5><a name="sec5_1_2_2">5.1.2.2 Response</a></h5>
1418 <ul><li> A HTTP 200 status code
1419 <li> A Views representation giving:
1420 <ul><li> <i>accepts</i>: A list of Views that the service SHALL accept
1421 <ul><li> In this context 'accepting a view' means that the service SHALL receive input data in this format
1422 <li> A simple file based system may use the reserved View URI ivo://net.ivoa.vospace/views/any to indicate that it can accept data in any format </ul>
1423 <li><i>provides</i>: A list of Views that the service SHALL provide
1424 <ul><li> In this context 'providing a view' means that the service SHALL produce output data in this format
1425 <li> A simple file based system may use the reserved View URI ivo://net.ivoa.vospace/views/any to indicate that it can provide data in any format
1426 </ul></ul>
1427 </ul>
1428 <h5><a name="sec5_1_2_3">5.1.2.3 Faults</a></h5>
1429 <ul>
1430 <li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1431 </ul>
1432 <!-- 5.1.2.4 Example -->
1433 <div class="exampleOuter">
1434 <div class="exampleHeader">Example: getViews</div>
1435 <div class="exampleWrapper">
1436 <pre>
1437 > <b>curl -v "http://localhost:8000/views"</b></pre>
1438 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1439 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
1440 > GET /views HTTP/1.1
1441 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1442 > Host: localhost:8000
1443 > Accept: */*
1444 >
1445 < HTTP/1.1 200 OK
1446 < Date: Tue, 09 Mar 2010 19:36:17 GMT
1447 < Content-Length: 181
1448 < Content-Type: text/html
1449 < Allow: GET, HEAD, POST, PUT
1450 < Server: CherryPy/3.1.2
1451 <
1452 &lt;views xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
1453 &lt;accepts>
1454 &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/>
1455 &lt;/accepts>
1456 &lt;provides>
1457 &lt;view uri="ivo://ivoa.net/vospace/core#defaultview"/>
1458 &lt;/provides>
1459 &lt;/views>
1460 * Connection #0 to host localhost left intact
1461 * Closing connection #0
1462 </pre>
1463 </div></div>
1464 <h4><a name="sec5_1_3">5.1.3 getProperties</a></h4>
1465 <h5><a name="sec5_1_3_1">5.1.3.1 Request</a></h5>
1466 <ul><li> A HTTP GET to http://rest-endpoint/properties
1467 </ul>
1468 <h5><a name="sec5_1_3_2">5.1.3.2 Response</a></h5>
1469 <ul><li> A HTTP 200 status code
1470 <li> A Properties representation including:
1471 <ul><li> <i>accepts</i>: A list of identifiers for the Properties that the service SHALL accept and understand. This refers to metadata (Properties) that is implementation dependent but can be used by a client to control operational aspects of the service: for example, a VOSpace implementation might allow individual users to control the permissions on data objects via a Property called "permissions". If the VOSpace receives a data object with this Property then it 'understands' what this property refers to and can deal with it accordingly.
1472 <li> <i>provides</i>: A list of identifiers for the Properties that the service SHALL provide
1473 <li> <i>contains</i>: A list of identifiers for all the Properties currently used by Nodes within the service
1474 </ul>
1475 </ul>
1476 <h5><a name="sec5_1_3_3">5.1.3.3 Faults</a></h5>
1477 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1478 </ul>
1479 <!-- 5.1.3.4 Example -->
1480 <div class="exampleOuter">
1481 <div class="exampleHeader">Example: getProperties</div>
1482 <div class="exampleWrapper">
1483 <pre>
1484 > <b>curl -v "http://localhost:8000/properties"</b></pre>
1485 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1486 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
1487 > GET /properties HTTP/1.1
1488 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1489 > Host: localhost:8000
1490 > Accept: */*
1491 >
1492 < HTTP/1.1 200 OK
1493 < Date: Tue, 09 Mar 2010 19:43:23 GMT
1494 < Content-Length: 644
1495 < Content-Type: text/html
1496 < Allow: GET, HEAD, POST, PUT
1497 < Server: CherryPy/3.1.2
1498 <
1499 &lt;properties xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
1500 &lt;accepts>
1501 &lt;property uri="ivo://ivoa.net/vospace/core#title"/>
1502 &lt;property uri="ivo://ivoa.net/vospace/core#creator"/>
1503 &lt;property uri="ivo://ivoa.net/vospace/core#description"/>
1504 &lt;/accepts>
1505 &lt;provides>
1506 &lt;property uri="ivo://ivoa.net/vospace/core#availableSpace"/>
1507 &lt;property uri="ivo://ivoa.net/vospace/core#httpput"/>
1508 &lt;/provides>
1509 &lt;contains>
1510 &lt;property uri="ivo://ivoa.net/vospace/core#availableSpace"/>
1511 &lt;property uri="ivo://ivoa.net/vospace/core#title"/>
1512 &lt;property uri="ivo://ivoa.net/vospace/core#creator"/>
1513 &lt;property uri="ivo://ivoa.net/vospace/core#description"/>
1514 &lt;/contains>
1515 &lt;/properties>
1516 * Connection #0 to host localhost left intact
1517 * Closing connection #0
1518 </pre>
1519 </div></div>
1520 <h3><a name="sec5_2">5.2 Creating and manipulating data nodes</a></h3>
1521
1522 <h4><a name="sec5_2_1">5.2.1 createNode</h4>
1523 <p>Create a new node at a specified location</p>
1524 <h5><a name="sec5_2_1_1">5.2.1.1 Request</a></h5>
1525 <ul><li> A HTTP PUT of a node representation to the node URL:
1526 <ul><li> <i>node</i>: A template Node (as defined in Section 3.1) for the node to be created
1527 </ul></ul><p>
1528 A valid uri attribute SHALL be required. The name .auto is a reserved URI to indicate an auto-generated URI for the destination, i.e. given the following URI vos://service/path/.auto a service SHALL create a new unique URI for the node within vos://service/path.
1529 </p><p>
1530 If the Node xsi:type is not specified then a generic node of type Node is implied.
1531 </p><p>
1532 The permitted values of xsi:type are:
1533 </p><ul>
1534 <li> vos:Node
1535 <li> vos:DataNode
1536 <li> vos:UnstructuredDataNode
1537 <li> vos:StructuredDataNode
1538 <li> vos:ContainerNode
1539 <li> vos:LinkNode
1540 </ul><p>
1541 When creating a new Node the service MAY substitute a valid subtype, i.e. If xsi:type is
1542 set to vos:DataNode then this may be implemented as a DataNode, StructuredDataNode
1543 or an UnstructuredDataNode.
1544 </p><p>
1545 The properties of the new Node can be set by adding Properties to the template.
1546 Attempting to set a Property that the service considers to be 'readOnly' SHALL cause a
1547 PermissionDenied fault.
1548 The accepts and provides lists of Views for the Node cannot be set using this method.
1549 </p><p>
1550 The capabilities list for the Node cannot be set using this method.
1551 </p>
1552 <h5><a name="sec5_2_1_2">5.2.1.2 Response</a></h5>
1553 <ul><li> A HTTP 201 status code
1554 <li> A node representation including
1555 <ul><li> <i>node</i>: details of the new Node
1556 </ul></ul><p>
1557 The <i>accepts</i> list of Views for the Node SHALL be filled in by the service based on service
1558 capabilities.
1559 </p><p>
1560 The <i>provides</i> list of Views for the Node MAY not be filled in until some data has been
1561 imported into the Node.
1562 </p><p>
1563 The <i>capabilities</i> list for the Node MAY not be filled in until some data has been imported into the Node.
1564 </p>
1565 </ul>
1566 <h5><a name="sec5_2_1_3">5.2.1.3 Faults</a></h5>
1567 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity body if the operation fails
1568 <li> The service SHALL throw a HTTP 409 status code including a DuplicateNode fault in the entity body if a Node already exists with the same URI
1569 <li> The service SHALL throw a HTTP 400 status code including an InvalidURI fault in the entity body if the requested URI is invalid
1570 <li> The service SHALL throw a HTTP 400 status code including a TypeNotSupported fault in the entity body if the type specified in xsi:type is not supported
1571 <li> The service SHALL throw a HTTP 401 status code including PermissionDenied fault in the entity body if the user does not have permissions to perform the operation
1572 <li> If a parent node in the URI path does not exist then the service SHALL throw a HTTP 404 status code including a ContainerNotFound fault in the entity body.
1573 <ul><li> For example, given the URI path /a/b/c, the service must
1574 throw a HTTP 404 status code including a ContainerNotFound fault in
1575 the entity body if either /a or /a/b do not exist. </ul>
1576 <li> If a parent node in the URI path is a LinkNode, the service SHALL throw a HTTP 400 status code including a LinkFound fault in the entity body.
1577 <ul><li> For example, given the URI path /a/b/c, the service must throw a HTTP 400 status code including a LinkFound fault in the entity body if either /a or /a/b are LinkNodes.
1578 </ul>
1579 </ul>
1580 <!-- 5.2.1.4 Example -->
1581 <div class="exampleOuter">
1582 <div class="exampleHeader">Example: createNode</div>
1583 <div class="exampleWrapper">
1584 <p>The node to be created (newNode.xml) is:</p>
1585 <pre>
1586 &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="vos:UnstructuredDataNode"
1587 xmlns="http://www.ivoa.net/xml/VOSpace/v2.0" uri="vos://nvo.caltech!vospace/mydata1">
1588 &lt;properties>
1589 &lt;property uri="ivo://ivoa.net/vospace/core#description">My important results&lt;/property>
1590 &lt;/properties>
1591 &lt;accepts/>
1592 &lt;provides/>
1593 &lt;capabilities/>
1594 &lt;/node>
1595 </pre>
1596 <pre>
1597 > <b>curl -v -X PUT -d @newNode.xml "http://localhost:8000/nodes/mydata1"</b></pre></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);"><pre>
1598 * Connected to localhost (127.0.0.1) port 8000 (#0)
1599 > PUT /nodes/mydata1 HTTP/1.1
1600 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1601 > Host: localhost:8000
1602 > Accept: */*
1603 > Content-Length: 267
1604 > Content-Type: application/x-www-form-urlencoded
1605 >
1606 < HTTP/1.1 200 Created
1607 < Date: Wed, 10 Mar 2010 00:10:27 GMT
1608 < Content-Length: 323
1609 < Content-Type: text/html
1610 < Allow: GET, HEAD, POST, PUT
1611 < Server: CherryPy/3.1.2
1612 <
1613 * Connection #0 to host localhost left intact
1614 * Closing connection #0
1615 &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1616 xmlns="http://www.ivoa.net/xml/VOSpace/v2.0" xsi:type="vos:UnstructuredDataNode"
1617 uri="vos://nvo.caltech!vospace/mydata1">
1618 &lt;properties>
1619 &lt;property uri="ivo://ivoa.net/vospace/core#description">My important results&lt;/property>
1620 &lt;/properties>
1621 &lt;accepts>
1622 &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/>
1623 &lt;/accepts>
1624 &lt;provides/>
1625 &lt;capabilities/>
1626 &lt;/node>
1627 </pre>
1628 </div></div>
1629 <h4><a name="sec5_2_2">5.2.2 moveNode</h4>
1630 <p>Move a node within a VOSpace service.
1631 </p><p>
1632 Note that this does not cover moving data between two separate VOSpace services.
1633 </p><p>
1634 Moving nodes between separate VOSpace services SHOULD be handled by the client, using the import, export and delete methods.
1635 </p><p>
1636 When the source is a ContainerNode, all its children (the contents of the container) SHALL also be moved to the new destination.
1637 </p><p>
1638 When the destination is an existing ContainerNode, the source SHALL be placed under it (i.e. within the container).
1639 </p>
1640 <p>The <i>Node</i> type cannot be changed using this method.</p>
1641
1642 <h5><a name="sec5_2_2_1">5.2.2.1 Request</a></h5>
1643 <ul><li> A HTTP POST of a Job representation for the transfer (see
1644 section 3.6) to http://rest-endpoint/transfers.
1645 </ul><p>
1646 .auto is a reserved URI to indicate an autogenerated URI for the destination, i.e. vos://service/path/.auto SHALL cause a new unique URI for the node within vos://service/path to be generated.
1647 </p>
1648 <h5><a name="sec5_2_2_2">5.2.2.2 Response</a></h5>
1649 <ul><li>The initial response is a HTTP 303 status code with the
1650 Location header keyword assigned to the created job.</li></ul>
1651 <p>If an autogenerated URI for the destination was specified in the
1652 request then its value SHALL be specified as a result in the Results
1653 List for the completed transfer with the id of "destination":
1654 </p>
1655 <pre>
1656 &lt;uws:job>
1657 ...
1658 &lt;uws:jobInfo>
1659 &lt;vos:direction>vos://nvo.caltech!vospace/mjg/.auto&lt;/vos:direction>
1660 ...
1661 &lt;uws:results>
1662 &lt;uws:result id="destination">vos://nvo.caltech!vospace/mjg/abc123&lt;/uws:result>
1663 &lt;/uws:results>
1664 ...
1665 &lt;/uws:job>
1666 </pre>
1667 <h5><a name="sec5_2_2_3">5.2.2.3 Faults</a></h5>
1668 <p>For all faults, the service shall set the PHASE to "ERROR" in the Job
1669 representation. The &lt;errorSummary&gt; element in the Job representation
1670 shall be set to the appropriate value for the fault type and the
1671 appropriate fault representation (see section 5.5) provided at the error URI:
1672 http://rest-endpoint/transfers/(jobid)/error.</p>
1673 <table>
1674 <tr><th align="left">Fault description</th><th
1675 align="left">errorSummary</th><th align="left">Fault representation</th></tr>
1676 <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
1677 <tr><td>User does not have permissions to perform the
1678 operation</td><td>Permission Denied</td><td>PermissionDenied</td></tr>
1679 <tr><td>Source node does not exist</td><td>Node Not Found</td><td>NodeNotFound</td></tr>
1680 <tr><td>Destination node already exists and it is not a
1681 ContainerNode</td><td>Duplicate Node</td><td>DuplicateNode</td></tr>
1682 <tr><td>A specified URI is invalid</td><td>Invalid
1683 URI</td><td>InvalidURI</td></tr>
1684 </table>
1685 <!-- 5.2.2.4 Example -->
1686 <div class="exampleOuter">
1687 <div class="exampleHeader">Example: moveNode</div>
1688 <div class="exampleWrapper">
1689 <p>The Job to be submitted (newJob.xml) is:</p>
1690 <pre>
1691 &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0" >
1692 &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
1693 &lt;vos:direction>vos://nvo.caltech!vospace/mydata2&lt;/vos:direction>
1694 &lt;vos:keepBytes>false&lt;/vos:keepBytes>
1695 &lt;/vos:transfer>
1696 </pre>
1697
1698 <pre>
1699 > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"</b>
1700 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1701 <pre>
1702 * Connected to localhost (127.0.0.1) port 8000 (#0)
1703 > POST /transfers HTTP/1.1
1704 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1705 > Host: localhost:8000
1706 > Accept: */*
1707 > Content-Length: 762
1708 > Content-Type: application/x-www-form-urlencoded
1709 >
1710 < HTTP/1.1 303 See Other
1711 < Content-Length: 174
1712 < Server: CherryPy/3.1.2
1713 < Location: http://localhost:8080/transfers/ec200b5ff77641fb841978a85d1f7245
1714 < Allow: GET, HEAD, POST, PUT
1715 < Date: Thu, 11 Mar 2010 19:54:00 GMT
1716 < Content-Type: text/html
1717 <
1718 * Connection #0 to host localhost left intact
1719 * Closing connection #0
1720 This resource can be found at <a href='http://localhost:8000/transfers/ec200b5ff77641fb841978a85d1f7245'>http://localhost:8000/transfers/ec200b5ff77641fb841978a85d1f7245</a>.
1721 </pre></div>
1722 <div class="exampleWrapper">
1723 <p>The status of the job can now be polled at the job location:</p>
1724 <pre>
1725 > <b>curl -v "http://localhost:8000/transfers/ec200b5ff77641fb841978a85d1f7245"</b></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1726 <pre>
1727 * Connected to localhost (127.0.0.1) port 8000 (#0)
1728 > GET /transfers/ccfd4ba0dd9f4406b2039c4358ba8ef3 HTTP/1.1
1729 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1730 > Host: localhost:8000
1731 > Accept: */*
1732 >
1733 < HTTP/1.1 200 OK
1734 < Date: Thu, 11 Mar 2010 19:54:02 GMT
1735 < Content-Length: 802
1736 < Content-Type: text/html
1737 < Allow: GET, HEAD, POST, PUT
1738 < Server: CherryPy/3.1.2
1739 <
1740 &lt;uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
1741 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1742 xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0"
1743 xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd ">
1744 &lt;uws:jobId>ec200b5ff77641fb841978a85d1f7245&lt;/uws:jobId>
1745 &lt;uws:ownerId xsi:nil="true"/>
1746 &lt;uws:phase>EXECUTING&lt;/uws:phase>
1747 &lt;uws:startTime>2010-03-11T19:54:00.433058&lt;/uws:startTime>
1748 &lt;uws:endTime xsi:nil="true"/>
1749 &lt;uws:executionDuration>0&lt;/uws:executionDuration>
1750 &lt;uws:destruction xsi:nil="true"/>
1751 &lt;uws:jobInfo>
1752 &lt;vos:transfer>
1753 &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
1754 &lt;vos:direction>vos://nvo.caltech!vospace/mydata2&lt;/vos:direction>
1755 &lt;vos:keepBytes>false&lt;/vos:keepBytes>
1756 &lt;/vos:transfer>
1757 &lt;/uws:jobInfo>
1758 &lt;uws:results/>
1759 * Connection #0 to host localhost left intact
1760 * Closing connection #0
1761 &lt;/uws:job>
1762 </pre>
1763 </div></div>
1764
1765 <h4><a name="sec5_2_3">5.2.3 copyNode</h4>
1766 <p>Copy a node with a VOSpace service.
1767 </p><p>
1768 Note that this does not cover copying data between two separate VOSpace services.
1769 </p><p>
1770 Copying nodes between separate VOSpace services SHOULD be handled by the client, using the import and export methods.
1771 </p><p>
1772 When the source is a ContainerNode, all its children (the full contents of the container) SHALL get copied, i.e. this is a deep recursive copy.
1773 </p><p>
1774 When the destination is an existing ContainerNode, the copy SHALL be placed under it (i.e. within the container).
1775 </p>
1776 <p>The <i>Node</i> type cannot be changed using this method.</p>
1777 <h5><a name="sec5_2_3_1">5.2.3.1 Request</a></h5>
1778 <ul><li> A HTTP POST of a Job representation for the transfer (see
1779 section 3.6) to http://rest-endpoint/transfers.</ul>
1780 <p>
1781 .auto is the reserved URI to indicate an auto-generated URI for the destination, i.e. vos://service/path/.auto SHALL cause a new unique URI for the node within vos://service/path to be generated.
1782 </p>
1783 <h5><a name="sec5_2_3_2">5.2.3.2 Response</a></h5>
1784 <ul><li>The initial response is a HTTP 303 status code with the
1785 Location header keyword assigned to the created job.</li></ul>
1786 <p>If an autogenerated URI for the destination was specified in the
1787 request then its value SHALL be specified as a result in the Results
1788 List for the completed transfer with the id of "destination":
1789 </p>
1790 <pre>
1791 &lt;uws:job>
1792 ...
1793 &lt;uws:jobInfo>
1794 &lt;vos:direction>vos://nvo.caltech!vospace/mjg/.auto&lt;/vos:direction>
1795 ...
1796 &lt;uws:results>
1797 &lt;uws:result id="destination">vos://nvo.caltech!vospace/mjg/abc123&lt;/uws:result>
1798 &lt;/uws:results>
1799 ...
1800 &lt;/uws:job>
1801 </pre>
1802 <h5><a name="sec5_2_3_3">5.2.3.3 Faults</a></h5>
1803 <p>For all faults, the service shall set the PHASE to "ERROR" in the Job
1804 representation. The &lt;errorSummary&gt; element in the Job representation
1805 shall be set to the appropriate value for the fault type and the
1806 appropriate fault representation (see section 5.5) provided at the error URI:
1807 http://rest-endpoint/transfers/(jobid)/error.</p>
1808 <table>
1809 <tr><th align="left">Fault description</th><th
1810 align="left">errorSummary</th><th align="left">Fault representation</th></tr>
1811 <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
1812 <tr><td>User does not have permissions to perform the
1813 operation</td><td>Permission Denied</td><td>PermissionDenied</td></tr>
1814 <tr><td>Source node does not exist</td><td>Node Not Found</td><td>NodeNotFound</td></tr>
1815 <tr><td>Destination node already exists and it is not a
1816 ContainerNode</td><td>Duplicate Node</td><td>DuplicateNode</td></tr>
1817 <tr><td>A specified URI is invalid</td><td>Invalid
1818 URI</td><td>InvalidURI</td></tr>
1819 </table>
1820
1821 <!-- 5.2.3.4 Example -->
1822 <div class="exampleOuter">
1823 <div class="exampleHeader">Example: copyNode</div>
1824 <div class="exampleWrapper">
1825 <p>The Job to be submitted (newJob.xml) is:</p>
1826 <pre>
1827 &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0">
1828 &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
1829 &lt;vos:direction>vos://nvo.caltech!vospace/mydir/.auto&lt;/vos:direction>
1830 &lt;vos:keepBytes>true&lt;/vos:keepBytes>
1831 &lt;/vos:transfer>
1832 </pre>
1833
1834 <pre>
1835 > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"</b>
1836 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1837 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
1838 > POST /transfers HTTP/1.1
1839 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1840 > Host: localhost:8000
1841 > Accept: */*
1842 > Content-Length: 765
1843 > Content-Type: application/x-www-form-urlencoded
1844 >
1845 < HTTP/1.1 303 See Other
1846 < Content-Length: 174
1847 < Server: CherryPy/3.1.2
1848 < Location: http://localhost:8080/transfers/6fbb28afec94417ba256d705f5e1f966
1849 < Allow: GET, HEAD, POST, PUT
1850 < Date: Thu, 11 Mar 2010 21:28:19 GMT
1851 < Content-Type: text/html
1852 <
1853 * Connection #0 to host localhost left intact
1854 * Closing connection #0
1855 This resource can be found at <a href='http://localhost:8000/transfers/6fbb28afec94417ba256d705f5e1f966'>http://localhost:8000/transfers/6fbb28afec94417ba256d705f5e1f966</a>.
1856 </pre></div>
1857 <div class="exampleWrapper">
1858
1859 <p>The status of the job can now be polled at the job location:</p>
1860 <pre>
1861 > <b>curl -v "http://localhost:8000/transfers/63fa39fb18f244c18c991ed2f96d26cd"</b></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);"><pre>
1862 * Connected to localhost (127.0.0.1) port 8000 (#0)
1863 > GET /transfers/63fa39fb18f244c18c991ed2f96d26cd HTTP/1.1
1864 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1865 > Host: localhost:8000
1866 > Accept: */*
1867 >
1868 < HTTP/1.1 200 OK
1869 < Date: Thu, 11 Mar 2010 21:28:21 GMT
1870 < Content-Length: 950
1871 < Content-Type: text/html
1872 < Allow: GET, HEAD, POST, PUT
1873 < Server: CherryPy/3.1.2
1874 <
1875 &lt;uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
1876 xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1877 xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd ">
1878 &lt;uws:jobId>6fbb28afec94417ba256d705f5e1f966&lt;/uws:jobId>
1879 &lt;uws:ownerId xsi:nil="true"/>
1880 &lt;uws:phase>COMPLETED&lt;/uws:phase>
1881 &lt;uws:startTime>2010-03-11T21:28:19.200324&lt;/uws:startTime>
1882 &lt;uws:endTime>2010-03-11T21:28:19.200529&lt;/uws:endTime>
1883 &lt;uws:executionDuration>0&lt;/uws:executionDuration>
1884 &lt;uws:destruction xsi:nil="true"/>
1885 &lt;uws:jobInfo>
1886 &lt;vos:transfer>
1887 &lt;vos:keepBytes>true&lt;/vos:keepBytes>
1888 &lt;vos:direction>vos://nvo.caltech!vospace/mydir/.auto&lt;/vos:direction>
1889 &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
1890 &lt;/vos:transfer>
1891 &lt;uws:jobInfo>
1892 &lt;uws:results>
1893 &lt;uws:result id="destination" xlink:href="vos://nvo.caltech!vospace/mydir/ef9ce281f5bd4bff92c8991580cddff4"/>
1894 &lt;/uws:results>
1895 * Connection #0 to host localhost left intact
1896 * Closing connection #0
1897 &lt;/uws:job>
1898 </pre></div></div>
1899
1900 <h4><a name="sec5_2_4">5.2.4 deleteNode</h4>
1901 <p>Delete a node.</p>
1902
1903 <p>When the target is a ContainerNode, all its children (the contents of the container) SHALL also be deleted.</p>
1904
1905 <p>Note that the same operation can also be achieved with a moveNode
1906 (see 5.2.2) with a .null node as the direction (destination node).</p>
1907
1908 <h5><a name="sec5_2_4_1">5.2.4.1 Request</a></h5>
1909 <ul> <li> A HTTP DELETE to the URL of an existing node
1910 </ul>
1911 <h5><a name="sec5_2_4_2">5.2.4.2 Response</a></h5>
1912 <ul><li> A HTTP 204 status code
1913 </ul>
1914 <h5><a name="sec5_2_4_3">5.2.4.3 Faults</a></h5>
1915 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
1916 <li> The service SHALL throw a HTTP 401 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
1917 <li> The service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if the target node does not exist
1918 <li> If a parent node in the URI path does not exist then the service SHALL throw a HTTP 404 status code including a ContainerNotFound fault in the entity-body
1919 <ul><li> For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a ContainerNotFound fault in the entity-body if either /a or /a/b do not exist.</ul>
1920 <li> If a parent node in the URI path is a LinkNode, the service SHALL throw a HTTP 400 status code including a LinkFound fault in the entity-body.
1921 <ul><li> For example, given the URI path /a/b/c, the service must throw a HTTP 400 status code including a LinkFound fault in the entity-body if either /a or /a/b are LinkNodes.</ul>
1922 <li> If the target node in the URI path does not exist, the service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body.
1923 <ul><li> For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if /a/b/c does not exist.
1924 </ul>
1925 </ul>
1926
1927 <!-- 5.2.4.4 Example -->
1928 <div class="exampleOuter">
1929 <div class="exampleHeader">Example: deleteNode</div>
1930 <div class="exampleWrapper">
1931 <pre>
1932 > <b>curl -v -X DELETE "http://localhost:8000/nodes/mydata1"</b></pre>
1933 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
1934 <pre>
1935 * Connected to localhost (127.0.0.1) port 8000 (#0)
1936 > DELETE /nodes/mydata1 HTTP/1.1
1937 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
1938 > Host: localhost:8000
1939 > Accept: */*
1940 >
1941 < HTTP/1.1 200 OK
1942 < Date: Thu, 11 Mar 2010 22:08:22 GMT
1943 < Content-Length: 0
1944 < Content-Type: text/html
1945 < Allow: DELETE, GET, HEAD, POST, PUT
1946 < Server: CherryPy/3.1.2
1947 <
1948 * Connection #0 to host localhost left intact
1949 * Closing connection #0
1950 </pre>
1951 </div></div>
1952
1953 <h3><a name="sec5_3">5.3 Accessing metadata</a></h3>
1954
1955 <h4><a name="sec5_3_1">5.3.1 getNode</h4>
1956 <p>Get the details for a specific Node.</p>
1957 <h5><a name="sec5_3_1_1">5.3.1.1 Request</a></h5>
1958 <ul><li> A HTTP GET to the URL of an existing node
1959 http://rest-endpoint/nodes/path
1960 </li></ul>
1961 <p>This can take the optional parameters to control the size of the response:</p>
1962 <ul>
1963 <li><i>detail</i> with values of:
1964 <ul><li>min: the returned record for the node contains minimum
1965 detail with all optional parts removed - the node type should be
1966 returned
1967 <ul><li>e.g. &lt;Node uri="vos://service/name" xsi:type="Node"/></ul>
1968 <li>max: the returned record for the node contains the maximum
1969 detail, including any xsi:type specific extensions
1970 <li>properties: the returned record for the node contains the
1971 basic node element with a list of properties but no xsi:type
1972 specific extensions
1973 </ul>
1974 <li><i>uri</i> with a value of a VOSpace identifier, URI-encoded
1975 according to RFC2396
1976 <li><i>limit</i> with an integer value indicating the maximum number of results in the response.
1977 <ul><li>No limit indicates a request for an unpaged list. However the
1978 server MAY still impose its own limit on the size of an individual
1979 response, splitting the results into more than one page if required/ </ul>
1980 </ul>
1981
1982 <p>
1983 The list of supported protocols for a node can be retrieved with:</p>
1984 <ul>
1985 <li> A HTTP POST of an empty protocol representation to the URL of an
1986 existing node http://rest-endpoint/nodes/path
1987 </ul>
1988 <h5><a name="sec5_3_1_2">5.3.1.2 Response</a></h5>
1989 <ul><li> A HTTP 200 status code and a Node representation in the entity-body
1990 </ul><p>
1991 When no parameters are present in the request, the full expanded
1992 record for the node SHALL be returned, including any xsi:type specific
1993 extensions; otherwise the appropriate form for the specified value of
1994 the "detail" parameter SHALL be returned.
1995 </p>
1996 <p>When the node is a container, the returned record will also contain
1997 a list of direct children nodes in the container (as &lt;node>
1998 subelements under the &lt; nodes> element).</p>
1999 <p>If a "uri" and "offset" are specified in the request then the returned
2000 list will consist of the subset of children which begins at the node
2001 matching the specified value of the "uri" parameter and with
2002 cardinality matching the specified value of the "offset" parameter
2003 drawn from an ordered sequence of all children. The ordering is
2004 determined by the server but results must always be drawn from the
2005 same ordered sequence.
2006 <h5><a name="sec5_3_1_3">5.3.1.3 Faults</a></h5>
2007 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
2008 <li> The service SHALL throw a HTTP 401 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
2009 <li> The service SHALL throw a HTTP 404 status code including a NodeNotFound fault in the entity-body if the target Node does not exist
2010 </ul>
2011
2012 <!-- 5.3.1.4 Example -->
2013 <div class="exampleOuter">
2014 <div class="exampleHeader">Example: getNode</div>
2015 <div class="exampleWrapper">
2016 <pre>
2017 > <b>curl -v "http://localhost:8000/nodes/mydir?detail=min&uri=vos://nvo.caltech!vospace/mydir/ngc3401"</b></pre>
2018 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2019 <pre>
2020 * Connected to localhost (127.0.0.1) port 8000 (#0)
2021 > GET /nodes/mydir?detail=min&uri=vos://nvo.caltech!vospace/mydir/ngc3401 HTTP/1.1
2022 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2023 > Host: localhost:8000
2024 > Accept: */*
2025 >
2026 < HTTP/1.1 200 OK
2027 < Date: Fri, 12 Mar 2010 04:05:39 GMT
2028 < Content-Length: 593
2029 < Content-Type: text/html
2030 < Allow: DELETE, GET, HEAD, POST, PUT
2031 < Server: CherryPy/3.1.2
2032 <
2033 &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2034 xsi:type="vos:ContainerNode" uri="vos://nvo.caltech!vospace/mydir"
2035 xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
2036 &lt;properties>
2037 &lt;property uri="ivo://ivoa.net/vospace/core#description">My award winning images&lt;/property>
2038 &lt;/properties>
2039 &lt;accepts>
2040 &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/>
2041 &lt;/accepts>
2042 &lt;provides>
2043 &lt;view uri="ivo://ivoa/net/vospace/core#defaultview"/>
2044 &lt;/provides>
2045 &lt;capabilities/>
2046 &lt;nodes>
2047 &lt;node uri="vos://nvo.caltech!vospace/mydir/ngc4323"/>
2048 &lt;node uri="vos://nvo.caltech!vospace/mydir/ngc5796"/>
2049 &lt;node uri="vos://nvo.caltech!vospace/mydir/ngc6801"/>
2050 &lt;/nodes>
2051 &lt;/node>
2052 * Connection #0 to host localhost left intact
2053 * Closing connection #0
2054 </pre>
2055 </div></div>
2056 <h4><a name="sec5_3_2">5.3.2 setNode</h4>
2057 <p>Set the property values for a specific Node</p>
2058
2059 <h5><a name="sec5_3_2_1">5.3.2.1 Request</a></h5>
2060 <ul><li> A HTTP POST of a Node representation to the URL of an existing node http://rest-endpoint/nodes/path including:
2061 <ul><li> node: A Node containing the Node uri and a list of the Properties to set (as defined in section 3.1)
2062 </ul></ul><p>
2063 This will add or update the node properties including any xsi:type specific elements.
2064 </p><p>
2065 The operation is the union of existing values and new ones.
2066 </p><p>
2067 <li> An empty value sets the value to blank.
2068 <li> To delete a Property, set the xsi:nil attribute to true
2069 </p><p>
2070 This method cannot be used to modify the Node type.
2071 </p><p>
2072 This method cannot be used to modify the accepts or provides list of Views for the Node.
2073 </p>
2074 <p>This method cannot be used to create children of a container Node.</p>
2075 <h5><a name="sec5_3_2_2">5.3.2.2 Response</a></h5>
2076 <ul<li> A HTTP 200 status code and a Node representation in the entity-body
2077 </ul><p>
2078 The full expanded record for the node SHALL be returned, including any xsi:type specific extensions.
2079 </p>
2080 <h5><a name="sec5_3_2_3">5.3.2.3 Faults</a></h5>
2081 <ul><li> The service SHOULD throw a HTTP 500 status code including an InternalFault fault in the entity-body if the operation fails
2082 <li> The service SHALL throw a HTTP 401 status code including a PermissionDenied fault in the entity-body if the request attempts to modify a read-only Property
2083 <li> The service SHALL throw a HTTP 401 status code including a PermissionDenied fault in the entity-body if the user does not have permissions to perform the operation
2084 <li> The service SHALL throw a HTTP 404 status code including a
2085 NodeNotFound fault in the entity-body if the target Node does not
2086 exist
2087 <li> If a parent node in the URI path does not exist then the service SHALL throw a HTTP 404 status code including a ContainerNotFound fault in the entity-body
2088 <ul><li> For example, given the URI path /a/b/c, the service must throw a HTTP 404 status code including a ContainerNotFound fault in the entity-body if either /a or /a/b do not exist.</ul>
2089 <li> The service SHALL throw a HTTP 400 status code including an InvalidArgument fault in the entity-body if a specified property value is invalid
2090 </ul>
2091
2092 <!-- 5.3.2.4 Example -->
2093 <div class="exampleOuter">
2094 <div class="exampleHeader">Example: setNode</div>
2095 <div class="exampleWrapper">
2096 <p>The updated node (newNode.xml) is:</p>
2097 <pre>
2098 &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2099 xsi:type="vos:UnstructuredDataNode"
2100 uri="vos://nvo.caltech!vospace/mydata1"
2101 xmlns="http://www.ivoa.net/xml/VOSpace/v2.0">
2102 &lt;properties>
2103 &lt;property uri="ivo://ivoa.net/vospace/core#date">2010-03-12&lt;/property>
2104 &lt;/properties>
2105 &lt;accepts/>
2106 &lt;provides/>
2107 &lt;capabilities/>
2108 &lt;/node>
2109 </pre>
2110 <pre>
2111 > <b>curl -v -X POST -d @newNode.xml "http://localhost:8000/nodes/mydata1"</b>
2112 </pre></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2113 <pre>
2114 * Connected to localhost (127.0.0.1) port 8000 (#0)
2115 > POST /nodes/mydata1 HTTP/1.1
2116 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2117 > Host: localhost:8000
2118 > Accept: */*
2119 > Content-Length: 309
2120 > Content-Type: application/x-www-form-urlencoded
2121 >
2122 < HTTP/1.1 200 OK
2123 < Date: Fri, 12 Mar 2010 18:49:25 GMT
2124 < Content-Length: 445
2125 < Content-Type: text/html
2126 < Allow: DELETE, GET, HEAD, POST, PUT
2127 < Server: CherryPy/3.1.2
2128 <
2129 &lt;node xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2130 xsi:type="vos:UnstructuredDataNode" uri="vos://nvo.caltech!vospace/mydata1"
2131 xmlns="http://www.ivoa.net/xml/VOSpace/v2.0" busy="false">
2132 &lt;properties>
2133 &lt;property uri="ivo://ivoa.net/vospace/core#description">My important results&lt;/property>
2134 &lt;property uri="ivo://ivoa.net/vospace/core#date">2010-03-12&lt;/property>
2135 &lt;/properties>
2136 &lt;accepts>
2137 &lt;view uri="ivo://ivoa.net/vospace/core#anyview"/>
2138 &lt;/accepts>
2139 &lt;provides/>
2140 &lt;capabilities/>
2141 &lt;/node>
2142 * Connection #0 to host localhost left intact
2143 * Closing connection #0
2144 </pre></div></div>
2145
2146 <h4><a name="sec5_3_3">5.3.3 findNodes</h4>
2147 <p>Find nodes whose properties match the specified values.
2148 </p><p>
2149 This operation is OPTIONAL.
2150 </p>
2151 <h5><a name="sec5_3_3_1">5.3.3.1 Request</a></h5>
2152 <ul><li> A HTTP POST of a Job representation of a Search (see section
2153 3.7) to http://rest-endpoint/searches
2154 </ul>
2155 <p>
2156 A null value of the "matches" parameter implies a full listing of the space.
2157 </p>
2158 </ul>
2159 <h5><a name="sec5_3_3_2">5.3.3.2 Response</a></h5>
2160 <ul><li>The initial response is a HTTP 303 status code with the
2161 Location header keyword assigned to the created job.
2162 </li></ul>
2163 <p>The search results representation can be retrieved directly from the
2164 link reported in the Results List, available from the results endpoint -
2165 http://rest-endpoint/searches/(jobid)/results -, the standard UWS location
2166 under the results endpoint - http://rest-endpoint/searches/(jobid)/results/searchDetails - (which may well just be a redirect to the
2167 former link), or as part of the full Job representation from
2168 http://rest-endpoint/searches/(jobid). The result element in the
2169 Results List SHALL have an id of "searchDetails":</p>
2170 <pre>
2171 &lt;uws:job>
2172 ...
2173 &lt;uws:results>
2174 &lt;uws:result id="searchDetails" xlink:href="http://rest-endpoint/searches/(jobid)/results/listing1"/>
2175 &lt;/uws:results>
2176 ...
2177 &lt;/uws:job>
2178 </pre>
2179
2180 <h5><a name="sec5_3_3_3">5.3.3.3 Faults</a></h5>
2181 <p>For all faults, the service shall set the PHASE to "ERROR" in the Job
2182 representation. The &lt;errorSummary&gt; element in the Job representation
2183 shall be set to the appropriate value for the fault type and the
2184 appropriate fault representation (see section 5.5) provided at the error URI:
2185 http://rest-endpoint/transfers/(jobid)/error.</p>
2186 <table>
2187 <tr><th align="left">Fault description</th><th
2188 align="left">errorSummary</th><th align="left">Fault representation</th></tr>
2189 <tr><td>Operation not supported</td><td>Operation Not Supported</td><td>OperationNotSupported</td></tr>
2190 <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
2191 <tr><td>User does not have permissions to perform the
2192 operation</td><td>Permission
2193 Denied</td><td>PermissionDenied</td></tr>
2194 <tr><td>A particular property is specified and does not exist in the
2195 space</td><td>Property Not Found</td><td>PropertyNotFound</td></tr>
2196 </table>
2197
2198 <!-- 5.3.3.4 Example -->
2199
2200 <div class="exampleOuter">
2201 <div class="exampleHeader">Example: findNodes</div>
2202 <div class="exampleWrapper">
2203 <p>The Job to be submitted (newJob.xml) is:</p>
2204 <pre>&lt;vos:search xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0">
2205 &lt;vos:detail>properties&lt;/vos:detail>
2206 &lt;vos:matches>ivo://ivoa.net/vospace/core#description='galax'&lt;/vos:matches>
2207 &lt;vos:search>
2208 </pre>
2209 <pre>
2210 > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/searches"</b></pre>
2211 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2212 <pre>
2213 * Connected to localhost (127.0.0.1) port 8000 (#0)
2214 > POST /searches HTTP/1.1
2215 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2216 > Host: localhost:8000
2217 > Accept: */*
2218 > Content-Length: 684
2219 > Content-Type: application/x-www-form-urlencoded
2220 >
2221 < HTTP/1.1 303 See Other
2222 < Content-Length: 172
2223 < Server: CherryPy/3.1.2
2224 < Location: http://localhost:8080/searches/8c5b0f78cd5a44af8694f10da1b92060
2225 < Allow: DELETE, GET, HEAD, POST, PUT
2226 < Date: Fri, 12 Mar 2010 19:50:12 GMT
2227 < Content-Type: text/html
2228 <
2229 * Connection #0 to host localhost left intact
2230 * Closing connection #0
2231 This resource can be found at <a href='http://localhost:8080/searches/8c5b0f78cd5a44af8694f10da1b92060'>http://localhost:8080/searches/8c5b0f78cd5a44af8694f10da1b92060</a>
2232 </pre></div>
2233 <div class="exampleWrapper">
2234 <p>The status of the job can now be polled at the job location:</p>
2235 <pre>
2236 > <b>curl -v "http://localhost:8000/searches/8c6e7bc53ee848638cda35817e47da65"</b></pre></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2237 <pre>
2238 * Connected to localhost (127.0.0.1) port 8000 (#0)
2239 > GET /searches/8c6e7bc53ee848638cda35817e47da65 HTTP/1.1
2240 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2241 > Host: localhost:8000
2242 > Accept: */*
2243 >
2244 < HTTP/1.1 200 OK
2245 < Date: Fri, 12 Mar 2010 19:51:24 GMT
2246 < Content-Length: 891
2247 < Content-Type: text/html
2248 < Allow: DELETE, GET, HEAD, POST, PUT
2249 < Server: CherryPy/3.1.2
2250 <
2251 &lt;uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
2252 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd ">
2253 &lt;uws:jobId>8c6e7bc53ee848638cda35817e47da65&lt;</uws:jobId>
2254 &lt;uws:ownerId xsi:nil="true"/>
2255 &lt;uws:phase>COMPLETED&lt;/uws:phase>
2256 &lt;uws:startTime>2010-03-12T19:50:56.552278&lt;/uws:startTime>
2257 &lt;uws:endTime>2010-03-12T19:50:56.562416&lt;/uws:endTime>
2258 &lt;uws:executionDuration>0&lt;/uws:executionDuration>
2259 &lt;uws:destruction xsi:nil="true"/>
2260 &lt;uws:jobInfo>
2261 &lt;vos:search>
2262 &lt;vos:detail>properties&lt;/vos:detail>
2263 &lt;vos:matches>ivo://ivoa.net/vospace/core#description='galax'&lt;/vos:matches>
2264 &lt;vos:search>
2265 &lt;uws:jobInfo>
2266 &lt;uws:results>
2267 &lt;uws:result id="searchDetails" xlink:href="http://localhost:8000/searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1"/>
2268 &lt;/uws:results>
2269 &lt;/uws:job>
2270 * Connection #0 to host localhost left intact
2271 * Closing connection #0
2272 </pre></div>
2273 <div class="exampleWrapper">
2274 <p>Once the Job has completed, the result can be obtained from the URL
2275 reported in the result element:</p>
2276 <pre>
2277 > <b>curl -v "http://localhost:8000/searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1"</b></pre>
2278 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2279 <pre>
2280 * Connected to localhost (127.0.0.1) port 8000 (#0)
2281 > GET /searches/d55814f88d974c21afe5ad50e4e875c8/results/listing1 HTTP/1.1
2282 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2283 > Host: localhost:8000
2284 > Accept: */*
2285 >
2286 < HTTP/1.1 200 OK
2287 < Date: Fri, 12 Mar 2010 20:29:25 GMT
2288 < Content-Length: 586
2289 < Content-Type: text/html
2290 < Allow: DELETE, GET, HEAD, POST, PUT
2291 < Server: CherryPy/3.1.2
2292 <
2293 &lt;nodes xmlns="http://www.ivoa.net/xml/VOSpace/v2.0"
2294 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
2295 &lt;node uri="vos://nvo.caltech!vospace/mydir/img1" xsi:type="vos:UnstructuredDataNode">
2296 &lt;properties>
2297 &lt;property uri="ivo://ivoa.net/vospace/core#description">This is an R-band image of the galaxy NGC 3276&lt;/property>
2298 &lt;/properties>
2299 &lt;/node>
2300 &lt;node uri="vos://nvo.caltech!vospace/mydir/img5" xsi:type="vos:StructuredDataNode">
2301 &lt;properties>
2302 &lt;property uri="ivo://ivoa.net/vospace/core#description">This is a Chandra mosaic of the Fornax cluster of galaxies&lt;/property>
2303 &lt;/properties>
2304 &lt;/node>
2305 &lt;/nodes>
2306 * Connection #0 to host localhost left intact
2307 * Closing connection #0
2308 </pre></div></div>
2309
2310 <h3><a name="sec5_4">5.4 Transferring data</a></h3>
2311 <p>Two modes are supported for external data transfers: a simple HTTP GET to
2312 retrieve data from a service (pullFromVoSpace) and a more general mechanism which
2313 employs a UWS-based approach [UWS] for submitting general data
2314 transfer requests (see section 3.6). In the latter, four directions
2315 are specified in which external data transfers can happen:
2316 <ul>
2317 <li> sending data to a service (pushToVoSpace)
2318 <li> importing data into a service (pullToVoSpace)
2319 <li> reading data from a service (pullFromVoSpace)
2320 <li> sending data from a service (pushFromVoSpace)
2321 </ul>
2322
2323 <p>A transfer job is created by a HTTP POST of an appropriate Job
2324 representation to the transfers endpoint of the service: http://rest-endpoint/transfers</p>
2325 <p>The service returns the jobid of the transfer and it can then
2326 be initiated with a HTTP POST of the single parameter "PHASE=RUN" to
2327 the appropriate job endpoint:
2328 http://rest-endpoint/transfers/(jobid)/phase. Alternatively the
2329 transfer can also be run immediately on creation by adding a
2330 "PHASE=RUN" to the initial Job representation.</p>
2331 <p>The status of any transfer can be obtained by polling the phase
2332 endpoint for a particular transfer, i.e. a HTTP GET to
2333 http://rest-endpoint/transfers/(jobid)/phase.</p>
2334 <p>Once a transfer has completed, any results can be obtained by
2335 following the link in the Results List available from
2336 the results endpoint for that transfer, i.e. with a HTTP GET to
2337 http://rest-endpoint/transfers/(jobid)/results. This pertains
2338 particularly to the transfer methods in which data is sent to or
2339 read from a service-negotiated URL (pushToVoSpace and pullFromVoSpace).</p>
2340 <p>A transfer can also be aborted at any stage with a HTTP POST of
2341 the parameter "PHASE=ABORT" to the endpoint:
2342 http://rest-endpoint/transfers/(jobid)/phase</p>
2343 <p>More specific details for each of the four directions are given below.</p>
2344
2345
2346 <h4><a name="sec5_4_1">5.4.1 pushToVoSpace</h4>
2347 <p>Request a list of URLs to send data to a VOSpace node.
2348 </p><p>
2349 This method asks the server for a list of one or more URLs that the client can use to send data to.
2350 </p><p>
2351 The data transfer is initiated by the client, after it has received the response from the VOSpace service.
2352 </p><p>
2353 The primary use case for this method is client that wants to send some data directly to a VOSpace service.
2354 </p>
2355 <p>
2356 This operation is OPTIONAL.
2357 </p>
2358 <h5><a name="sec5_4_1_1">5.4.1.1 Request</a></h5>
2359 <ul<li> A HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers
2360 </ul><p>
2361 If a Node already exists at the target URI, then the data SHALL be imported into the existing Node and the Node properties SHALL be cleared unless the node is a ContainerNode.
2362 </p><p>
2363 If there is no Node at the target URI, then the service SHALL create a new Node using the uri and the default xsi:type for the space.
2364 </p><p>
2365 The transfer representation contains details of the View and a list of the Protocols that the client wants to use.
2366 </p><p>
2367 The list of Protocols SHOULD not contain endpoint addresses, the service will supply the endpoint addresses in the response.
2368 </p><p>
2369 The service SHALL ignore any of the requested protocols that it does not understand or is unable to support.
2370 </p><p>
2371 .auto is the reserved URI to indicate an auto-generated URI for the destination, i.e. vos://service/path/.auto SHALL cause a new unique URI for the node within vos://service/path to be generated.
2372 </p>
2373 <p>There is also an alternate convenience mode:</p>
2374 <ul><li>A HTTP POST of a Job representation for the transfer to
2375 http://rest-endpoint/sync
2376 </ul>
2377 <p>The assumed transfer protocol is HTTP PUT; however, transfer
2378 negotiation in the usual manner is possible with this convenience mode.</p>
2379
2380
2381 <h5><a name="sec5_4_1_2">5.4.1.2 Response</a></h5>
2382 <ul><li>The initial response is a HTTP 303 status code with the
2383 Location header keyword assigned to the created job.
2384 </ul><p>
2385 The service SHALL select which of the requested Protocols it is
2386 willing to provide and fill in the operational details for each one in
2387 the transfer result representation - this SHOULD normally include specifying the destination URL of the transfer protocol endpoint.
2388 </p><p>
2389 The transfer result SHOULD not include any Protocols that it is unable to support.
2390 </p>
2391 <p>
2392 The transfer results representation can be retrieved directly from the
2393 link reported in the Results List, available either from the results endpoint
2394 - http://rest-endpoint/transfers/(jobid)/results - or as part of the
2395 full Job representation for the completed transfer available from
2396 http://rest-endpoint/transfers/(jobid). The result
2397 element in the Results List SHALL have an id of
2398 "transferDetails":</p>
2399 <pre>
2400 &lt;uws:job>
2401 ...
2402 &lt;uws:results>
2403 &lt;uws:result id="transferDetails" xlink:href="http://rest-endpoint/transfers/(jobid)/results/details1"/>
2404 &lt;/uws:results>
2405 ...
2406 &lt;/uws:job>
2407 </pre>
2408 <p>For the alternate convenience mode:</p>
2409 <ul><li>A HTTP 303 status code with the Location
2410 header keyword assigned to the endpoint: http://rest-endpoint/transfers/(jobid)/results/transferDetails.
2411 </ul>
2412 The HTTP 303 redirect points to a transfer representation with the
2413 required transfer details and endpoints.
2414
2415 </p>
2416 <h5><a name="sec5_4_1_3">5.4.1.3 Faults</a></h5>
2417 <p>For all faults using the UWS mode, the service shall set the PHASE to "ERROR" in the Job
2418 representation. The &lt;errorSummary&gt; element in the Job representation
2419 shall be set to the appropriate value for the fault type and the
2420 appropriate fault representation (see section 5.5) provided at the error URI:
2421 http://rest-endpoint/transfers/(jobid)/error.</p>
2422 <table>
2423 <tr><th align="left">Fault description</th><th
2424 align="left">errorSummary</th><th align="left">Fault representation</th></tr>
2425 <tr><td>Operation not supported</td><td>Operation Not Supported</td><td>OperationNotSupported</td></tr>
2426 <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
2427 <tr><td>User does not have permissions to perform the
2428 operation</td><td>Permission
2429 Denied</td><td>PermissionDenied</td></tr>
2430 <tr><td>Service does not support the requested View</td><td>View Not
2431 Supported</td><td>ViewNotSupported</td></tr>
2432 <tr><td>Service supports none of the requested
2433 Protocols</td><td>Protocol Not
2434 Supported</td><td>ProtocolNotSupported</td></tr>
2435 <tr><td>A View parameter is invalid</td><td>Invalid Argument</td><td>InvalidArgument</td></tr>
2436 <tr><td>A Protocol parameter is invalid</td><td>Invalid
2437 Argument</td><td>InvalidArgument</td></tr>
2438 </table>
2439
2440 <p>If an error occurs with the alternate convenience mode, the
2441 resultingtransfers document SHOULD have no protocols. The
2442 client can then retrieve the Job representation for error
2443 information as with asynchronous transfers.</p>
2444
2445
2446
2447 <!-- 5.4.1.4 Example -->
2448 <div class="exampleOuter">
2449 <div class="exampleHeader">Example: pushToVoSpace</div>
2450 <div class="exampleWrapper">
2451 <p>The Job to be submitted (newJob.xml) is:</p>
2452 <pre>
2453 &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0">
2454 &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
2455 &lt;vos:direction>pushToVoSpace&lt;/vos:direction>
2456 &lt;vos:view uri="ivo://net.ivoa/vospace/core#fits"/>
2457 &lt;vos:protocol uri="ivo://net.ivoa/vospace/core#httpput" authType="ivo://net.ivoa/vospace/core#anon"/>
2458 &lt;/vos:transfer>
2459 </pre>
2460 <pre>
2461 > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"</b></pre>
2462 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2463 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
2464 > POST /transfers HTTP/1.1
2465 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2466 > Host: localhost:8000
2467 > Accept: */*
2468 > Content-Length: 836
2469 > Content-Type: application/x-www-form-urlencoded
2470 >
2471 < HTTP/1.1 303 See Other
2472 < Content-Length: 174
2473 < Server: CherryPy/3.1.2
2474 < Location: http://localhost:8000/transfers/fd5cf0cb1b6d4fbd84602982abf19ef1
2475 < Allow: DELETE, GET, HEAD, POST, PUT
2476 < Date: Fri, 12 Mar 2010 22:12:21 GMT
2477 < Content-Type: text/html
2478 <
2479 * Connection #0 to host localhost left intact
2480 * Closing connection #0
2481 This resource can be found at <a href='http://localhost:8000/transfers/fd5cf0cb1b6d4fbd84602982abf19ef1'>http://localhost:8000/transfers/fd5cf0cb1b6d4fbd84602982abf19ef1</a>.
2482 </pre></div>
2483 <div class="exampleWrapper">
2484 <p>The status of the job can now be polled at the job location:</p>
2485 <pre>
2486 > <b>curl -v 'http://localhost:8000/transfers/fd5cf0cb1b6d4fbd84602982abf19ef1'</b></pre></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2487 <pre>
2488 * Connected to localhost (127.0.0.1) port 8000 (#0)
2489 > GET /transfers/fd5cf0cb1b6d4fbd84602982abf19ef1 HTTP/1.1
2490 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2491 > Host: localhost:8000
2492 > Accept: */*
2493 >
2494 < HTTP/1.1 200 OK
2495 < Date: Fri, 12 Mar 2010 22:45:46 GMT
2496 < Content-Length: 1037
2497 < Content-Type: text/html
2498 < Allow: DELETE, GET, HEAD, POST, PUT
2499 < Server: CherryPy/3.1.2
2500 <
2501 &lt;uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink"
2502 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ivoa.net/xml/UWS/v1.0 UWS.xsd">
2503 &lt;uws:jobId>fd5cf0cb1b6d4fbd84602982abf19ef1&lt;/uws:jobId>
2504 &lt;uws:ownerId xsi:nil="true"/>
2505 &lt;uws:phase>COMPLETED&lt;/uws:phase>
2506 &lt;uws:startTime>2010-03-12T22:45:25.568694&lt;/uws:startTime>
2507 &lt;uws:endTime>2010-03-12T22:45:25.568840&lt;/uws:endTime>
2508 &lt;uws:executionDuration>0&lt;/uws:executionDuration>
2509 &lt;uws:destruction xsi:nil="true"/>
2510 &lt;uws:jobInfo>
2511 &lt;vos:transfer>
2512 &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
2513 &lt;vos:direction>pushToVoSpace&lt;/vos:direction>
2514 &lt;vos:view uri="ivo://net.ivoa/vospace/core#fits"/>
2515 &lt;vos:protocol uri="ivo://net.ivoa/vospace/core#httpput" authType="ivo://net.ivoa/vospace/core#anon"/>
2516 &lt;/vos:transfer>
2517 &lt;uws:jobInfo>
2518 &lt;uws:results>
2519 &lt;uws:result id="transferDetails"
2520 xlink:href="http://localhost:8000/transfers/fd5cf0cb1b6d4fbd84602982abf19ef1/results/details"/>
2521 &lt;/uws:results>
2522 &lt;/uws:job>
2523 * Connection #0 to host localhost left intact
2524 * Closing connection #0
2525 </pre></div>
2526 <div class="exampleWrapper">
2527 <p>The final negotiated details of the transfer can be retrieved from
2528 the URL reported in the result element:</p>
2529 <pre>
2530 > <b>curl -v "http://localhost:8000/transfers/fd5cf0cb1b6d4fbd84602982abf19ef1/results/details"</b></pre></div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2531 <pre>
2532 * Connected to localhost (127.0.0.1) port 8000 (#0)
2533 > GET /transfers/fd5cf0cb1b6d4fbd84602982abf19ef1/results/details HTTP/1.1
2534 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2535 > Host: localhost:8000
2536 > Accept: */*
2537 >
2538 < HTTP/1.1 200 OK
2539 < Date: Fri, 12 Mar 2010 22:46:17 GMT
2540 < Content-Length: 316
2541 < Content-Type: text/html
2542 < Allow: DELETE, GET, HEAD, POST, PUT
2543 < Server: CherryPy/3.1.2
2544 <
2545 &lt;transfer>
2546 &lt;target>vos://nvo.caltech!vospace/mydata1&lt;/target>
2547 &lt;direction>pushToVoSpace&lt;/direction>
2548 &lt;view>ivo://ivoa.net/vospace/core#fits&lt;/view>
2549 &lt;protocol uri="ivo://ivoa.net/vospace/core#httpput" authType="ivo://net.ivoa/vospace/core#anon">
2550 &lt;endpoint>http://localhost:8000/data/d55814f88d974c21afe5ad50e4e875c8&lt;/endpoint>
2551 &lt;/protocol>
2552 &lt;/transfer>
2553 * Connection #0 to host localhost left intact
2554 * Closing connection #0
2555 </pre></div>
2556 <div class="exampleWrapper">
2557 <p>The FITS image can then be uploaded to the specified HTTP endpoint.</p>
2558 </div></div>
2559
2560 <h4><a name="sec5_4_2">5.4.2 pullToVoSpace</h4>
2561 <p>Import data into a VOSpace node.
2562 </p><p>
2563 This method asks the server to fetch data from a remote location.
2564 </p><p>
2565 The data transfer is initiated by the VOSpace service and transferred direct into the target Node.
2566 </p><p>
2567 The data source can be another VOSpace service, or a standard HTTP or FTP server.
2568 </p><p>
2569 The primary use case for this method is transferring data from one server or service to another.
2570 </p>
2571 <p>
2572 This operation is OPTIONAL.
2573 </p>
2574 <h5><a name="sec5_4_2_1">5.4.2.1 Request</a></h5>
2575 <ul><li> A HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers
2576 </ul>
2577 <p>If a Node already exists at the target URI, then the data SHALL be imported into the existing Node and the Node properties SHALL be cleared unless the node is a ContainerNode.
2578 </p><p>
2579 If there is no Node at the target URI, then the service SHALL create a new Node using the uri, and the default xsi:type for the space.
2580 </p><p>
2581 <!--<font color="red">The Transfer details SHOULD include the View and -->
2582 <!--a list of one or more Protocols with valid endpoints and -->
2583 <!--parameters. The endpoint SHOULD normally refer to the source URL -->
2584 <!--for the transfer protocol. </font> -->
2585 </p>
2586 <h5><a name="sec5_4_2_2">5.4.2.2 Response</a></h5>
2587 <ul><li>The initial response is a HTTP 303 status code with the
2588 Location header keyword assigned to the created job.
2589 </ul>
2590 <h5><a name="sec5_4_2_3">5.4.2.3 Faults</a></h5>
2591 <p>For all faults, the service shall set the PHASE to "ERROR" in the Job
2592 representation. The &lt;errorSummary&gt; element in the Job representation
2593 shall be set to the appropriate value for the fault type and the
2594 appropriate fault representation (see section 5.5) provided at the error URI:
2595 http://rest-endpoint/transfers/(jobid)/error.</p>
2596 <table>
2597 <tr><th align="left">Fault description</th><th
2598 align="left">errorSummary</th><th align="left">Fault representation</th></tr>
2599 <tr><td>Operation not supported</td><td>Operation Not Supported</td><td>OperationNotSupported</td></tr>
2600 <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
2601 <tr><td>User does not have permissions to perform the
2602 operation</td><td>Permission
2603 Denied</td><td>PermissionDenied</td></tr>
2604 <tr><td>Service does not support the requested View</td><td>View Not
2605 Supported</td><td>ViewNotSupported</td></tr>
2606 <tr><td>Service supports none of the requested
2607 Protocols</td><td>Protocol Not
2608 Supported</td><td>ProtocolNotSupported</td></tr>
2609 <tr><td>Destination URI is invalid</td><td>Invalid URI</td><td>InvalidURI</td></tr>
2610 <tr><td>A View parameter is invalid</td><td>Invalid Argument</td><td>InvalidArgument</td></tr>
2611 <tr><td>A Protocol parameter is invalid</td><td>Invalid
2612 Argument</td><td>InvalidArgument</td></tr>
2613 <tr><td>Data format does not match the requested
2614 View</td><td>Invalid Data</td><td>InvalidData</td></tr>
2615 </table>
2616 <h5><a name="sec5_4_2_4">5.4.2.4 Notes</a></h5>
2617 <p>If the Job request contains more than one protocol parameter, then
2618 the service MAY fail over to use one or more of the options if
2619 the first one fails. The service SHOULD try each protocol
2620 option in turn until one succeeds or all have been tried.</p>
2621
2622 <!-- 5.4.2.5 Example -->
2623 <div class="exampleOuter">
2624 <div class="exampleHeader">Example: pullToVoSpace</div>
2625 <div class="exampleWrapper">
2626 <p>The Job to be submitted (newJob.xml) is:</p>
2627 <pre>
2628 &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0">
2629 &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
2630 &lt;vos:direction>pullToVoSpace&lt;/vos:direction>
2631 &lt;vos:view uri="ivo://ivoa.net/vospace/core#fits"/>
2632 &lt;vos:protocol uri="ivo://ivoa.net/vospace/core#httpget">
2633 &lt;vos:protocolEndpoint>http://some.server.com/here/is/the/data&lt;/vos:protocolEndpoint>
2634 &lt;/vos:protocol>
2635 &lt;/vos:transfer>
2636 </pre>
2637 <pre>
2638 > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"</b></pre>
2639 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2640 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
2641 > POST /transfers HTTP/1.1
2642 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2643 > Host: localhost:8000
2644 > Accept: */*
2645 > Content-Length: 932
2646 > Content-Type: application/x-www-form-urlencoded
2647 >
2648 < HTTP/1.1 303 See Other
2649 < Content-Length: 174
2650 < Server: CherryPy/3.1.2
2651 < Location: http://localhost:8000/transfers/ea901be0f7ef41668df9916ca25820f8
2652 < Allow: DELETE, GET, HEAD, POST, PUT
2653 < Date: Fri, 12 Mar 2010 23:36:58 GMT
2654 < Content-Type: text/html
2655 <
2656 * Connection #0 to host localhost left intact
2657 * Closing connection #0
2658 This resource can be found at <a href='http://localhost:8000/transfers/ea901be0f7ef41668df9916ca25820f8'>http://localhost:8000/transfers/ea901be0f7ef41668df9916ca25820f8</a>.
2659 </pre>
2660 </div>
2661 <div class="exampleWrapper">
2662 <p>The status of the job can now be polled at the phase endpoint:</p>
2663 <pre>
2664 > <b>curl -v "http://localhost:8000/transfers/ea901be0f7ef41668df9916ca25820f8/phase"</b></pre>
2665 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2666 <pre>
2667 * Connected to localhost (127.0.0.1) port 8000 (#0)
2668 > GET /transfers/ea901be0f7ef41668df9916ca25820f8/phase HTTP/1.1
2669 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2670 > Host: localhost:8000
2671 > Accept: */*
2672 >
2673 < HTTP/1.1 200 OK
2674 < Date: Fri, 12 Mar 2010 23:37:02 GMT
2675 < Content-Length: 9
2676 < Content-Type: text/html
2677 < Allow: DELETE, GET, HEAD, POST, PUT
2678 < Server: CherryPy/3.1.2
2679 <
2680 EXECUTING
2681 * Connection #0 to host localhost left intact
2682 * Closing connection #0
2683 </pre></div></div>
2684
2685 <h3><a name="sec5_4_3">5.4.3 pullFromVoSpace</h3>
2686 <p>Request a set of URLs that the client can read data from.</p>
2687
2688 <p>The client requests access to the data in a Node, and the server SHALL respond with a set of
2689 URLs that the client can read the data from. </p>
2690
2691 <h5><a name="sec5_4_3_1">5.4.3.1 Request</a></h5>
2692 <ul><li> A HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers
2693 </ul><p>
2694 The transfer representation SHOULD contain details of the View and a list of the Protocols that the client would like to use.
2695 </p><p>
2696 The list of Protocols SHOULD not contain endpoint addresses; the service SHALL supply the endpoint addresses in the response.
2697 </p><p>
2698 The service SHALL ignore any of the requested protocols that it does not understand or is unable to support.
2699 </p>
2700 <p>
2701 A transfer may also be initiated by a HTTP POST of a Job
2702 representation for the transfer to http://rest-endpoint/sync. The
2703 assumed transport protocol is HTTP GET but transfer negotiation is possible.
2704 </p>
2705 <p>There is also an alternate, optimized convenience mode (for example, for web
2706 browser access):</p>
2707 <ul><li>A HTTP GET to the /sync endpoint with transfer parameters in the query string will return the data transfer endpoint directly:
2708 <ul><li>curl -d "TARGET=vos://nvo.caltech!vospace/mydata1&DIRECTION=pullFromVoSpace&PROTOCOL=ivo://ivoa.net/vospace/core#httpget" "http://localhost:8000/sync"
2709 </ul></ul>
2710 <p>The assumed transfer protocol is HTTP GET and the View of the
2711 node is its default value, i.e. no alternate Views are possible with
2712 this mode. Note that no transfer
2713 negotiation is possible with this convenience mode.</p>
2714 <p>Other values of the URL parameter "view" may be used by individual
2715 services for particular purposes, e.g., "view=rss" to identify a RSS
2716 feed on the resource.</p>
2717
2718 <h5><a name="sec5_4_3_2">5.4.3.2 Response</a></h5>
2719 <ul><li>The initial response for the UWS mode is a HTTP 303 status code
2720 with the Location header keyword assigned to the created job
2721 </ul><p>
2722 The service SHALL select which of the requested Protocols it is
2723 willing to provide and fill in the operational details for each one in
2724 the transfer result representation - this SHOULD normally include specifying the source URL of the transfer protocol endpoint.
2725 </p><p>
2726 The service response SHOULD not include any Protocols that it is unable to support.
2727 </p>
2728 <p>
2729 The transfer results representation can be retrieved directly from the
2730 link reported in the Results List, available either from the results
2731 endpoint - http://rest-endpoint/transfers/(jobid)/results - or as part
2732 of the full Job representation for the completed transfer available from
2733 http://rest-endpoint/transfers/(jobid). In the latter case, the result
2734 element in the Results List SHALL have an id of "transferDetails":</p>
2735 <pre>
2736 &lt;uws:job>
2737 ...
2738 &lt;uws:results>
2739 &lt;uws:result id="transferDetails" xlink:href="http://rest-endpoint/transfers/(jobid)/results/details1"/>
2740 &lt;/uws:results>
2741 ...
2742 &lt; /uws:job>
2743 </pre>
2744 <p>
2745 If the transfer was initiated with a HTTP POST to
2746 http://rest-endpoint/sync then the response is:
2747 <ul><li>A HTTP 303 status code with the Location
2748 header keyword assigned to the endpoint: http://rest-endpoint/transfers/(jobid)/results/transferDetails.
2749 </ul>
2750 The HTTP 303 redirect points to a transfer representation with the
2751 required transfer details and endpoints.
2752 </p>
2753 <p>For the alternate convenience mode (HTTP GET to the node):</p>
2754 <ul><li>A direct byte stream for the node</ul>
2755 <p>or</p>
2756 <ul>
2757 <li>A HTTP 303 status code with the Location header keyword assigned
2758 to an endpoint where a direct byte stream can be obtained
2759 </ul>
2760 <p>Although HTTP GET is the assumed transfer protocol in this mode,
2761 the HTTP 303 redirect could point to a endpoint supported by an
2762 alternate transfer protocol, i.e. a FTP endpoint. The client can
2763 check for this on the scheme returned URI.</p>
2764 <h5><a name="sec5_4_3_3">5.4.3.3 Faults</a></h5>
2765 <p>For all faults using the UWS mode, the service shall set the PHASE to "ERROR" in the Job
2766 representation. The &lt;errorSummary&gt; element in the Job representation
2767 shall be set to the appropriate value for the fault type and the
2768 appropriate fault representation (see section 5.5) provided at the error URI:
2769 http://rest-endpoint/transfers/(jobid)/error.</p>
2770 <table>
2771 <tr><th align="left">Fault description</th><th
2772 align="left">errorSummary</th><th align="left">Fault representation</th></tr>
2773 <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
2774 <tr><td>User does not have permissions to perform the
2775 operation</td><td>Permission
2776 Denied</td><td>PermissionDenied</td></tr>
2777 <tr><td>Source Node does not exist</td><td>Node Not Found</td><td>NodeNotFound</td></tr>
2778 <tr><td>Service does not support the requested View</td><td>View Not
2779 Supported</td><td>ViewNotSupported</td></tr>
2780 <tr><td>Service supports none of the requested
2781 Protocols</td><td>Protocol Not
2782 Supported</td><td>ProtocolNotSupported</td></tr>
2783 <tr><td>A View parameter is invalid</td><td>Invalid Argument</td><td>InvalidArgument</td></tr>
2784 <tr><td>A Protocol parameter is invalid</td><td>Invalid
2785 Argument</td><td>InvalidArgument</td></tr>
2786 </table>
2787
2788 <p>If an error occurs with the alternate convenience mode, the
2789 resulting transfers document SHOULD have no protocols. The
2790 client can then retrieve the Job representation for error
2791 information as with asynchronous transfers.</p>
2792
2793
2794 <h5><a name="sec5_4_3_4">5.4.3.4 Notes</a></h5>
2795 <p>The endpoint URLs supplied in the UWS response SHOULD be considered as 'one shot' URLs. A VOSpace service connected to a standard web server MAY return the public URL for the data. However, a different implementation MAY create a unique single use URL specifically for this transfer. </p>
2796
2797 <!-- 5.4.3.5 Example -->
2798 <div class="exampleOuter">
2799 <div class="exampleHeader">Example: pullFromVoSpace</div>
2800 <div class="exampleWrapper">
2801 <p>The Job to be submitted (newJob.xml) is:</p>
2802 <pre>
2803 &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0">
2804 &lt;vos:target>vos://nvo.caltech!vospace/mydata1&lt;/vos:target>
2805 &lt;vos:direction>pullFromVoSpace&lt;/vos:direction>
2806 &lt;vos:view uri="ivo://ivoa.net/vospace/core#defaultview"/>
2807 &lt;vos:protocol uri="ivo://ivoa.net/vospace/core#httpget" authType="ivo://net.ivoa/vospace/core#anon"/>
2808 &lt;vos:protocol uri="ivo://ivoa.net/vospace/core#ftpget"/>
2809 &lt;/vos:transfer>
2810 </pre>
2811 <pre>
2812 > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"</b></pre>
2813 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2814 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
2815 > POST /transfers HTTP/1.1
2816 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2817 > Host: localhost:8000
2818 > Accept: */*
2819 > Content-Length: 928
2820 > Content-Type: application/x-www-form-urlencoded
2821 >
2822 < HTTP/1.1 303 See Other
2823 < Content-Length: 174
2824 < Server: CherryPy/3.1.2
2825 < Location: http://localhost:8000/transfers/1ce91a4346b54432a4fd4a756fc75397
2826 < Allow: DELETE, GET, HEAD, POST, PUT
2827 < Date: Fri, 12 Mar 2010 23:46:46 GMT
2828 < Content-Type: text/html
2829 <
2830 * Connection #0 to host localhost left intact
2831 * Closing connection #0
2832 This resource can be found at <a
2833 href='http://localhost:8000/transfers/1ce91a4346b54432a4fd4a756fc75397'>http://localhost:8000/transfers/1ce91a4346b54432a4fd4a756fc75397</a>.
2834 </pre></div>
2835 <div class="exampleWrapper">
2836 <p>Once the job has completed (by polling the phase endpoint of the
2837 service), the results can be obtained from the result endpoint:</p>
2838 <pre>
2839 > <b>curl -v "http://localhost:8000/transfers/1ce91a4346b54432a4fd4a756fc75397/results"</b></pre>
2840 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2841 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
2842 > GET /transfers/1ce91a4346b54432a4fd4a756fc75397/results HTTP/1.1
2843 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2844 > Host: localhost:8000
2845 > Accept: */*
2846 >
2847 < HTTP/1.1 200 OK
2848 < Date: Sat, 13 Mar 2010 00:00:20 GMT
2849 < Content-Length: 239
2850 < Content-Type: text/html
2851 < Allow: DELETE, GET, HEAD, POST, PUT
2852 < Server: CherryPy/3.1.2
2853 <
2854 &lt;ns0:results xmlns:ns0="http://www.ivoa.net/xml/UWS/v1.0">
2855 &lt;ns0:result xmlns:ns1="http://www.w3.org/1999/xlink" id="transferDetails"
2856 ns1:href="http://localhost:8000/transfers/83c19a500b1c48108d631f1aa020e8bb/results/details"/>
2857 &lt;/ns0:results>
2858 * Connection #0 to host localhost left intact
2859 * Closing connection #0
2860 </pre></div>
2861 <div class="exampleWrapper">
2862 <p>The final negotiated details of the transfer can then be retrieved
2863 from the URL reported in the result element:</p>
2864 <pre>
2865 > <b>curl -v "http://localhost:8000/transfers/83c19a500b1c48108d631f1aa020e8bb/results/details"</b></pre>
2866 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2867 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
2868 > GET /transfers/1ce91a4346b54432a4fd4a756fc75397/results/details HTTP/1.1
2869 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2870 > Host: localhost:8000
2871 > Accept: */*
2872 >
2873 < HTTP/1.1 200 OK
2874 < Date: Sat, 13 Mar 2010 00:13:18 GMT
2875 < Content-Length: 477
2876 < Content-Type: text/html
2877 < Allow: DELETE, GET, HEAD, POST, PUT
2878 < Server: CherryPy/3.1.2
2879 <
2880 &lt;transfer>
2881 &lt;target>vos://nvo.caltech!vospace/mydata1&lt;/target>
2882 &lt;direction>pullFromVoSpace&lt;/direction>
2883 &lt;view uri="ivo://ivoa.net/vospace/core#defaultview"/>
2884 &lt;protocol uri="ivo://ivoa.net/vospace/core#httpget" authType="ivo://net.ivoa/vospace/core#anon">
2885 &lt;endpoint>http://localhost:8000/data/d27282305c6746889691e914abab9403&lt;/endpoint>
2886 &lt;/protocol>
2887 &lt;protocol uri="ivo://ivoa.net/vospace/core#ftpget">
2888 &lt;endpoint>ftp://localhost:8000/data/0d4824049dd444a290f6a524323dbcd0&lt;/endpoint>
2889 &lt;/protocol>
2890 &lt;/transfer>
2891 * Connection #0 to host localhost left intact
2892 * Closing connection #0
2893 </pre></div></div>
2894
2895 <h3><a name="sec5_4_4">5.4.4 pushFromVoSpace</h3>
2896 <p>Ask the server to send data to a remote location.
2897 </p><p>
2898 The client supplies a list of URLs and asks the server to send the data to the remote location.
2899 </p><p>
2900 The transfer is initiated by the server, and the data transferred direct from the server to the remote location.
2901 </p>
2902 <p>
2903 This operation is OPTIONAL.
2904 </p>
2905 <h5><a name="sec5_4_4_1">5.4.4.1 Request</a></h5>
2906 <ul><li> A HTTP POST of a Job representation for the transfer to http://rest-endpoint/transfers
2907 </ul>
2908 <!--<p><font color="red">The Transfer details SHOULD include the View and a list of one or more Protocols with valid endpoint and parameters. The endpoints will normally refer to the destination URLs for the transfer protocols.</font> -->
2909 </p>
2910 <h5><a name="sec5_4_4_2">5.4.4.2 Response</a></h5>
2911 <ul><li>The initial response is a HTTP 303 status code with the
2912 Location header keyword assigned to the created job.</ul>
2913 </ul>
2914 <h5><a name="sec5_4_4_3">5.4.4.3 Faults</a></h5>
2915 <table>
2916 <tr><th align="left">Fault description</th><th
2917 align="left">errorSummary</th><th align="left">Fault representation</th></tr>
2918 <tr><td>Operation not supported</td><td>Operation Not Supported</td><td>OperationNotSupported</td></tr>
2919 <tr><td>Operation fails</td><td>Internal Fault</td><td>InternalFault</td></tr>
2920 <tr><td>User does not have permissions to perform the
2921 operation</td><td>Permission
2922 Denied</td><td>PermissionDenied</td></tr>
2923 <tr><td>Source Node does not exist</td><td>Node Not Found</td><td>NodeNotFound</swtd></tr>
2924
2925 <tr><td>Service does not support the requested View</td><td>View Not
2926 Supported</td><td>ViewNotSupported</td></tr>
2927 <tr><td>Service supports none of the requested
2928 Protocols</td><td>Protocol Not
2929 Supported</td><td>ProtocolNotSupported</td></tr>
2930 <tr><td>Destination URI is invalid</td><td>Invalid URI</td><td>InvalidURI</td></tr>
2931 <tr><td>A Protocol parameter is invalid</td><td>Invalid
2932 Argument</td><td>InvalidArgument</td></tr>
2933 <tr><td>Data transfer does not complete</td><td>Transfer Failed</td><td>TransferFailed</td></tr>
2934 </table>
2935
2936 <h5><a name="sec5_4_4_4">5.4.4.4 Notes</a></h5>
2937 <p>
2938 If the Job request contains more than one protocol parameter then the service MAY fail over to use one or more of the options if the first one fails. The service SHOULD try each protocol option in turn until one succeeds or all have been tried.
2939 </p>
2940 <!-- 5.4.4.5 Example -->
2941 <div class="exampleOuter">
2942 <div class="exampleHeader">Example: pushFromVoSpace</div>
2943 <div class="exampleWrapper">
2944 <p>The Job to be submitted (newJob.xml) is:</p>
2945 <pre>
2946 &lt;vos:transfer xmlns:vos="http://www.ivoa.net/xml/VOSpace/v2.0">
2947 &lt;vos:target">vos://nvo.caltech!vospace/mydata1&lt;/uws:parameter>
2948 &lt;vos:direction">pushFromVoSpace&lt;/uws:parameter>
2949 &lt;vos:view">ivo://ivoa.net/vospace/core#defaultview&lt;/uws:parameter>
2950 &lt;vos:protocol uri="ivo://ivoa.net/vospace/core#httpput">
2951 &lt;vos:protocolEndpoint>http://some.server.com/put/the/data/here&lt;/vos:protocolEndpoint>
2952 &lt;/vos:protocol>
2953 &lt;vos:protocol uri="ivo://ivoa.net/vospace/core#ftpput">
2954 &lt;vos:protocolEndpoint>ftp://some.other.server.com/put/the/data/here&lt;/vos:protocolEndpoint>
2955 &lt;/vos:protocol>
2956 &lt;/vos:transfer>
2957 </pre>
2958 <pre>
2959 > <b>curl -v -X POST -d @newJob.xml "http://localhost:8000/transfers"</b></pre>
2960 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2961 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
2962 > POST /transfers HTTP/1.1
2963 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2964 > Host: localhost:8000
2965 > Accept: */*
2966 > Content-Length: 942
2967 > Content-Type: application/x-www-form-urlencoded
2968 >
2969 < HTTP/1.1 303 See Other
2970 < Content-Length: 174
2971 < Server: CherryPy/3.1.2
2972 < Location: http://localhost:8000/transfers/346d5cd27a0d405a8311819c90818cbc
2973 < Allow: DELETE, GET, HEAD, POST, PUT
2974 < Date: Sat, 13 Mar 2010 00:41:20 GMT
2975 < Content-Type: text/html
2976 <
2977 * Connection #0 to host localhost left intact
2978 * Closing connection #0
2979 This resource can be found at <a href='http://localhost:8000/transfers/346d5cd27a0d405a8311819c90818cbc'>http://localhost:8000/transfers/346d5cd27a0d405a8311819c90818cbc</a>.
2980 </pre>
2981 </div>
2982 <div class="exampleWrapper">
2983 <p>The Job can then be started with:</p>
2984 <pre>
2985 > <b>curl -v -d PHASE=RUN http://localhost:8000/transfers/346d5cd27a0d405a8311819c90818cbc</b></pre>
2986 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
2987 <pre>* Connected to localhost (127.0.0.1) port 8000 (#0)
2988 > POST /transfers HTTP/1.1
2989 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
2990 > Host: localhost:8000
2991 > Accept: */*
2992 > Content-Length: 9
2993 > Content-Type: application/x-www-form-urlencoded
2994 >
2995 </pre>
2996 </div>
2997 <div class="exampleWrapper">
2998 <p>The status of the job can now be polled at the phase endpoint:</p>
2999 <pre>
3000 > <b>curl -v "http://localhost:8000/transfers/346d5cd27a0d405a8311819c90818cbc/phase"</b></pre>
3001 </div><div class="exampleInner" style="background-color: rgb(213, 222, 227);">
3002 <pre>
3003 * Connected to localhost (127.0.0.1) port 8000 (#0)
3004 > GET /transfers/346d5cd27a0d405a8311819c90818cbc/phase HTTP/1.1
3005 > User-Agent: curl/7.19.4 (universal-apple-darwin10.0) libcurl/7.19.4 OpenSSL/0.9.8l zlib/1.2.3
3006 > Host: localhost:8000
3007 > Accept: */*
3008 >
3009 < HTTP/1.1 200 OK
3010 < Date: Fri, 12 Mar 2010 23:37:02 GMT
3011 < Content-Length: 9
3012 < Content-Type: text/html
3013 < Allow: DELETE, GET, HEAD, POST, PUT
3014 < Server: CherryPy/3.1.2
3015 <
3016 COMPLETED
3017 * Connection #0 to host localhost left intact
3018 * Closing connection #0
3019 </pre></div></div>
3020
3021 <h3><a name="sec5_5">5.5 Fault arguments</a></h3>
3022 <p>Faults reported by a VOSpace service SHALL contain the following information:</p>
3023 <h4><a name="sec5_5_1">5.5.1 InternalFault</a></h4>
3024 <p>This is thrown with a description of the cause of the fault. </p>
3025 <h4><a name="sec5_5_2">5.5.2 PermissionDenied </a></h4>
3026 <p>This is thrown with a description of why the credentials (if any were provided) were rejected. </p>
3027 <h4><a name="sec5_5_3">5.5.3 InvalidURI </a></h4>
3028 <p>This is thrown with details of the invalid URI. </p>
3029 <h4><a name="sec5_5_4">5.5.4 NodeNotFound </a></h4>
3030 <p>This is thrown with the URI of the missing Node. </p>
3031 <h4><a name="sec5_5_5">5.5.5 DuplicateNode </a></h4>
3032 <p>This is thrown with the URI of the duplicate Node.</p>
3033 <h4><a name="sec5_5_6">5.5.6 InvalidToken </a></h4>
3034 <p>This is thrown with the invalid token. </p>
3035 <h4><a name="sec5_5_7">5.5.7 InvalidArgument </a></h4>
3036 <p>This is thrown with a description of the invalid argument, including the View or Protocol URI and the name and value of the parameter that caused the fault. </p>
3037 <h4><a name="sec5_5_8">5.5.8 TypeNotSupported </a></h4>
3038 <p>This is thrown with the QName of the unsupported type.