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

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

Parent Directory Parent Directory | Revision Log Revision Log


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


1 msdemlei 3130 \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 francois 3183 \title{IVOA Server-side Operations for Data Access}
11 msdemlei 3130
12     \ivoagroup{DAL}
13    
14 francois 3183 \author{Fran\c cois Bonnarel, Markus Demleitner, Patrick Dowler, Douglas Tody }
15 msdemlei 3130
16 francois 3183 \editor{Fran\c cois Bonnarel}
17 msdemlei 3130
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 francois 3183 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 francois 3182
28 msdemlei 3130 \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 francois 3183 The SODA web service interface defines a RESTful web service for performing server-side operations and processing on data before transfer.
37 msdemlei 3130
38 francois 3183
39 msdemlei 3130 \subsection{The Role in the IVOA Architecture}
40    
41 francois 3183
42    
43    
44 msdemlei 3130 TODO: new diagram from TCG
45    
46 francois 3183 SODA services conform to the Data Access
47 msdemlei 3130 layer Interface \citep{std:DALI} specification, including the
48     Virtual Observatory Support Interfaces \citep{std:VOSI} resources.
49    
50     \subsection{Motivating Use Cases}
51 francois 3183 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 msdemlei 3130
53     \subsubsection{Retrieve Subsection of a Datacube}
54     \label{sect:use-cube}
55    
56 francois 3183 Cutout a subsection using coordinate axis values. The input to the cutout operation will include one or more of the following:
57 msdemlei 3130
58 francois 3183
59 msdemlei 3130 \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 francois 3183 \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 msdemlei 3130 \subsubsection{Flatten a Datacube into a 2D Image}
83    
84     This use case will be developed and supported in the
85 francois 3183 SODA-1.1 (or later) specification.
86 msdemlei 3130
87     \subsubsection{Flatten a Datacube into a 1D Spectrum}
88    
89     This use case will be developed and supported in the
90 francois 3183 SODA-1.1 (or later) specification.
91 msdemlei 3130
92     \subsubsection{Rebin Data by a Fixed Factor}
93    
94     This use case will be developed and supported in the
95 francois 3183 SODA-1.1 (or later) specification.
96 msdemlei 3130
97     \subsubsection{Reproject Data onto a Specified Grid}
98    
99     This use case will be developed and supported in the
100 francois 3183 SODA-1.1 (or later) specification.
101 msdemlei 3130
102     \subsubsection{Compute Aggregate Functions over the Data}
103    
104     This use case will be developed and supported in the
105 francois 3183 SODA-1.1 (or later) specification.
106 msdemlei 3130
107    
108     \subsubsection{Apply Standard Function to Data Values}
109    
110 francois 3183 It could be
111 msdemlei 3189 ``denoising'' with standard methods or ``on the fly'' recalibration. This use case will be developed and supported in the
112 francois 3183 SODA-1.1 (or later) specification.
113    
114 msdemlei 3130 \subsubsection{Apply Arbitrary User-Specified Function to Data Values}
115    
116     This use case will be developed and supported in the
117 francois 3183 SODA-1.1 (or later) specification.
118 msdemlei 3130
119     \subsubsection{Run Arbitrary User-Supplied Code on the Data}
120    
121     This use case will be developed and supported in the
122 francois 3183 SODA-1.1 (or later) specification.
123 msdemlei 3130
124     \section{Resources}
125    
126 francois 3183 SODA services are implemented as HTTP REST \citep{richardson07} web
127 msdemlei 3130 services with a \{sync\} resource that conforms to the DALI-
128     sync resource description.
129    
130 msdemlei 3190 \begin{table}[ht]
131 msdemlei 3130 \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 francois 3183 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 msdemlei 3130
147 francois 3183 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 msdemlei 3130
149     \subsection{\{sync\} resource}
150 msdemlei 3186 \label{sect:syncres}
151 msdemlei 3130
152     The \{sync\} resource is a synchronous web service resource
153 msdemlei 3186 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 msdemlei 3130
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 msdemlei 3186 that conforms to the DALI-async description. The considerations on
174     naming the resource given in sect.~\ref{sect:syncres} apply for it.
175 msdemlei 3130
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 msdemlei 3187 SODA services should provide a DALI-examples resource
193 msdemlei 3130 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 msdemlei 3187 preferred, as the examples may be used by automatic validators doing
197     relatively frequent (of order daily) queries.
198 msdemlei 3130
199 msdemlei 3187 Parameters to be passed to the service must be given using the DALI
200     \texttt{generic-parameter} term.
201    
202    
203 msdemlei 3130 \subsection{Availability: VOSI-availability}
204    
205 francois 3183 A SODA web service must have a VOSI-availability
206 msdemlei 3130 resource \citep{std:VOSI} as described in DALI \citep{std:DALI}.
207    
208     \subsection{Capabilities: VOSI-capabilities}
209    
210 francois 3183 A web service that includes SODA capabilities must
211 msdemlei 3130 have a VOSI-capabilities resource \citep{std:VOSI} as described in DALI
212     \citep{std:DALI}. The standardID for the \{sync\} resource is
213 msdemlei 3188 $$\hbox{\texttt{ivo://ivoa.net/std/SODA\#sync-1.0}.}$$
214 msdemlei 3130
215     The standardID for the \{async\} resource is
216    
217 msdemlei 3188 $$\hbox{\texttt{ivo://ivoa.net/std/SODA\#async-1.0}.}$$
218 msdemlei 3130
219     All DAL services must implement the \texttt{/capabilities} resource.
220     The following capabilities document shows the minimal
221 francois 3183 metadata for a stand-alone SODA service and does not
222 msdemlei 3130 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 msdemlei 3188 <capability standardid="ivo://ivoa.net/std/SODA#sync-1.0">
243 msdemlei 3130 <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 msdemlei 3188 <capability standardid="ivo://ivoa.net/std/SODA#async-1.0">
251 msdemlei 3130 <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 msdemlei 3191 \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 francois 3194 ``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 msdemlei 3191 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 francois 3194 \subsubsection{Discovery of Supported Parameter. Implementation strategies}
319 msdemlei 3191 \label{sect:discovery-supported}
320    
321     There are two principal ways a client will be led to a SODA service:
322 francois 3194 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 msdemlei 3191 from the applicable service descriptor.
326    
327 francois 3194 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 msdemlei 3191
336 francois 3194 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 msdemlei 3191
338 francois 3194 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 msdemlei 3191
340 francois 3194 \subsubsection{SODA Service Descriptor}
341     \label{sect:serv-desc}
342 msdemlei 3191
343 francois 3194 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 msdemlei 3191
352 francois 3194 \begin{lstlisting}[language=XML,basicstyle=\footnotesize]
353 msdemlei 3191
354 francois 3194 <RESOURCE type="meta" utype="adhoc:service" name="this">
355 msdemlei 3191
356 francois 3194 <PARAM name="standardID" datatype="char" arraysize="*"
357     value="ivo://ivoa.net/std/SODA#sync-1.0" />
358 msdemlei 3191
359 francois 3194 <PARAM name="accessURL" datatype="char" arraysize="*"
360     value="http://example.com/SODA/sync" />
361 msdemlei 3191
362 francois 3194 <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 msdemlei 3191
380     \end{lstlisting}
381    
382 francois 3194 This VOTable resource should be output for empty sync
383     queries; Thus all inputs and outputs would be fully
384     described.
385 msdemlei 3191
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 francois 3194 \item Obtain the parameter triples domains as
393 msdemlei 3191 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 msdemlei 3130 \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 msdemlei 3191 \label{sect:ID}
419 msdemlei 3130
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 msdemlei 3192 as-is. The DataLink specification \citep{std:datalink} describes mechanisms
425 msdemlei 3130 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 francois 3183 \{sync\} soda requests access a single dataset or file.
431 msdemlei 3130 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 msdemlei 3189 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 francois 3183
440    
441 msdemlei 3130 \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 msdemlei 3189 does not intersect the bounds of the data).
453 msdemlei 3130
454     \subsubsection{POS}
455 msdemlei 3191 \label{sect:POS}
456 msdemlei 3130
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 msdemlei 3189 \begin{tabular}{ll}
464 msdemlei 3130 \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 msdemlei 3189 As in DALI, open intervals use -Inf or +Inf as one limit.
476 msdemlei 3130
477 msdemlei 3189 Examples for POS values:
478 msdemlei 3130
479 msdemlei 3189 \begin{itemize}
480     \item A circle at (12,34) with radius 0.5:
481    
482 msdemlei 3130 \begin{lstlisting}
483     POS=CIRCLE 12 34 0.5
484     \end{lstlisting}
485    
486 msdemlei 3189 \item A range of [12,14] in longitude and [34,36] in latitude:
487 msdemlei 3130
488     \begin{lstlisting}
489     POS=RANGE 12 14 34 36
490     \end{lstlisting}
491    
492 msdemlei 3189 \item A polygon from (12,34) to (14,34) to (14,36) to (12,36) and
493 msdemlei 3130 (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 msdemlei 3189 \item A band around the equator:
504 msdemlei 3130
505     \begin{lstlisting}
506     POS=RANGE 0 360 -2 2
507     \end{lstlisting}
508    
509 msdemlei 3189 \item The north pole:
510 msdemlei 3130
511     \begin{lstlisting}
512 francois 3183 POS=RANGE 0 360 89 +Inf
513 msdemlei 3130 \end{lstlisting}
514 msdemlei 3189 \end{itemize}
515 msdemlei 3130
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 francois 3183 data).
525 msdemlei 3130
526     The POS parameter is single-valued for \{sync\} requests and
527     multi-valued for \{async\} jobs.
528    
529 msdemlei 3189 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 msdemlei 3130
533     \subsubsection{BAND}
534 msdemlei 3191 \label{sect:BAND}
535 msdemlei 3130
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 msdemlei 3189 always include the bounding values. As in DALI, open intervals use -Inf
541     or +Inf as one limit.
542 msdemlei 3130
543     If there is one single value the interval is assumed to be
544     infinitely small (a scalar value).
545    
546 msdemlei 3189 \begin{itemize}
547     \item The closed interval [500,550]:
548 msdemlei 3130
549     \begin{lstlisting}
550     BAND=500 550
551     \end{lstlisting}
552    
553 msdemlei 3189 \item The open interval (-inf,300]:
554 msdemlei 3130
555     \begin{lstlisting}
556 francois 3183 BAND=-Inf 300
557 msdemlei 3130 \end{lstlisting}
558    
559 msdemlei 3189 \item The open interval [750,inf):
560 msdemlei 3130
561     \begin{lstlisting}
562 francois 3183 BAND=750 +Inf
563 msdemlei 3130 \end{lstlisting}
564    
565 msdemlei 3189 \item The scalar value 550, equivalent to [550,550]:
566 msdemlei 3130
567     \begin{lstlisting}
568     BAND=550
569     \end{lstlisting}
570    
571 msdemlei 3189 \end{itemize}
572    
573 msdemlei 3130 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 msdemlei 3189 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 msdemlei 3130
588 francois 3183
589 msdemlei 3130 \subsubsection{TIME}
590 msdemlei 3191 \label{sect:TIME}
591 msdemlei 3130
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 msdemlei 3189 Julian Dates). As in DALI, open intervals use -Inf or +Inf as one limit.
596 msdemlei 3130
597     If there is one single value the numeric interval is assumed
598     to be infinitely small (a scalar value).
599    
600 msdemlei 3189 \begin{itemize}
601     \item An open interval from the MJD 55100.0 and all later times:
602 msdemlei 3130
603     \begin{lstlisting}
604 francois 3183 TIME= 55100.0 +Inf
605 msdemlei 3130 \end{lstlisting}
606    
607 msdemlei 3189 \item A range of MJD values:
608 msdemlei 3130
609     \begin{lstlisting}
610     TIME=55123.456 55123.466
611     \end{lstlisting}
612    
613 msdemlei 3189 \item An instant in time using Modified Julian Date:
614 msdemlei 3130
615     \begin{lstlisting}
616     TIME=55678.123456
617     \end{lstlisting}
618 msdemlei 3189 \end{itemize}
619 msdemlei 3130
620 francois 3183 Time values are always UTC.
621 msdemlei 3130 The TIME parameter is single-valued for \{sync\} requests and
622     multi-valued for \{async\} jobs.
623    
624 msdemlei 3189 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 msdemlei 3130
629 francois 3183
630 msdemlei 3130 \subsubsection{POL}
631 msdemlei 3191 \label{sect:POL}
632 msdemlei 3130
633     The POL parameter defines the polarization state(s) (Stokes)
634     to be extracted from the data.
635    
636 msdemlei 3189 \begin{itemize}
637     \item Extract the unpolarized intensity:
638 msdemlei 3130 \begin{lstlisting}
639     POL=I
640     \end{lstlisting}
641 msdemlei 3189 \item Extract the standard circular polarization:
642 msdemlei 3130 \begin{lstlisting}
643     POL=V
644     \end{lstlisting}
645 msdemlei 3189
646     \item The POL parameter is multi-valued; multiple values can be
647 msdemlei 3130 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 msdemlei 3189 \end{itemize}
655 msdemlei 3130
656 msdemlei 3189 The POL is multi-valued for both \{sync\} and \{async\} requests.
657 msdemlei 3130 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 msdemlei 3189 combination of ID and other filtering parameters).
662 msdemlei 3130
663 msdemlei 3189 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 msdemlei 3130
666    
667    
668     \section{\{sync\} Responses}
669    
670 francois 3183 All responses from the \{sync\} resource follow the rules for
671     DALI-sync resources, except that the \{sync\} response allows
672 msdemlei 3130 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 francois 3194 set.
699 msdemlei 3130
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 francois 3194 \caption{error messages with their meaning}
717 msdemlei 3130 \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 francois 3183 \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 msdemlei 3130 \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 msdemlei 3190 This is the initial document version.
757 msdemlei 3130
758     \bibliography{ivoatex/ivoabib}
759    
760     \end{document}

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