/[volute]/trunk/projects/grid/uws/UWSRegExt/UWSRegExt.tex
ViewVC logotype

Diff of /trunk/projects/grid/uws/UWSRegExt/UWSRegExt.tex

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

revision 5063 by major.brian, Wed May 30 00:06:19 2018 UTC revision 5064 by msdemlei, Mon Jun 25 11:14:29 2018 UTC
# Line 1  Line 1 
1  \documentclass[11pt,a4paper]{ivoa}  \documentclass[11pt,a4paper]{ivoa}
2  \input tthdefs  \input tthdefs
3    
4  \usepackage{verbatim}  \usepackage{listings}
5    \lstloadlanguages{XML,SQL}
6    \lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False,
7      basicstyle=\footnotesize}
8    
9  \title{UWS Registry Extension}  \title{UWS Registry Extension}
10    
# Line 39  Line 42 
42    
43  \section{Introduction}  \section{Introduction}
44    
45  This note describes the registry extension for the Universal Worker Service (UWS) \citep{std:UWS}.  Registry extensions add information to the schema defined in VOResource \citep{std:VOR} that are specific to a particular standard, in this case UWS.  This note describes the registry extension for the Universal Worker Service UWS \citep{std:UWS}.  Registry extensions add information to the schema defined in VOResource \citep{std:VOR} that are specific to a particular standard, in this case UWS.
46    
47  The UWS registry extension is very simple--it allows for two new values to be set on the \emph{type} attribute in the \xmlel{interface} element in a VOResource \xmlel{capability}.  These types have the purpose of identifying the \xmlel{interface} as one of the synchronous or asynchronous UWS job execution features.  The UWS registry extension is very simple--it allows for two new values to be set on the \emph{type} attribute in the \xmlel{interface} element in a VOResource \xmlel{capability}.  These types have the purpose of identifying the \xmlel{interface} as one of the synchronous or asynchronous UWS job execution features.
48    
# Line 68  Line 71 
71    
72  \subsection{Motivation}  \subsection{Motivation}
73    
74  During the review of the TAP 1.1 specification (\citep{std:TAP}), it was discovered that, when searching for TAP instances, there is the potential for clients of RegTAP (\citep{std:RegTAP} to discover multiple \xmlel{interface} results per instance when only one is expected.    During the review of the TAP 1.1 specification \citep{std:TAP}, it was discovered that, when searching for TAP instances, there is the potential for clients of RegTAP \citep{std:RegTAP} to discover multiple \xmlel{interface} results per instance when only one is expected.  
75    
76  TAP clients currently follow the recommendations of RegTAP 1.1 to discover TAP access URLs and issue a query like this:  TAP clients currently follow the recommendations of RegTAP 1.1 to discover TAP access URLs and issue a query like this:
77    
78  \begin{verbatim}  \begin{lstlisting}[language=SQL]
79  SELECT ivoid, access_url  SELECT ivoid, access_url
80      FROM rr.capability      FROM rr.capability
81      NATURAL JOIN rr.interface      NATURAL JOIN rr.interface
82      WHERE standard_id like 'ivo://ivoa.net/std/tap%'      WHERE standard_id like 'ivo://ivoa.net/std/tap%'
83      AND intf_type='vs:paramhttp'      AND intf_type='vs:paramhttp'
84  \end{verbatim}  \end{lstlisting}
85    
86  This query is sufficient for most of the existing registered TAP services and will return only one result.  Those records typically look like this:  This query is sufficient for most of the existing registered TAP services and will return only one result.  Those records typically look like this:
87    
88  \begin{verbatim}  \begin{lstlisting}[language=XML]
89    <capability standardID="ivo://ivoa.net/std/TAP">    <capability standardID="ivo://ivoa.net/std/TAP">
90      <interface xsi:type="vod:ParamHTTP" role="std">      <interface xsi:type="vod:ParamHTTP" role="std">
91        <accessURL use="base">http://example.com/tap</accessURL>        <accessURL use="base">http://example.com/tap</accessURL>
92      </interface>      </interface>
93    </capability>    </capability>
94  \end{verbatim}  \end{lstlisting}
95    
96  To then use the sync and async endpoints of the TAP service, clients simply append /sync and /async to the end of the base access URL, as per the recommendations of TAP version 1.0.  To then use the sync and async endpoints of the TAP service, clients simply append /sync and /async to the end of the base access URL, as per the recommendations of TAP version 1.0.
97    
# Line 98  Line 101 
101    
102  Here is an example of the \xmlel{capability} element of the (now obsolete) synchronous endpoint in TAP 1.1:  Here is an example of the \xmlel{capability} element of the (now obsolete) synchronous endpoint in TAP 1.1:
103    
104  \begin{verbatim}  \begin{lstlisting}[language=XML]
105    <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">    <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
106      <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">      <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
107        <accessURL use="base">http://example.com/tap/sync</accessURL>        <accessURL use="base">http://example.com/tap/sync</accessURL>
108      </interface>      </interface>
109    </capability>    </capability>
110  \end{verbatim}  \end{lstlisting}
111    
112  \paragraph{Change \#2. Multiple \xmlel{interfaces} per \xmlel{capability}} Although, in VOResource, it has always been the case that multiple \xmlel{interfaces} are allowed per \xmlel{capability}, no services had yet to be registered with such a configuration.  This changed when some TAP implementations introduced TAP endpoints with a variety of \xmlel{SecurityMethods}.  To document such a configuration, multiple \xmlel{interfaces} per \xmlel{capability} must be created, each with a different \xmlel{SecurityMethod}.  Or, when the access URLs are the same, a single \xmlel{interface} with multiple \xmlel{SecurityMethods} could be created.  Each configuration causes difficulties for registry service lookup.  \paragraph{Change \#2. Multiple \xmlel{interfaces} per \xmlel{capability}} Although, in VOResource, it has always been the case that multiple \xmlel{interfaces} are allowed per \xmlel{capability}, no services had yet to be registered with such a configuration.  This changed when some TAP implementations introduced TAP endpoints with a variety of \xmlel{SecurityMethod}\/s.  To document such a configuration, multiple \xmlel{interfaces} per \xmlel{capability} must be created, each with a different \xmlel{SecurityMethod}.  Or, when the access URLs are the same, a single \xmlel{interface} with multiple \xmlel{SecurityMethod}\/s could be created.  Each configuration causes difficulties for registry service lookup.
113    
114  Here is an example of the \xmlel{capability} element of the synchronous endpoint in TAP 1.1 (now obsolete) with multiple \xmlel{interfaces} to support multiple \xmlel{SecurityMethods}:  Here is an example of the \xmlel{capability} element of the synchronous endpoint in TAP 1.1 (now obsolete) with multiple \xmlel{interfaces} to support multiple \xmlel{SecurityMethod}\/s:
115    
116  \begin{verbatim}  \begin{lstlisting}[language=XML]
117    <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">    <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
118      <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">      <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
119        <accessURL use="base">http://example.com/tap/sync</accessURL>        <accessURL use="base">http://example.com/tap/sync</accessURL>
# Line 120  Line 123 
123        <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>        <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
124      </interface>      </interface>
125    </capability>    </capability>
126  \end{verbatim}  \end{lstlisting}
127    
128  Note that, though this issue was discovered on the review of TAP 1.1, it applies to all IVOA services that need to provide potentially different access URLs for each \xmlel{SecurityMethod}.  Note that, though this issue was discovered on the review of TAP 1.1, it applies to all IVOA services that need to provide potentially different access URLs for each \xmlel{SecurityMethod}.
129    
130  \subsection{Reaction}  \subsection{Reaction}
131    
132  To address problem \#2 described above, RegTAP 1.1 recommends that an additional constraint of having a null \xmlel{SecurityMethod} is included in the where clause of the TAP service discovery query.  However, for this to work, there cannot be a case where an \xmlel{interface} is reused by multiple \xmlel{securityMethods}, as this would not allow the constraint of a null securityMethod to work if the endpoint supported other non-null securityMethods.  So, VOResource 1.1 has ensures that at most one \xmlel{SecurityMethod} is allowed per \xmlel{interface}.  To address problem \#2 described above, RegTAP 1.1 recommends that an additional constraint of having a null \xmlel{SecurityMethod} is included in the where clause of the TAP service discovery query.  However, for this to work, there cannot be a case where an \xmlel{interface} is reused by multiple \xmlel{securityMethod}\/s, as this would not allow the constraint of a null securityMethod to work if the endpoint supported other non-null \xmlel{securityMethod}\/s.  So, VOResource 1.1 has ensures that at most one \xmlel{SecurityMethod} is allowed per \xmlel{interface}.
133    
134  Problem \#1 is addressed in two ways:  One:  By removing multiple standard IDs from TAP 1.1; and, two:  by the use of this UWS Registry Extension.  TAP 1.1 has removed the use of standardIDs for sync and async and instead now only uses the version agnostic standardID from TAP 1.0:  \xmlel{ivo://ivoa.net/std/TAP}.  Clients can recognize the TAP service as version 1.1 by checking for a \xmlel{version} attribute with the value "1.1" in the \xmlel{capability}.  In order to allow services to choose their own access URLs for sync and async queries, \xmlel{interface} elements within the \xmlel{capability} are created for each type of \xmlel{SecurityMethod} that is supported.  There may be both sync and async versions of these \xmlel{interfaces}.  Whether an interface is sync or async is determined by the \emph{type} attribute in the \xmlel{interface}.  To support TAP 1.0 backwards compatibility, a TAP 1.0 style \xmlel{interface} must remain in the \xmlel{capabilities}.  Problem \#1 is addressed in two ways:  One:  By removing multiple standard IDs from TAP 1.1; and, two:  by the use of this UWS Registry Extension.  TAP 1.1 has removed the use of standardIDs for sync and async and instead now only uses the version agnostic standardID from TAP 1.0:  \xmlel{ivo://ivoa.net/std/TAP}.  Clients can recognize the TAP service as version 1.1 by checking for a \xmlel{version} attribute with the value "1.1" in the \xmlel{capability}.  In order to allow services to choose their own access URLs for sync and async queries, \xmlel{interface} elements within the \xmlel{capability} are created for each type of \xmlel{SecurityMethod} that is supported.  There may be both sync and async versions of these \xmlel{interfaces}.  Whether an interface is sync or async is determined by the \emph{type} attribute in the \xmlel{interface}.  To support TAP 1.0 backwards compatibility, a TAP 1.0 style \xmlel{interface} must remain in the \xmlel{capabilities}.
135    
# Line 136  Line 139 
139    
140  This first version of the UWS Registry Extension enables UWS services to be registered with UWS-specific interface types so that they can be discovered by clients in a standard way defined by this note.  This means that specifications built on UWS need not specify additional details on how to discover UWS RESTful endpoints.  This first version of the UWS Registry Extension enables UWS services to be registered with UWS-specific interface types so that they can be discovered by clients in a standard way defined by this note.  This means that specifications built on UWS need not specify additional details on how to discover UWS RESTful endpoints.
141    
142  The UWS Registry Extension introduces two new \xmlel{interface} types: one for synchronous jobs and one for asynchronous jobs.  The surrounding \xmlel{capability} element should be marked with the minor version of service specification, as per the recommendations in the XML schema versioning note (\citep{std:schemaversioning})).  The UWS Registry Extension introduces two new \xmlel{interface} types: one for synchronous jobs and one for asynchronous jobs.  The surrounding \xmlel{capability} element should be marked with the minor version of service specification, as per the recommendations in the XML schema versioning note \citep{2018ivoa.spec.0529H}.
143    
144  \begin{table}  \begin{table}
145  \centering  \centering
# Line 156  Line 159 
159    
160  The following example describes how a TAP 1.1 service advertises its sync and async query endpoints under the single TAP capability.  Both sync and async support anonymous queries and authenticated queries with TLS \citep{std:SSOAUTH}.  The first two \xmlel{interface} are there to provide backwards compatibility support for 1.0 TAP clients.  The following example describes how a TAP 1.1 service advertises its sync and async query endpoints under the single TAP capability.  Both sync and async support anonymous queries and authenticated queries with TLS \citep{std:SSOAUTH}.  The first two \xmlel{interface} are there to provide backwards compatibility support for 1.0 TAP clients.
161    
162  \begin{verbatim}  \begin{lstlisting}[language=XML]
163    <capability standardID="ivo://ivoa.net/std/TAP">    <capability standardID="ivo://ivoa.net/std/TAP">
164            
165      # TAP 1.0 support      <!-- TAP 1.0 support -->
166      <capability standardID="ivo://ivoa.net/std/TAP">      <capability standardID="ivo://ivoa.net/std/TAP">
167        <interface xsi:type="vod:ParamHTTP" role="std">        <interface xsi:type="vod:ParamHTTP" role="std">
168          <accessURL use="base">http://example.com/tap</accessURL>          <accessURL use="base">http://example.com/tap</accessURL>
# Line 170  Line 173 
173        </interface>        </interface>
174      </capability>      </capability>
175            
176      # TAP 1.1 support      <!-- TAP 1.1 support -->
177      <interface      <interface
178           xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"           xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
179           xsi:type="uws:Sync" role="std" version="1.1">           xsi:type="uws:Sync" role="std" version="1.1">
# Line 195  Line 198 
198      </interface>      </interface>
199            
200    </capability>    </capability>
201  \end{verbatim}  \end{lstlisting}
202    
203  \subsection{XML Schema}  \subsection{XML Schema}
204    
205  The following is the XML Schema Definition for the UWS Registry Extension version 1.0.  It can be brought into an XML document's schema as a namespace with the URI \xmlel{http://www.ivoa.net/xml/UWSRegExt/v1.0}.  The following is the XML Schema Definition for the UWS Registry Extension version 1.0.  It can be brought into an XML document's schema as a namespace with the URI \xmlel{http://www.ivoa.net/xml/UWSRegExt/v1.0}.
206    
207  \verbatiminput{UWSRegExt-v1.0.xsd}  \lstinputlisting[language=XML]{UWSRegExt-v1.0.xsd}
208    
209  \appendix  \appendix
210  \section{Changes from Previous Versions}  \section{Changes from Previous Versions}

Legend:
Removed from v.5063  
changed lines
  Added in v.5064

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