/[volute]/trunk/projects/dal/SODA/SODA.tex
ViewVC logotype

Contents of /trunk/projects/dal/SODA/SODA.tex

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3200 - (show annotations)
Thu Dec 31 17:05:05 2015 UTC (5 years, 8 months ago) by francois
File MIME type: application/x-tex
File size: 26446 byte(s)


1 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
3
4 \usepackage{listings}
5 \lstloadlanguages{XML,sh}
6 \lstset{flexiblecolumns=true,tagstyle=\ttfamily,
7 showstringspaces=False}
8 \usepackage{todonotes}
9
10 \title{IVOA Server-side Operations for Data Access}
11
12 \ivoagroup{DAL}
13
14 \author{Fran\c cois Bonnarel, Markus Demleitner, Patrick Dowler, Douglas Tody }
15
16 \editor{Fran\c cois Bonnarel}
17
18 \previousversion{WD-AccessData-1.0-20151021}
19 \previousversion{WD-AccessData-1.0-20140730}
20 \previousversion{WD-AccessData-1.0-20140312}
21
22
23 \begin{document}
24
25 \begin{abstract}
26 This document describes the SODA web service capability. SODA is a low-level data access capability or server side data processing that can act upon the data files, performing various kinds of operations: filtering/subsection, transformations, pixel operations, and applying functions to the data.
27
28 \end{abstract}
29
30 \section*{Acknowledgments}
31 The authors would like to thank all the participants in DAL-
32 WG discussions for their ideas, critical reviews, and
33 contributions to this document.
34
35 \section{Introduction}
36 The SODA web service interface defines a RESTful web service for performing server-side operations and processing on data before transfer.
37
38
39 \subsection{The Role in the IVOA Architecture}
40
41
42
43
44 TODO: new diagram from TCG
45
46 SODA services conform to the Data Access
47 layer Interface \citep{std:DALI} specification, including the
48 Virtual Observatory Support Interfaces \citep{std:VOSI} resources.
49
50 \subsection{Motivating Use Cases}
51 Below are some of the more common use cases that have motivated the development of the SODA specification. While this is not complete, it helps to understand the problem area covered by this specification.
52
53 \subsubsection{Retrieve Subsection of a Datacube}
54 \label{sect:use-cube}
55
56 Cutout a subsection using coordinate axis values. The input to the cutout operation will include one or more of the following:
57
58
59 \begin{itemize}
60 \item a region on the sky
61 \item an energy value or range
62 \item a time value or range
63 \item one or more polarization states
64 \end{itemize}
65
66 The region on the sky should be something simple: a circle,
67 a range of coordinate values, or maybe a polygon.
68
69 \subsubsection{Retrieve subsection of a 2D Image}
70 This is a special case of \ref{sect:use-cube},
71 where the cutout is only in the spatial axes.
72
73 \subsubsection{Retrieve subsection of a Spectrum}
74
75 This is a special case of \ref{sect:use-cube},
76 where the cutout is only in the spectral axis.
77
78 \subsection{Provide the data in different formats}
79
80 Examples are images in PNG, or JPEG instead of FITS and spectra in csv, FITS or VOTable.
81
82 \subsubsection{Flatten a Datacube into a 2D Image}
83
84 This use case will be developed and supported in the
85 SODA-1.1 (or later) specification.
86
87 \subsubsection{Flatten a Datacube into a 1D Spectrum}
88
89 This use case will be developed and supported in the
90 SODA-1.1 (or later) specification.
91
92 \subsubsection{Rebin Data by a Fixed Factor}
93
94 This use case will be developed and supported in the
95 SODA-1.1 (or later) specification.
96
97 \subsubsection{Reproject Data onto a Specified Grid}
98
99 This use case will be developed and supported in the
100 SODA-1.1 (or later) specification.
101
102 \subsubsection{Compute Aggregate Functions over the Data}
103
104 This use case will be developed and supported in the
105 SODA-1.1 (or later) specification.
106
107
108 \subsubsection{Apply Standard Function to Data Values}
109
110 It could be
111 ``denoising'' with standard methods or ``on the fly'' recalibration. This use case will be developed and supported in the
112 SODA-1.1 (or later) specification.
113
114 \subsubsection{Apply Arbitrary User-Specified Function to Data Values}
115
116 This use case will be developed and supported in the
117 SODA-1.1 (or later) specification.
118
119 \subsubsection{Run Arbitrary User-Supplied Code on the Data}
120
121 This use case will be developed and supported in the
122 SODA-1.1 (or later) specification.
123
124 \section{Resources}
125
126 SODA services are implemented as HTTP REST \citep{richardson07} web
127 services with a \{sync\} resource that conforms to the DALI-
128 sync resource description.
129
130 \begin{table}[ht]
131 \begin{tabular}{rrr}
132 \sptablerule
133 \textbf{resource type}&\textbf{resource name}&\textbf{required}\cr
134 \sptablerule
135 \{sync\}&service specific&\cr
136 \{async\}&service specific&\cr
137 {DALI-examples}&/examples&no\cr
138 {VOSI-availability}&/availability&yes\cr
139 {VOSI-capabilities}&/capabilities&yes\cr
140 \sptablerule
141 \end{tabular}
142 \caption{Endpoints for AccessData services}
143 \end{table}
144
145 A stand-alone SODA service may have one or both of the \{sync\} and \{async\} resources. For either type, it could have multiple resources (e.g. to support alternate authentication schemes). The SODA service may also include other custom or supporting resources.
146
147 Either the \{sync\} or \{async\} SODA capability may be included as part of other web services. For example, a single web service could contain the SIA-2.0 \{query\} capability, the DataLink-1.0 \{links\} capability, and the SODA \{sync\} capability. Such a service must also have the VOSI-availability and VOSI-capabilities resources to report on and describe all the implemented capabilities.
148
149 \subsection{\{sync\} resource}
150 \label{sect:syncres}
151
152 The \{sync\} resource is a synchronous web service resource
153 that conforms to the DALI-sync description. Implementors
154 are free to name this resource however
155 they like, except that the name must consist of one URI segment only (i.e.,
156 contain no slash). This is to allow clients, given the access URL,
157 can reliably find out the URL of the capabilities endpoint.
158 Clients, in turn, can find the resource path using the
159 VOSI-capabilities resource, but will in general be provided the access
160 URLs through a previous data discovery query or through direct user
161 input.
162
163 The \{sync\} resource performs the data access as specified by
164 the input parameters and returns the data directly in the
165 output stream. Synchronous data access is suitable when the
166 operations can be quickly performed and the data stream can
167 be setup and written to (by the service) in a short period
168 of time (e.g. before any timeouts).
169
170 \subsection{\{async\} resource}
171
172 The \{async\} resource is an asynchronous web service resource
173 that conforms to the DALI-async description. The considerations on
174 naming the resource given in sect.~\ref{sect:syncres} apply for it.
175
176 The \{async\} resource performs the data access as specified
177 by the input parameters and either (i) stores the results
178 for later transfer or (ii) pushes the results to a specified
179 destination (e.g. to a VOSpace location). Asynchronous data
180 access usually introduces resource constraints on the
181 service (which may be limited) and usually imposes a higher
182 latency before any results can be seen because the location
183 of results does not have to be valid until the data access
184 job is complete. Asynchronous data access is intended for
185 (but not limited to) use when the operations take
186 considerable time and results must be staged (e.g. some
187 multi-pass algorithms or operations that result in multiple
188 outputs).
189
190 \subsection{Examples: DALI-examples}
191
192 SODA services should provide a DALI-examples resource
193 with one example invocation that shows the variety
194 operations the service can perform. Example operations using
195 the \{sync\} resource and that output a small data stream are
196 preferred, as the examples may be used by automatic validators doing
197 relatively frequent (of order daily) queries.
198
199 Parameters to be passed to the service must be given using the DALI
200 \texttt{generic-parameter} term.
201
202
203 \subsection{Availability: VOSI-availability}
204
205 A SODA web service must have a VOSI-availability
206 resource \citep{std:VOSI} as described in DALI \citep{std:DALI}.
207
208 \subsection{Capabilities: VOSI-capabilities}
209
210 A web service that includes SODA capabilities must
211 have a VOSI-capabilities resource \citep{std:VOSI} as described in DALI
212 \citep{std:DALI}. The standardID for the \{sync\} resource is
213 $$\hbox{\texttt{ivo://ivoa.net/std/SODA\#sync-1.0}.}$$
214
215 The standardID for the \{async\} resource is
216
217 $$\hbox{\texttt{ivo://ivoa.net/std/SODA\#async-1.0}.}$$
218
219 All DAL services must implement the \texttt{/capabilities} resource.
220 The following capabilities document shows the minimal
221 metadata for a stand-alone SODA service and does not
222 require a registry extension schema:
223
224 \begin{lstlisting}[language=XML]
225 <?xml version="1.0"?>
226 <capabilities
227 xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
228 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
229 xmlns:vod="http://www.ivoa.net/xml/VODataService/v1.1">
230 <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
231 <interface xsi:type="vod:ParamHTTP" version="1.0">
232 <accessURL use="full">http://example.com/data/capabilities</accessURL>
233 </interface>
234 </capability>
235 <capability standardID="ivo://ivoa.net/std/VOSI#availability">
236 <interface xsi:type="vod:ParamHTTP" version="1.0">
237 <accessURL use="full">
238 http://example.com/data/availability
239 </accessURL>
240 </interface>
241 </capability>
242 <capability standardid="ivo://ivoa.net/std/SODA#sync-1.0">
243 <interface xsi:type="vod:ParamHTTP" role="std" version="1.0">
244 <accessurl use="full">
245 http://example.com/data/sync
246 </accessurl>
247 </interface>
248 <!-- service details from extension schema could go here -->
249 </capability>
250 <capability standardid="ivo://ivoa.net/std/SODA#async-1.0">
251 <interface xsi:type="vod:ParamHTTP" role="std" version="1.0">
252 <accessurl use="full">
253 http://example.com/data/async
254 </accessurl>
255 </interface>
256 <!-- service details from extension schema could go here -->
257 </capability>
258 </capabilities>
259 \end{lstlisting}
260
261 Note that the \{sync\} and \{async\} resources do not have to be
262 named as shown in the accessURL(s) above. Multiple
263 capability elements for the \{sync\} and the \{async\} resources
264 may be included; this is typically used if the differ in
265 protocol (http vs. https) and/or authentication
266 requirements.
267
268 \begin{admonition}{Note}
269 As SODA builds upon several concepts of DataLink \citep{std:datalink},
270 that document should be read before trying to understand the following
271 material.
272 \end{admonition}
273 \subsection{Parameter Description and Three-Factor Semantics}
274
275 \subsubsection{Three-factor Semantics}
276
277 Parameters in SODA are defined by triples of name, UCD, and unit (the
278 ``SODA triple''). Data services are free to support as many such parameters
279 as is appropriate for their datasets, in addition to supporting
280 standard parameters. With the three factors, it is
281 unlikely that two operators will by accident use the same three factors
282 for parameters of differing semantics. In this way, when a new standard
283 parameter is adopted, no existing service should require changes to
284 remain compliant.
285
286 With standard parameters as defined in this document, clients can rely
287 on certain semantics and exploit that knowledge in the provision of
288 special UIs or APIs. Standard parameters defined so far are given
289 in table~\ref{table:standardpars}. Instructions for how to propose
290 additional standard parameters are given on the landing page of the IVOA
291 DAL working group\footnote{At the time of writing, this is
292 \href{http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaResReg}{http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaResReg}.}.
293
294 \begin{table}[mht]
295 \begin{tabular}{llll}
296 \sptablerule
297 \textbf{Name}&\textbf{UCD}&\textbf{Unit}&\textbf{Semantics}\cr
298 \sptablerule
299 ID&meta.ref.url;meta.curation&&cf.~sect.~\ref{sect:ID}\cr
300 POS&pos&&cf.~sect.~\ref{sect:POS}\cr
301 BAND&em&m&cf.~sect.~\ref{sect:BAND}\cr
302 TIME&time&d&cf.~sect.~\ref{sect:TIME}\cr
303 POL&pol&&cf.~sect.~\ref{sect:POL}\cr
304 \sptablerule
305 \end{tabular}
306 \caption{SODA triples for the standard parameters defined here.}
307 \label{table:standardpars}
308 \end{table}
309
310 Both standard and non-standard parameters should follow DALI conventions
311 if at all possible. Roughly, float-valued parameters should be mapped
312 to interval-valued parameters (i.e., do not split up minimum and maximum
313 into separate parameters). Depending on their semantics, integer
314 parameters should either be intervals or enumerated parameters (which
315 typically can be repeated). String-valued parameters should always
316 be enumerated.
317
318 \subsubsection{Discovery of Supported Parameter. Implementation strategies}
319 \label{sect:discovery-supported}
320
321 There are two principal ways a client will be led to a SODA service:
322 From a service descriptor that is part of a DAL discovery response,
323 or by direct access mediated or not via a DataLink service. In the latter case an empty query to the service iwill answer by giving the service descriptor. . In both cases,
324 clients must obtain the set of supported parameters
325 from the applicable service descriptor.
326
327 In contrast to previous IVOA DAL protocols, SODA is not a data discovery
328 protocol but instead operates on concrete datasets. In a typical case,
329 some combinations of parameters (e.g., a positional or spectral cutout)
330 may yield no output at all, as the coverage of an individual dataset is
331 very limited. To provide meaningful user interfaces, clients would therefore
332 need detailed information on the service parameters, in particular as
333 regards their domains (i.e., set of values that are likely to yield
334 non-empty results). This, in regard, requires efficient and rich service APIs, not unlikely involving service-specific parameters.
335
336 But the double ways towards SODA service execution makes the providing of this information difficult to describe and is not done in this version.
337
338 As a consequence of this, when the SODA service is driven from a data discovery phase, parameters domains can be inferred by the end-user from the discovery reponse. In the other case, it may happen that these parameters have to be furnished blindly by the end-user.
339
340 \subsubsection{SODA Service Descriptor}
341 \label{sect:serv-desc}
342
343 The DataLink \citep{std:datalink} specification describes a mechanism for
344 describing a service within a VOTable resource and
345 recommends that services can describe themselves with a
346 special resource with \texttt{name="this"}. SODA responses for
347 empty sync queries should include a descriptor describing
348 both standard and custom query parameters (if applicable).
349 The descriptor for a service with standard parameters (see
350 sect.~\ref{sect:stdpars}) would be:
351
352 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
353
354 <RESOURCE type="meta" utype="adhoc:service" name="this">
355
356 <PARAM name="standardID" datatype="char" arraysize="*"
357 value="ivo://ivoa.net/std/SODA#sync-1.0" />
358
359 <PARAM name="accessURL" datatype="char" arraysize="*"
360 value="http://example.com/SODA/sync" />
361
362 <GROUP name="inputParams">
363 <PARAM name="ID" ucd="meta.id" datatype="char"
364 arraysize="*" xtype="ivoident" />
365 <PARAM name="POS" ucd="pos" unit="deg" datatype="char"
366 arraysize="*" xtype="circle" />
367 <PARAM name="POS" ucd="pos" unit="deg" datatype="char"
368 arraysize="*" xtype="range" />
369 <PARAM name="POS" ucd="pos" unit="deg" datatype="char"
370 arraysize="*" xtype="polygon" />
371 <PARAM name="BAND" ucd="em" unit="m" datatype="double"
372 arraysize="*" xtype="interval" />
373 <PARAM name="TIME" ucd="time" unit="d" datatype="double"
374 arraysize="*" xtype="interval" />
375 <PARAM name="POL" ucd="pol" datatype="char" arraysize="*"
376 xtype="Stokes" />
377 </GROUP>
378 </RESOURCE>
379
380 \end{lstlisting}
381
382 This VOTable resource should be output for empty sync
383 queries; Thus all inputs and outputs would be fully
384 described.
385
386 \subsubsection{Client Handling of Discovered Parameters}
387
388 To keep SODA clients useful even when advanced data products are being
389 accessed, the following procedure should be followed by clients:
390
391 \begin{enumerate}
392 \item Obtain the parameter triples domains as
393 described in sect.~\ref{sect:discovery-supported}.
394 \item Identify standard parameters understood by the client and provide
395 suitable input widgets (e.g., a rubberband on top of a sky rendering,
396 or a \texttt{spatial\_cutout} method possibly allowing library-specific
397 coverage objects) for them.
398
399 \item For the remaining parameters, provide generic UI or API elements
400 (e.g., sliders or text boxes with domains annotated for intervals, pop-up
401 menus for enumerated values).
402 \end{enumerate}
403
404
405
406
407 \section{Parameters for \{sync\} and \{async\}}
408
409 \label{sect:stdpars}
410
411 The \{sync\} and \{async\} resources accept the same set of
412 parameters.
413
414
415 \subsection{Common Parameters}
416
417 \subsubsection{ID}
418 \label{sect:ID}
419
420 The ID parameter is used to specify the dataset or file to
421 be accessed. The values for the ID parameter are generally
422 discovered from data discovery or DataLink requests. The
423 values must be treated as opaque identifiers that are used
424 as-is. The DataLink specification \citep{std:datalink} describes mechanisms
425 for conveying opaque parameters and values in service
426 descriptor resources that can be used by clients to set the
427 ID parameter.
428
429 The ID parameter is single-valued in \{sync\} requests, so
430 \{sync\} soda requests access a single dataset or file.
431 Multiple ID parameters may be submitted in \{async\} requests
432 on order to bundle access to multiple datasets or files in a
433 single job.
434
435
436 The ID ucd is ``meta.id'', and its unit is blank.
437 In addition its xtype is ``ivoident'' and its datatype ``char'', with
438 arraysize ``*''.
439
440
441 \subsection{Filtering Parameters}
442
443 Filtering parameters are used to extract subsets of larger
444 datasets or data files. In general, filtering parameters are
445 single-valued in \{sync\} requests and multi-valued in \{async\}
446 requests (exceptions noted below). When multiple values of
447 filtering parameters are used in an \{async\} job, each
448 combination of values produces zero or one result. For
449 example, if an \{async\} job included two POS and two BAND
450 values, there could be as many as four results (or fewer if
451 some combinations do not produce a result because the filter
452 does not intersect the bounds of the data).
453
454 \subsubsection{POS}
455 \label{sect:POS}
456
457 The POS parameter defines the positional region(s) to be
458 extracted from the data. The value is made up of a shape
459 keyword followed by coordinate values. The
460 allowed shapes are:
461
462 \begin{table}[h]
463 \begin{tabular}{ll}
464 \sptablerule
465 \textbf{Shape}&\textbf{Coordinate values}\cr
466 \sptablerule
467 \texttt{CIRCLE}&\texttt{<longitude> <latitude> <radius>}\cr
468 \texttt{RANGE}&\texttt{<longitude1> <longitude2> <latitude1> <latitude2>}\cr
469 \texttt{POLYGON}&\texttt{<longitude1> <latitude1> ... (at least 3 pairs)}\cr
470 \sptablerule
471 \end{tabular}
472 \caption{POS Values in Spherical Coordinates}
473 \end{table}
474
475 As in DALI, open intervals use -Inf or +Inf as one limit.
476
477 Examples for POS values:
478
479 \begin{itemize}
480 \item A circle at (12,34) with radius 0.5:
481
482 \begin{lstlisting}
483 POS=CIRCLE 12 34 0.5
484 \end{lstlisting}
485
486 \item A range of [12,14] in longitude and [34,36] in latitude:
487
488 \begin{lstlisting}
489 POS=RANGE 12 14 34 36
490 \end{lstlisting}
491
492 \item A polygon from (12,34) to (14,34) to (14,36) to (12,36) and
493 (implicitly) back to (12,34):
494
495 \begin{lstlisting}
496 POS=POLYGON 12 34 14 34 14 36 12 36
497 \end{lstlisting}
498
499 The inside is always assumed to be the smaller of the region
500 to the left and the region to the right so only polygons
501 smaller than half the sphere can be specified.
502
503 \item A band around the equator:
504
505 \begin{lstlisting}
506 POS=RANGE 0 360 -2 2
507 \end{lstlisting}
508
509 \item The north pole:
510
511 \begin{lstlisting}
512 POS=RANGE 0 360 89 +Inf
513 \end{lstlisting}
514 \end{itemize}
515
516 This syntax is in the same style as STC-S, but with no
517 reference positions, coordinate systems, units, or geometric
518 operators like union, intersection, not, etc.
519
520 All longitude and latitude values (plus the radius of the
521 CIRCLE) are expressed in degrees in the ICRS. A future
522 version of this specification may allow the use of other
523 reference systems (specifically the native system of the
524 data).
525
526 The POS parameter is single-valued for \{sync\} requests and
527 multi-valued for \{async\} jobs.
528
529 The unit of POS is ``deg'' and the ucd is ``pos''. However the datatype
530 of the POS parameter is ``char'', and the xtype can take one of the three
531 values ``circle'', ``range'' and ``polygon'' as defined in DALI.
532
533 \subsubsection{BAND}
534 \label{sect:BAND}
535
536 The BAND parameter defines the energy interval(s) to be
537 extracted from the data. The value is an open or closed
538 numeric interval of values in the native spectral axis
539 coordinate system and units of the data. The intervals
540 always include the bounding values. As in DALI, open intervals use -Inf
541 or +Inf as one limit.
542
543 If there is one single value the interval is assumed to be
544 infinitely small (a scalar value).
545
546 \begin{itemize}
547 \item The closed interval [500,550]:
548
549 \begin{lstlisting}
550 BAND=500 550
551 \end{lstlisting}
552
553 \item The open interval (-inf,300]:
554
555 \begin{lstlisting}
556 BAND=-Inf 300
557 \end{lstlisting}
558
559 \item The open interval [750,inf):
560
561 \begin{lstlisting}
562 BAND=750 +Inf
563 \end{lstlisting}
564
565 \item The scalar value 550, equivalent to [550,550]:
566
567 \begin{lstlisting}
568 BAND=550
569 \end{lstlisting}
570
571 \end{itemize}
572
573 Extracting using a scalar value should normally extract a
574 single pixel along the energy axis of the data; extracting
575 using an interval should extract one or more pixels.
576
577 All energy values are expressed as barycentric wavelength in
578 meters. A future version of this specification may allow the
579 use of other reference systems (specifically the native
580 system of ther data).
581
582 The BAND parameter is single-valued for \{sync\} requests and
583 multi-valued for \{async\} jobs.
584
585 The ucd of the BAND parameter is ``em'', the unit is ``m''. Its datatype is
586 double with an arraysize of 2, and the xtype is ``interval'' as defined in DALI.
587
588
589 \subsubsection{TIME}
590 \label{sect:TIME}
591
592 The TIME parameter defines the time interval(s) to be
593 extracted from the data. The value is an open or closed
594 interval with either numeric values (interpreted as Modified
595 Julian Dates). As in DALI, open intervals use -Inf or +Inf as one limit.
596
597 If there is one single value the numeric interval is assumed
598 to be infinitely small (a scalar value).
599
600 \begin{itemize}
601 \item An open interval from the MJD 55100.0 and all later times:
602
603 \begin{lstlisting}
604 TIME= 55100.0 +Inf
605 \end{lstlisting}
606
607 \item A range of MJD values:
608
609 \begin{lstlisting}
610 TIME=55123.456 55123.466
611 \end{lstlisting}
612
613 \item An instant in time using Modified Julian Date:
614
615 \begin{lstlisting}
616 TIME=55678.123456
617 \end{lstlisting}
618 \end{itemize}
619
620 Time values are always UTC.
621 The TIME parameter is single-valued for \{sync\} requests and
622 multi-valued for \{async\} jobs.
623
624 The ucd of the TIME parameter is ``time'' and the unit is ``d''. The
625 datatype is ``double'' with an arraysize of 2,
626 and the xtype is, again, ``interval'' as defined in
627 DALI
628
629
630 \subsubsection{POL}
631 \label{sect:POL}
632
633 The POL parameter defines the polarization state(s) (Stokes)
634 to be extracted from the data.
635
636 \begin{itemize}
637 \item Extract the unpolarized intensity:
638 \begin{lstlisting}
639 POL=I
640 \end{lstlisting}
641 \item Extract the standard circular polarization:
642 \begin{lstlisting}
643 POL=V
644 \end{lstlisting}
645
646 \item The POL parameter is multi-valued; multiple values can be
647 included in a single request and all will be extracted.
648 Extract only the IQU components:
649 \begin{lstlisting}
650 POL=I
651 POL=Q
652 POL=U
653 \end{lstlisting}
654 \end{itemize}
655
656 The POL is multi-valued for both \{sync\} and \{async\} requests.
657 Unlike general filtering parameters, all values of POL are
658 combined into a single filter; for example, if the request
659 includes the three values above, the job would generate one
660 result with some or all of these polarization states (per
661 combination of ID and other filtering parameters).
662
663 The ucd of the POL PARAMETER is ``pol'' and the unit is blank. The
664 datatype is ``char'' with arraysize ``*'', and the xtype is ``stokes''.
665
666
667
668 \section{\{sync\} Responses}
669
670 All responses from the \{sync\} resource follow the rules for
671 DALI-sync resources, except that the \{sync\} response allows
672 for error messages for individual input identifier values.
673
674 \subsection{Successful Requests}
675
676 Successfully executed requests should result in a response
677 with HTTP status code 200 (OK) and a response in the format
678 requested by the client or in the default format for the
679 service.
680
681 If the values specified for cutout parameters do not include
682 any pixels from the target dataset/file, the service must
683 respond with HTTP status code 204 (No Content) and no
684 response body.
685
686 The service should set the following HTTP headers to the
687 correct values where possible.
688
689 \begin{tabular}{rr}
690 \sptablerule
691 Content-Type&mime-type of the response\cr
692 Content-Encoding&encoding/compression of the response (if applicable)\cr
693 \sptablerule
694 \end{tabular}
695
696 Since the response is usually dynamically generated, the
697 Content-Length and Last-Modified headers cannot usually be
698 set.
699
700
701 \subsection{Errors}
702
703 The error handling specified for DALI-sync resources applies
704 to service failure. Error documents should be text using the
705 text/plain content-type and the text must begin with one of
706 the following strings:
707
708 \begin{table}[h]
709 \begin{tabular}{rr}
710 Error&General error (not covered below)\cr
711 AuthenticationError&Not authenticated\cr
712 AuthorizationError&Not authorized to access the resource\cr
713 ServiceUnavailable&Transient error (could succeed with retry)\cr
714 UsageError&Permanent error (retry pointless)\cr
715 \end{tabular}
716 \caption{error messages with their meaning}
717 \end{table}
718
719 \section{\{async\} Responses}
720
721 The \{async\} resource conforms to the DALI-async resource
722 description, which means the job is a UWS job with all the
723 job control features available. All result files are to be
724 listed as children of the UWS results resource. The service
725 provider is free to name each result.
726
727 \appendix
728
729 \section{Changes from Previous Versions}
730
731 \subsection{WD-SODA-1.0-20151120}
732
733 Change the name of the protocol. Suppression of SELECT and COORD. xtype description are in DALI. Reference to this has been added.
734
735 \subsection{WD-AccessData-1.0-20151021}
736
737 Added general introduction on PARAMETER description to
738 section 3. Modified SELECT and COORD sections in order to
739 detach them from SimDal. Added Appendix on xtype description
740 with BNF syntax.
741
742 \subsection{WD-AccessData-1.0-20140730}
743
744 \begin{itemize}
745 \item Removed REQUEST parameter since the DAL-WG decision to not
746 include it when there is only one value.
747
748 \item Clarified that ID and filierting parameters are single
749 valued for \{sync\} and multi-valued for \{async\}, wth POL
750 being multi-valued but still being treated as a single
751 filter.
752 \end{itemize}
753
754 \subsection{WD-AccessData-1.0-20140312}
755
756 This is the initial document version.
757
758 \bibliography{ivoatex/ivoabib}
759
760 \end{document}

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