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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 3199 by francois, Mon Dec 21 14:03:03 2015 UTC revision 3200 by francois, Thu Dec 31 17:05:05 2015 UTC
# Line 271  Line 271 
271  material.  material.
272  \end{admonition}  \end{admonition}
273  \subsection{Parameter Description and Three-Factor Semantics}  \subsection{Parameter Description and Three-Factor Semantics}
 %  
 %In contrast to previous IVOA DAL protocols, SODA is not a data discovery  
 %protocol but instead operates on concrete datasets.  In a typical case,  
 %most combinations of parameters (e.g., a positional or spectral cutout)  
 %will yield no output at all, as the coverage of an individual dataset is  
 %very limited.  To provide meaningful user interfaces, clients therefore  
 %need detailed information on the service parameters, in particular as  
 %regards their domains (i.e., set of values that are likely to yield  
 %non-empty results).  
 %  
 %Conversely, efficient handling of complex datasets will typically  
 %require rich service APIs, not unlikely involving service-specific  
 %parameters.  It is therefore important that services provide expressive  
 %and correct metadata on each combination of service and dataset, and  
 %that clients interpret that metadata and use it in the generation of  
 %user interfaces (UIs) or, in the case of libraries, programming  
 %interfaces (APIs).  
 %  
 %To satisfy these requirements, this specification defines an extensible  
 %semantics for parameters as well as a simple recipe for the generation  
 %of UIs or APIs.  
