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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5118 - (hide annotations)
Fri Aug 24 22:49:29 2018 UTC (2 years, 1 month ago) by major.brian
File MIME type: application/x-tex
File size: 13147 byte(s)
fixed biblio references
1 major.brian 4969 \documentclass[11pt,a4paper]{ivoa}
2     \input tthdefs
3    
4 msdemlei 5064 \usepackage{listings}
5     \lstloadlanguages{XML,SQL}
6     \lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False,
7     basicstyle=\footnotesize}
8 major.brian 4969
9 major.brian 5005 \title{UWS Registry Extension}
10 major.brian 4969
11 major.brian 5005 \ivoagroup{Grid and Web Services}
12 major.brian 4969
13 major.brian 5116 \author{Patrick Dowler}
14     \author{Markus Demleitner}
15 major.brian 5005 \author{Brian Major}
16 major.brian 5021 \author{Mark Taylor}
17 major.brian 4969
18 major.brian 5005 \editor{Brian Major}
19    
20 major.brian 4969 \previousversion{This is the first public release}
21    
22     \begin{document}
23     \begin{abstract}
24    
25 msdemlei 5065 The Universal Worker Service (UWS) Registry Extension allows for
26     extended metadata to be set on a VOResource \xmlel{interface} for the
27     purpose of tagging UWS job execution access URLs.
28 major.brian 4969
29 major.brian 5005 \end{abstract}
30 major.brian 4969
31     \section*{Conformance-related definitions}
32    
33     The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
34     ``OPTIONAL'' (in upper or lower case) used in this document are to be
35     interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.
36    
37     The \emph{Virtual Observatory (VO)} is a
38     general term for a collection of federated resources that can be used
39     to conduct astronomical research, education, and outreach.
40     The \href{http://www.ivoa.net}{International
41     Virtual Observatory Alliance (IVOA)} is a global
42     collaboration of separately funded projects to develop standards and
43     infrastructure that enable VO applications.
44    
45     \section{Introduction}
46    
47 msdemlei 5065 This note describes the registry extension for the Universal Worker
48     Service UWS \citep{std:UWS}. Registry extensions add information to the
49     schema defined in VOResource \citep{std:VOR} that are specific to a
50     particular standard, in this case UWS.
51 major.brian 4969
52 msdemlei 5065 The UWS registry extension is very simple--it allows for two new values
53     to be set on the \emph{type} attribute in the \xmlel{interface} element
54     in a VOResource \xmlel{capability}. These types have the purpose of
55     identifying the \xmlel{interface} as one of the synchronous or
56     asynchronous UWS job execution features.
57 major.brian 4969
58 msdemlei 5065 Although the UWS registry extension itself is simple, the history of the
59     need for it is complicated. This history is described in section
60     \ref{background}. The extension itself is described in section
61     \ref{uwsregext}.
62 major.brian 5005
63 major.brian 5021 %\subsection{Role within the VO Architecture}
64    
65     %\begin{figure}
66     %\centering
67    
68     % As of ivoatex 1.2, the architecture diagram is generated by ivoatex in
69     % SVG; copy ivoatex/archdiag-full.xml to archdiag.xml and throw out
70     % all lines not relevant to your standard.
71     % Notes don't generally need this. If you don't copy archdiag.xml,
72     % you must remove archdiag.svg from FIGURES in the Makefile.
73    
74     %\includegraphics[width=0.9\textwidth]{archdiag.svg}
75     %\caption{Architecture diagram for this document}
76     %\label{fig:archdiag}
77     %\end{figure}
78    
79     %Fig.~\ref{fig:archdiag} shows the role this document plays within the
80     %IVOA architecture \citep{note:VOARCH}.
81    
82 major.brian 5005 \section{Background} \label{background}
83    
84     \subsection{Motivation}
85    
86 major.brian 5099 During the review of the TAP 1.1 specification \citep{std:TAP11}, it was
87 msdemlei 5065 discovered that, when searching for TAP instances, there is the
88     potential for clients of RegTAP \citep{std:RegTAP} to discover multiple
89     \xmlel{interface} results per instance when only one is expected.
90 major.brian 5005
91 msdemlei 5065 TAP clients currently follow the recommendations of RegTAP 1.1 to
92     discover TAP access URLs and issue a query like this:
93 major.brian 5005
94 msdemlei 5064 \begin{lstlisting}[language=SQL]
95 major.brian 5005 SELECT ivoid, access_url
96     FROM rr.capability
97     NATURAL JOIN rr.interface
98     WHERE standard_id like 'ivo://ivoa.net/std/tap%'
99     AND intf_type='vs:paramhttp'
100 msdemlei 5064 \end{lstlisting}
101 major.brian 5005
102 msdemlei 5065 This query is sufficient for most of the existing registered TAP
103     services and will return only one result. Those records typically look
104     like this:
105 major.brian 5005
106 msdemlei 5064 \begin{lstlisting}[language=XML]
107 major.brian 5005 <capability standardID="ivo://ivoa.net/std/TAP">
108     <interface xsi:type="vod:ParamHTTP" role="std">
109     <accessURL use="base">http://example.com/tap</accessURL>
110     </interface>
111     </capability>
112 msdemlei 5064 \end{lstlisting}
113 major.brian 5005
114 msdemlei 5065 To then use the sync and async endpoints of the TAP service, clients
115     simply append /sync and /async to the end of the base access URL, as per
116     the recommendations of TAP version 1.0.
117 major.brian 5005
118 msdemlei 5065 Two things have changed since VOResource version 1.03 that make this
119     query to find all TAP services incorrect:
120 major.brian 5005
121 msdemlei 5065 \paragraph{Change \#1. Multiple standard IDs in TAP} TAP 1.1 originally
122     stated that the standard IDs of sync and async are distinct and each are
123     registered. Although this gives services the flexibility to use URLs
124     for sync and async that don't end in precisely /sync and /async, it
125     breaks the pattern of TAP 1.0 service discovery. With the search
126     recommended by RegTAP, clients would find the \xmlel{interfaces} within
127     each of the \xmlel{capabilities} and attempt to append /sync and /async
128     to the endpoints.
129 major.brian 5005
130 msdemlei 5065 Here is an example of the \xmlel{capability} element of the (now
131     obsolete) synchronous endpoint in TAP 1.1:
132 major.brian 5005
133 msdemlei 5064 \begin{lstlisting}[language=XML]
134 major.brian 5005 <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
135     <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
136     <accessURL use="base">http://example.com/tap/sync</accessURL>
137     </interface>
138     </capability>
139 msdemlei 5064 \end{lstlisting}
140 major.brian 5005
141 msdemlei 5065 \paragraph{Change \#2. Multiple \xmlel{interfaces} per
142     \xmlel{capability}} Although, in VOResource, it has always been the case
143     that multiple \xmlel{interfaces} are allowed per \xmlel{capability}, no
144     services had yet to be registered with such a configuration. This
145     changed when some TAP implementations introduced TAP endpoints with a
146     variety of \xmlel{SecurityMethod}\/s. To document such a configuration,
147     multiple \xmlel{interfaces} per \xmlel{capability} must be created, each
148     with a different \xmlel{SecurityMethod}. Or, when the access URLs are
149     the same, a single \xmlel{interface} with multiple
150     \xmlel{SecurityMethod}\/s could be created. Each configuration causes
151     difficulties for registry service lookup.
152 major.brian 5005
153 msdemlei 5065 Here is an example of the \xmlel{capability} element of the synchronous
154     endpoint in TAP 1.1 (now obsolete) with multiple \xmlel{interfaces} to
155     support multiple \xmlel{SecurityMethod}\/s:
156 major.brian 5005
157 msdemlei 5064 \begin{lstlisting}[language=XML]
158 major.brian 5005 <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
159     <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
160     <accessURL use="base">http://example.com/tap/sync</accessURL>
161     </interface>
162     <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
163     <accessURL use="base">https://example.com/tap/sync</accessURL>
164     <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
165     </interface>
166     </capability>
167 msdemlei 5064 \end{lstlisting}
168 major.brian 5005
169 msdemlei 5065 Note that, though this issue was discovered on the review of TAP 1.1, it
170     applies to all IVOA services that need to provide potentially different
171     access URLs for each \xmlel{SecurityMethod}.
172 major.brian 5005
173 major.brian 5024 \subsection{Reaction}
174 major.brian 5005
175 msdemlei 5065 To address problem \#2 described above, RegTAP 1.1 recommends that an
176     additional constraint of having a null \xmlel{SecurityMethod} is
177     included in the where clause of the TAP service discovery query.
178     However, for this to work, there cannot be a case where an
179     \xmlel{interface} is reused by multiple \xmlel{securityMethod}\/s, as
180     this would not allow the constraint of a null securityMethod to work if
181     the endpoint supported other non-null \xmlel{securityMethod}\/s. So,
182 major.brian 5099 VOResource 1.1 has ensured that at most one \xmlel{SecurityMethod} is
183 msdemlei 5065 allowed per \xmlel{interface}.
184 major.brian 5005
185 msdemlei 5065 Problem \#1 is addressed in two ways: One: By removing multiple
186     standard IDs from TAP 1.1; and, two: by the use of this UWS Registry
187     Extension. TAP 1.1 has removed the use of standardIDs for sync and
188     async and instead now only uses the version agnostic standardID from TAP
189     1.0: \xmlel{ivo://ivoa.net/std/TAP}. Clients can recognize the TAP
190     service as version 1.1 by checking for a \xmlel{version} attribute with
191 major.brian 5099 the value "1.1" in the various \xmlel{interface} elements within the capability.
192     In order to allow services to choose their own access URLs for sync and
193     async queries, \xmlel{interface} elements within the \xmlel{capability} are
194     created for each type of \xmlel{SecurityMethod} that is supported. There
195     may be both sync and async versions of these \xmlel{interfaces}. Whether
196     an interface is sync or async is determined by the \emph{type} attribute in
197 msdemlei 5065 the \xmlel{interface}. To support TAP 1.0 backwards compatibility, a
198     TAP 1.0 style \xmlel{interface} must remain in the \xmlel{capabilities}.
199 major.brian 5005
200     \section{UWS Registry Extension} \label{uwsregext}
201    
202 msdemlei 5065 A number of IVOA services have functionality built on the Universal
203     Worker Service. Jobs, which perform service-specific functions, can be
204     created and started in either a synchronous or asynchronous manner.
205 major.brian 5118 These services include TAP \citep{std:TAP11}, VOSpace \citep{std:VOSpace},
206 msdemlei 5065 and others. It is the UWS specification itself that defines how the
207     lifecycle of these jobs is managed through a RESTful interface, not the
208     services that are built on top of them. However, in the past, it has
209 major.brian 5099 been left to the services to state how the synchronous and asynchronous
210     endpoints are to be discovered through the IVOA registry.
211 major.brian 5005
212 msdemlei 5065 This first version of the UWS Registry Extension enables UWS services to
213     be registered with UWS-specific interface types so that they can be
214     discovered by clients in a standard way defined by this note. This
215     means that specifications built on UWS need not specify additional
216     details on how to discover UWS RESTful endpoints.
217 major.brian 5005
218 msdemlei 5065 The UWS Registry Extension introduces two new \xmlel{interface} types:
219     one for synchronous jobs and one for asynchronous jobs. The surrounding
220 major.brian 5099 \xmlel{interface} element should be marked with the minor version of
221 msdemlei 5065 service specification, as per the recommendations in the XML schema
222     versioning note \citep{2018ivoa.spec.0529H}.
223 major.brian 5005
224     \begin{table}
225 major.brian 4969 \centering
226 major.brian 5005 \begin{tabular}{| c | c | c |}
227     \hline
228     & Asynchronous & Synchronous \\
229     \hline
230 major.brian 5116 Interface Type & urx:Async & urx:Sync \\
231 major.brian 5005 \hline
232     \end{tabular}
233     \caption{UWS Async and Sync interface types}
234     \end{table}
235 major.brian 4969
236 msdemlei 5065 Future versions of the UWS Registry Extension may allow for more detail
237     to be added about the UWS interfaces. This first version only supplies
238     the two new \xmlel{interface} types so that they can be used by UWS
239     services to \emph{tag} their sync and async endpoints.
240 major.brian 4969
241 major.brian 5005 \subsection{Example TAP 1.1 capability}
242 major.brian 4969
243 msdemlei 5065 The following example describes how a TAP 1.1 service advertises its
244     sync and async query endpoints under the single TAP capability. Both
245     sync and async support anonymous queries and authenticated queries with
246     TLS \citep{std:SSOAUTH}. The first two \xmlel{interface} are there to
247     provide backwards compatibility support for 1.0 TAP clients.
248 major.brian 4969
249 msdemlei 5064 \begin{lstlisting}[language=XML]
250 major.brian 5116
251     <vosi:capabilities
252     xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
253     xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
254     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
255     xmlns:urx="http://www.ivoa.net/xml/UWSRegExt/v0.1">
256    
257 major.brian 5005 <capability standardID="ivo://ivoa.net/std/TAP">
258    
259 msdemlei 5064 <!-- TAP 1.0 support -->
260 msdemlei 5066 <interface xsi:type="vod:ParamHTTP" role="std">
261     <accessURL use="base">http://example.com/tap</accessURL>
262     </interface>
263     <interface xsi:type="vod:ParamHTTP" role="std">
264 major.brian 5099 <accessURL use="base">https://example.com/tap</accessURL>
265 msdemlei 5066 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
266     </interface>
267 major.brian 5005
268 msdemlei 5064 <!-- TAP 1.1 support -->
269 major.brian 5005 <interface
270 major.brian 5116 xsi:type="urx:Sync" role="std" version="1.1">
271 major.brian 5005 <accessURL use="base">http://example.com/tap/sync</accessURL>
272     </interface>
273     <interface
274 major.brian 5116 xsi:type="urx:Sync" role="std" version="1.1">
275 major.brian 5005 <accessURL use="base">https://example.com/tap/sync</accessURL>
276     <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
277     </interface>
278     <interface
279 major.brian 5116 xsi:type="urx:Async" role="std" version="1.1">
280 major.brian 5005 <accessURL use="base">http://example.com/tap/async</accessURL>
281     </interface>
282     <interface
283 major.brian 5116 xsi:type="urx:Async" role="std" version="1.1">
284 major.brian 5005 <accessURL use="base">https://example.com/tap/async</accessURL>
285     <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
286     </interface>
287    
288     </capability>
289 major.brian 5116
290     </vosi:capabilities>
291 msdemlei 5064 \end{lstlisting}
292 major.brian 4969
293 major.brian 5116 In the examples in this document, the prefix \xmlel{urx} is used to refer to
294     the UWSRegExt namespace. It should be noted that this prefix is arbitrary
295     and has no value in itselt.
296    
297     The UWSRegExt namepace in the example is declared in the \xmlel{capabilities}
298     element so that it does not have to be repeatedly declared in the
299     \xmlel{interface} elements. However, it is also technically correct for it to
300     be declared at the interface level or in the document root. As best
301     practice we recommend it be declared in the deepest element that contains all
302     the references.
303    
304 major.brian 5005 \subsection{XML Schema}
305    
306 msdemlei 5065 The following is the XML Schema Definition for the UWS Registry
307 major.brian 5116 Extension version 0.1. It can be brought into an XML document's schema
308 msdemlei 5065 as a namespace with the URI
309 major.brian 5116 \xmlel{http://www.ivoa.net/xml/UWSRegExt/v0.1}.
310 major.brian 5005
311 major.brian 5116 \lstinputlisting[language=XML]{UWSRegExt-v0.1.xsd}
312 major.brian 5005
313 major.brian 4969 \appendix
314     \section{Changes from Previous Versions}
315    
316     No previous versions yet.
317     % these would be subsections "Changes from v. WD-..."
318     % Use itemize environments.
319    
320 major.brian 5099 \bibliography{UWSRegExt.bib,ivoatex/ivoabib,ivoatex/docrepo}
321 major.brian 4969
322     \end{document}

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