ViewVC logotype

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 5118 - (show 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 \documentclass[11pt,a4paper]{ivoa}
2 \input tthdefs
4 \usepackage{listings}
5 \lstloadlanguages{XML,SQL}
6 \lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False,
7 basicstyle=\footnotesize}
9 \title{UWS Registry Extension}
11 \ivoagroup{Grid and Web Services}
13 \author{Patrick Dowler}
14 \author{Markus Demleitner}
15 \author{Brian Major}
16 \author{Mark Taylor}
18 \editor{Brian Major}
20 \previousversion{This is the first public release}
22 \begin{document}
23 \begin{abstract}
25 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.
29 \end{abstract}
31 \section*{Conformance-related definitions}
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}.
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.
45 \section{Introduction}
47 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.
52 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.
58 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}.
63 %\subsection{Role within the VO Architecture}
65 %\begin{figure}
66 %\centering
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.
74 %\includegraphics[width=0.9\textwidth]{archdiag.svg}
75 %\caption{Architecture diagram for this document}
76 %\label{fig:archdiag}
77 %\end{figure}
79 %Fig.~\ref{fig:archdiag} shows the role this document plays within the
80 %IVOA architecture \citep{note:VOARCH}.
82 \section{Background} \label{background}
84 \subsection{Motivation}
86 During the review of the TAP 1.1 specification \citep{std:TAP11}, it was
87 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.
91 TAP clients currently follow the recommendations of RegTAP 1.1 to
92 discover TAP access URLs and issue a query like this:
94 \begin{lstlisting}[language=SQL]
95 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 \end{lstlisting}
102 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:
106 \begin{lstlisting}[language=XML]
107 <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 \end{lstlisting}
114 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.
118 Two things have changed since VOResource version 1.03 that make this
119 query to find all TAP services incorrect:
121 \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.
130 Here is an example of the \xmlel{capability} element of the (now
131 obsolete) synchronous endpoint in TAP 1.1:
133 \begin{lstlisting}[language=XML]
134 <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 \end{lstlisting}
141 \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.
153 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:
157 \begin{lstlisting}[language=XML]
158 <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 \end{lstlisting}
169 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}.
173 \subsection{Reaction}
175 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 VOResource 1.1 has ensured that at most one \xmlel{SecurityMethod} is
183 allowed per \xmlel{interface}.
185 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 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 the \xmlel{interface}. To support TAP 1.0 backwards compatibility, a
198 TAP 1.0 style \xmlel{interface} must remain in the \xmlel{capabilities}.
200 \section{UWS Registry Extension} \label{uwsregext}
202 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 These services include TAP \citep{std:TAP11}, VOSpace \citep{std:VOSpace},
206 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 been left to the services to state how the synchronous and asynchronous
210 endpoints are to be discovered through the IVOA registry.
212 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.
218 The UWS Registry Extension introduces two new \xmlel{interface} types:
219 one for synchronous jobs and one for asynchronous jobs. The surrounding
220 \xmlel{interface} element should be marked with the minor version of
221 service specification, as per the recommendations in the XML schema
222 versioning note \citep{2018ivoa.spec.0529H}.
224 \begin{table}
225 \centering
226 \begin{tabular}{| c | c | c |}
227 \hline
228 & Asynchronous & Synchronous \\
229 \hline
230 Interface Type & urx:Async & urx:Sync \\
231 \hline
232 \end{tabular}
233 \caption{UWS Async and Sync interface types}
234 \end{table}
236 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.
241 \subsection{Example TAP 1.1 capability}
243 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.
249 \begin{lstlisting}[language=XML]
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">
257 <capability standardID="ivo://ivoa.net/std/TAP">
259 <!-- TAP 1.0 support -->
260 <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 <accessURL use="base">https://example.com/tap</accessURL>
265 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
266 </interface>
268 <!-- TAP 1.1 support -->
269 <interface
270 xsi:type="urx:Sync" role="std" version="1.1">
271 <accessURL use="base">http://example.com/tap/sync</accessURL>
272 </interface>
273 <interface
274 xsi:type="urx:Sync" role="std" version="1.1">
275 <accessURL use="base">https://example.com/tap/sync</accessURL>
276 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
277 </interface>
278 <interface
279 xsi:type="urx:Async" role="std" version="1.1">
280 <accessURL use="base">http://example.com/tap/async</accessURL>
281 </interface>
282 <interface
283 xsi:type="urx:Async" role="std" version="1.1">
284 <accessURL use="base">https://example.com/tap/async</accessURL>
285 <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
286 </interface>
288 </capability>
290 </vosi:capabilities>
291 \end{lstlisting}
293 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.
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.
304 \subsection{XML Schema}
306 The following is the XML Schema Definition for the UWS Registry
307 Extension version 0.1. It can be brought into an XML document's schema
308 as a namespace with the URI
309 \xmlel{http://www.ivoa.net/xml/UWSRegExt/v0.1}.
311 \lstinputlisting[language=XML]{UWSRegExt-v0.1.xsd}
313 \appendix
314 \section{Changes from Previous Versions}
316 No previous versions yet.
317 % these would be subsections "Changes from v. WD-..."
318 % Use itemize environments.
320 \bibliography{UWSRegExt.bib,ivoatex/ivoabib,ivoatex/docrepo}
322 \end{document}

ViewVC Help
Powered by ViewVC 1.1.26