274    
275  \subsubsection{Three-factor Semantics}  \subsubsection{Three-factor Semantics}
276    
# Line 358  Line 337 
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.  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    
 %\paragraph{SODA within a DAL response  
 %  
 %A service descriptor returned as part of DAL response (e.g., SIAv2 or  
 %SSAP) as described in DataLink applies to the entire set of returned  
 %documents.    
 %  
 %Services are should define the parameter domains using  
 %\xmlel{PARAM}/\xmlel{VALUES} as applicable to the entire subset returned  
 %even when clients can discover them from the metadata given in the DAL  
 %response.  For instance, in a response containing two cubes, one of  
 %which covers wavelengths between $650\,\rm nm$ and $750\,\rm nm$, the other  
 %covering $800\,\rm nm$ through $900\,\rm nm$, the declared PARAM would  
 %be  
 %  
 %\begin{lstlisting}[language=XML]  
 %<PARAM name="BAND" ucd="em" unit="m" type="float"  
 %    arraysize="2" xtype="interval">  
 %  <DESCRIPTION>Wavelength range to cut out</DESCRIPTION>  
 %  <VALUES>  
 %    <MIN value="6.5e-7"/>  
 %    <MAX value="9e-7"/>  
 %  </VALUES>  
 %</PARAM>  
 %\end{lstlisting}  
 %  
 %With non-standard parameters, services should try even harder to define  
 %the domain using \xmlel{VALUES} because otherwise clients will not be  
 %able to offer users discoverable UIs or APIs.  For instance,  
 %  
 %\begin{lstlisting}[language=XML]  
 %<PARAM name="FORMAT" arraysize="*" datatype="char"  
 %    ucd="meta.code.mime">  
 %  <DESCRIPTION>Media type of the output format the service  
 %    should generate.</DESCRIPTION>  
 %  <VALUES>  
 %    <OPTION name="VOTable, spectral DM 2 serialization"  
 %      value="application/x-votable+xml"/>  
 %    <OPTION name="FITS binary table" value="application/fits"/>  
 %    <OPTION name="Comma separated values" value="text/csv"/>  
 %  </VALUES>  
 %</PARAM>  
 %\end{lstlisting}  
 %  
 %In particular for such nonstandard parameters, providing an expressive  
 %\xmlel{DESCRIPTION} within the parameter is important to ensure users  
 %understand what the parameter effects.  
 %  
 %When building UIs or APIs, clients should use the the service-provided  
 %\xmlel{VALUES}.  In cases where one or more datasets are already  
 %selected by the user, clients may obtain domains for standard  
 %parameters from the provided metadata.  
 %  
 %With SODA descriptors embedded in DAL responses, there is additionally  
 %the mechanism of \xmlel{PARAM}\/s with \xmlel{ref} attributes as described  
 %by DataLink; for instance,  
 %  
 %\begin{lstlisting}[language=XML]  
 %<PARAM name="ID" arraysize="*" datatype="char" ref="ssa_pubDID"  
 %  ucd="meta.id;meta.main">  
 %  <DESCRIPTION>The pubisher DID of the dataset of  
 %    interest</DESCRIPTION>  
 %</PARAM>  
 %\end{lstlisting}  
 %  
 %These should never be exposed in UIs or APIs but instead immediately  
 %satisfied from the DAL response as described in DataLink.  
 %  
 %\paragraph{Standalone SODA}  
 %  
 %Here, the client only has a reference to or copy of a DataLink document  
 %describing the dataset.  This can happen as a result of an ObsTAP query  
 %that has yielded an access\_url with a DataLink access\_format -- as the  
 %set of returned columns is under user control, it may not have the  
 %complete metadata --, or because a discovered link is obtained from a web  
 %page or via SAMP.  
 %  
 %In such a DataLink document, the service must give \xmlel{PARAM} domains  
 %tailored to the dataset in question.  A cube with a spectral coverage  
 %from $800\,\rm nm$ to $900\,\rm nm$ would declare  
 %  
 %\begin{lstlisting}[language=XML]  
 %<PARAM name="BAND" ucd="em" unit="m" datatype="float"  
 %    arraysize="2" xtype="interval">  
 %  <DESCRIPTION>Wavelength range to cut out</DESCRIPTION>  
 %  <VALUES>  
 %    <MIN value="8e-7"/>  
 %    <MAX value="9e-7"/>  
 %  </VALUES>  
 %</PARAM>  
 %\end{lstlisting}  
 %  
 %A custom parameter letting a user retrieve only certain orders of an  
 %Echelle spectrum would be declared as follows when orders 85 through 142  
 %are present in the given dataset:  
 %  
 %\begin{lstlisting}[language=XML]  
 %<PARAM name="ECHELLE_ORDER" datatype="short" ucd="instr.order"  
 %    arraysize="2" xtype="interval">  
 %  <DESCRIPTION>Echelle orders to retrieve</DESCRIPTION>  
 %  <VALUES>  
 %    <MIN value="85"/>  
 %    <MAX value="142"/>  
 %  </VALUES>  
 %</PARAM>  
 %\end{lstlisting}  
 %  
 %UIs and APIs should provide simple means of accessing information on the  
 %domains of the parameters, as well as the service-provided  
 %\xmlel{DESCRIPTION}.  
 %  
340  \subsubsection{SODA Service Descriptor}  \subsubsection{SODA Service Descriptor}
341  \label{sect:serv-desc}  \label{sect:serv-desc}
342    
# Line 533  Line 402 
402  \end{enumerate}  \end{enumerate}
403    
404    
 %Clients should  
 %assume that intervals can only be given once, whereas enumerated  
 %parameters can be given multiple times.  
   
 %This heuristics will yield erroneous results in important cases (e.g.,  
 %the FORMAT parameter defined above that can reasonably be assumed to be  
 %singled-valued in almost all services).  Services should, in the  
 %presence of such interface problems, proceed in a best-effort way (i.e.,  
 %not fail and rather pick one of the user-provided values).  
   
 %jhWe expect that the declaration of parameter multiplicities, as well as  
 %annotating conflicting parameters (e.g., when a constraint is given both  
 %in physical and pixel coordinates) will be effected using a suitable  
 %data model (e.g., PDL) in VO-DML; clients should therefore be prepared  
 %to encounter VO-DML \xmlel{GROUP}\/s in DataLink responses.  In SODA  
 %development, we will make sure that clients ignoring such  
 %\xmlel{GROUP}\/s will be compatible with such future SODA services.  
405    
406    
407  \section{Parameters for \{sync\} and \{async\}}  \section{Parameters for \{sync\} and \{async\}}
# Line 845  Line 697 
697  Content-Length and Last-Modified headers cannot usually be  Content-Length and Last-Modified headers cannot usually be
698  set.  set.
699    
 %\todo{If we say that, we should at least mention chunked transfers, or  
 %people might think they have to close the connections. -- Markus}  
700    
701  \subsection{Errors}  \subsection{Errors}
702    

Legend:
Removed from v.3199  
changed lines
  Added in v.3200

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