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

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 108 109 http://example.com/tap 110 111 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 135 136 http://example.com/tap/sync 137 138 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 159 160 http://example.com/tap/sync 161 162 163 https://example.com/tap/sync 164 165 166 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 256 257 major.brian 5005 258 259 msdemlei 5064 260 msdemlei 5066 261 http://example.com/tap 262 263 264 major.brian 5099 https://example.com/tap 265 msdemlei 5066 266 267 major.brian 5005 268 msdemlei 5064 269 major.brian 5005 271 major.brian 5005 http://example.com/tap/sync 272 273 275 major.brian 5005 https://example.com/tap/sync 276 277 278 280 major.brian 5005 http://example.com/tap/async 281 282 284 major.brian 5005 https://example.com/tap/async 285 286 287 288 289 major.brian 5116 290 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}