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

Revision 5064 - (show annotations)
Mon Jun 25 11:14:29 2018 UTC (2 years, 1 month ago) by msdemlei
File MIME type: application/x-tex
File size: 12630 byte(s)
Typography

(mainly, using listings rather than verbatim, as that's likely to be better
supported in ivoatex)


 1 \documentclass[11pt,a4paper]{ivoa} 2 \input tthdefs 3 4 \usepackage{listings} 5 \lstloadlanguages{XML,SQL} 6 \lstset{flexiblecolumns=true,tagstyle=\ttfamily,showstringspaces=False, 7 basicstyle=\footnotesize} 8 9 \title{UWS Registry Extension} 10 11 \ivoagroup{Grid and Web Services} 12 13 \author{Brian Major} 14 \author{Markus Demleitner} 15 \author{Patrick Dowler} 16 \author{Mark Taylor} 17 18 \editor{Brian Major} 19 20 \previousversion{This is the first public release} 21 22 \begin{document} 23 \begin{abstract} 24 25 The Universal Worker Service (UWS) Registry Extension allows for extended metadata to be set on a VOResource \xmlel{interface} for the purpose of tagging UWS job execution access URLs. 26 27 \end{abstract} 28 29 \section*{Conformance-related definitions} 30 31 The words MUST'', SHALL'', SHOULD'', MAY'', RECOMMENDED'', and 32 OPTIONAL'' (in upper or lower case) used in this document are to be 33 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}. 34 35 The \emph{Virtual Observatory (VO)} is a 36 general term for a collection of federated resources that can be used 37 to conduct astronomical research, education, and outreach. 38 The \href{http://www.ivoa.net}{International 39 Virtual Observatory Alliance (IVOA)} is a global 40 collaboration of separately funded projects to develop standards and 41 infrastructure that enable VO applications. 42 43 \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. 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. 48 49 Although the UWS registry extension itself is simple, the history of the need for it is complicated. This history is described in section \ref{background}. The extension itself is described in section \ref{uwsregext}. 50 51 %\subsection{Role within the VO Architecture} 52 53 %\begin{figure} 54 %\centering 55 56 % As of ivoatex 1.2, the architecture diagram is generated by ivoatex in 57 % SVG; copy ivoatex/archdiag-full.xml to archdiag.xml and throw out 58 % all lines not relevant to your standard. 59 % Notes don't generally need this. If you don't copy archdiag.xml, 60 % you must remove archdiag.svg from FIGURES in the Makefile. 61 62 %\includegraphics[width=0.9\textwidth]{archdiag.svg} 63 %\caption{Architecture diagram for this document} 64 %\label{fig:archdiag} 65 %\end{figure} 66 67 %Fig.~\ref{fig:archdiag} shows the role this document plays within the 68 %IVOA architecture \citep{note:VOARCH}. 69 70 \section{Background} \label{background} 71 72 \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. 75 76 TAP clients currently follow the recommendations of RegTAP 1.1 to discover TAP access URLs and issue a query like this: 77 78 \begin{lstlisting}[language=SQL] 79 SELECT ivoid, access_url 80 FROM rr.capability 81 NATURAL JOIN rr.interface 82 WHERE standard_id like 'ivo://ivoa.net/std/tap%' 83 AND intf_type='vs:paramhttp' 84 \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: 87 88 \begin{lstlisting}[language=XML] 89 90 91 http://example.com/tap 92 93 94 \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. 97 98 Two things have changed since VOResource version 1.03 that make this query to find all TAP services incorrect: 99 100 \paragraph{Change \#1. Multiple standard IDs in TAP} TAP 1.1 originally stated that the standard IDs of sync and async are distinct and each are registered. Although this gives services the flexibility to use URLs for sync and async that don't end in precisely /sync and /async, it breaks the pattern of TAP 1.0 service discovery. With the search recommended by RegTAP, clients would find the \xmlel{interfaces} within each of the \xmlel{capabilities} and attempt to append /sync and /async to the endpoints. 101 102 Here is an example of the \xmlel{capability} element of the (now obsolete) synchronous endpoint in TAP 1.1: 103 104 \begin{lstlisting}[language=XML] 105 106 107 http://example.com/tap/sync 108 109 110 \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{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{SecurityMethod}\/s: 115 116 \begin{lstlisting}[language=XML] 117 118 119 http://example.com/tap/sync 120 121 122 https://example.com/tap/sync 123 124 125 126 \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}. 129 130 \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{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}. 135 136 \section{UWS Registry Extension} \label{uwsregext} 137 138 A number of IVOA services have functionality built on the Universal Worker Service. Jobs, which perform service-specific functions, can be created and started in either a synchronous or asynchronous manner. These services include TAP \citep{std:TAP}, VOSpace \citep{std:VOSpace}, and others. It is the UWS specification itself that defines how the lifecycle of these jobs is managed through a RESTful interface, not the services that are built on top of them. However, in the past, it has been left to the services to state how the various UWS endpoints (namely the synchronous and asynchronous job execution endpoints) are to be discovered through the IVOA registry. 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. 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{2018ivoa.spec.0529H}. 143 144 \begin{table} 145 \centering 146 \begin{tabular}{| c | c | c |} 147 \hline 148 & Asynchronous & Synchronous \\ 149 \hline 150 Interface Type & uws:Async & uws:Sync \\ 151 \hline 152 \end{tabular} 153 \caption{UWS Async and Sync interface types} 154 \end{table} 155 156 Future versions of the UWS Registry Extension may allow for more detail to be added about the UWS interfaces. This first version only supplies the two new \xmlel{interface} types so that they can be used by UWS services to \emph{tag} their sync and async endpoints. 157 158 \subsection{Example TAP 1.1 capability} 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. 161 162 \begin{lstlisting}[language=XML] 163 164 165 166 167 168 http://example.com/tap 169 170 171 http://example.com/tap 172 173 174 175 176 177 180 http://example.com/tap/sync 181 182 185 https://example.com/tap/sync 186 187 188 191 http://example.com/tap/async 192 193 196 https://example.com/tap/async 197 198 199 200 201 \end{lstlisting} 202 203 \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}. 206 207 \lstinputlisting[language=XML]{UWSRegExt-v1.0.xsd} 208 209 \appendix 210 \section{Changes from Previous Versions} 211 212 No previous versions yet. 213 % these would be subsections "Changes from v. WD-..." 214 % Use itemize environments. 215 216 \bibliography{ivoatex/ivoabib,ivoatex/docrepo} 217 218 \end{document}