ViewVC logotype

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

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

revision 4969 by major.brian, Fri May 18 23:50:38 2018 UTC revision 5005 by major.brian, Thu May 24 19:12:17 2018 UTC
# Line 1  Line 1 
1  \documentclass[11pt,a4paper]{ivoa}  \documentclass[11pt,a4paper]{ivoa}
2  \input tthdefs  \input tthdefs
4  \title{???? Full title ????}  \usepackage{verbatim}
6  \ivoagroup{???? group ????}  \title{UWS Registry Extension}
8  \author[????URL????]{????Alfred Usher Thor????}  \ivoagroup{Grid and Web Services}
 \author{????Fred Offline????}  
10  \editor{????Alfred Usher Thor????}  \author{Brian Major}
11    \author{Markus Demleitner}
12    \author{Patrick Dowler}
14    \editor{Brian Major}
 % \previousversion[????URL????]{????Funny Label????}  
16  \previousversion{This is the first public release}  \previousversion{This is the first public release}
18  \begin{document}  \begin{document}
19  \begin{abstract}  \begin{abstract}
 ???? Abstract ????  
21  \section*{Acknowledgments}  The Universal Worker Service (UWS) Registry Extension allows for extended metadata to be set on a VOResource \xmlel{interface} for the purpose of discovering UWS job execution access URLs.
23  ???? Or remove the section header ????  \end{abstract}
25  \section*{Conformance-related definitions}  \section*{Conformance-related definitions}
# Line 38  Line 36 
36  collaboration of separately funded projects to develop standards and  collaboration of separately funded projects to develop standards and
37  infrastructure that enable VO applications.  infrastructure that enable VO applications.
39  \section{Introduction}  \section{Introduction}
41  ???? Write something ????  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.
43    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.
45    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}.  
47    \section{Background} \label{background}
49    \subsection{Motivation}
51    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.  
53    TAP clients currently follow the recommendations of RegTAP 1.1 to discover TAP access URLs and issue a query like this:
55    \begin{verbatim}
56    SELECT ivoid, access_url
57        FROM rr.capability
58        NATURAL JOIN rr.interface
59        WHERE standard_id like 'ivo://ivoa.net/std/tap%'
60        AND intf_type='vs:paramhttp'
61    \end{verbatim}
63    This query is sufficient for most of the existing registered TAP services and will return only one result.  Those records typically look like this:
65    \begin{verbatim}
66      <capability standardID="ivo://ivoa.net/std/TAP">
67        <interface xsi:type="vod:ParamHTTP" role="std">
68          <accessURL use="base">http://example.com/tap</accessURL>
69        </interface>
70      </capability>
71    \end{verbatim}
73    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.
75  \subsection{Role within the VO Architecture}  Two things have changed since VOResource version 1.03 that make this query to find all TAP services incorrect:
77  \begin{figure}  \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.
79    Here is an example of the \xmlel{capability} element of the (now obsolete) synchronous endpoint in TAP 1.1:
81    \begin{verbatim}
82      <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
83        <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
84          <accessURL use="base">http://example.com/tap/sync</accessURL>
85        </interface>
86      </capability>
87    \end{verbatim}
89    \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.
91    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}:
93    \begin{verbatim}
94      <capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
95        <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
96          <accessURL use="base">http://example.com/tap/sync</accessURL>
97        </interface>
98        <interface xsi:type="vs:ParamHTTP" role="std" version="1.1">
99          <accessURL use="base">https://example.com/tap/sync</accessURL>
100          <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
101        </interface>
102      </capability>
103    \end{verbatim}
105    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}.
107    \subsection{Solution}
109    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}.
111    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}.
113    \section{UWS Registry Extension} \label{uwsregext}
115    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.
117    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.
119    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})).
121    \begin{table}
122  \centering  \centering
123    \begin{tabular}{| c | c | c |}
124    \hline
125     & Asynchronous & Synchronous \\
126    \hline
127    Interface Type & uws:Async & uws:Sync \\
128    \hline
129    \end{tabular}
130    \caption{UWS Async and Sync interface types}
131    \end{table}
133    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.
135    \subsection{Example TAP 1.1 capability}
137    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.
139    \begin{verbatim}
140      <capability standardID="ivo://ivoa.net/std/TAP">
142        # TAP 1.0 support
143        <capability standardID="ivo://ivoa.net/std/TAP">
144          <interface xsi:type="vod:ParamHTTP" role="std">
145            <accessURL use="base">http://example.com/tap</accessURL>
146          </interface>
147          <interface xsi:type="vod:ParamHTTP" role="std">
148            <accessURL use="base">http://example.com/tap</accessURL>
149            <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
150          </interface>
151        </capability>
153        # TAP 1.1 support
154        <interface
155             xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
156             xsi:type="uws:Sync" role="std" version="1.1">
157          <accessURL use="base">http://example.com/tap/sync</accessURL>
158        </interface>
159        <interface
160             xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
161             xsi:type="uws:Sync" role="std" version="1.1">
162          <accessURL use="base">https://example.com/tap/sync</accessURL>
163          <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
164        </interface>
165        <interface
166             xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
167             xsi:type="uws:Async" role="std" version="1.1">
168          <accessURL use="base">http://example.com/tap/async</accessURL>
169        </interface>
170        <interface
171             xmlns:uws="http://www.ivoa.net/xml/UWSRegExt/v1.0"
172             xsi:type="uws:Async" role="std" version="1.1">
173          <accessURL use="base">https://example.com/tap/async</accessURL>
174          <securityMethod standardID="ivo://ivoa.net/sso#tls-with-certificate"/>
175        </interface>
177      </capability>
178    \end{verbatim}
180  % As of ivoatex 1.2, the architecture diagram is generated by ivoatex in  \subsection{XML Schema}
 % SVG; copy ivoatex/archdiag-full.xml to archdiag.xml and throw out  
 % all lines not relevant to your standard.  
 % Notes don't generally need this.  If you don't copy archdiag.xml,  
 % you must remove archdiag.svg from FIGURES in the Makefile.  
 \caption{Architecture diagram for this document}  
182  Fig.~\ref{fig:archdiag} shows the role this document plays within the  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}.
 IVOA architecture \citep{note:VOARCH}.  
184  ???? and so on, LaTeX as you know and love it. ????  \verbatiminput{UWSRegExt-v1.0.xsd}
186  \appendix  \appendix
187  \section{Changes from Previous Versions}  \section{Changes from Previous Versions}
# Line 71  Line 190 
190  % these would be subsections "Changes from v. WD-..."  % these would be subsections "Changes from v. WD-..."
191  % Use itemize environments.  % Use itemize environments.
193  \bibliography{ivoatex/ivoabib,ivoatex/docrepo}  \bibliography{ivoatex/ivoabib,ivoatex/docrepo}
195  \end{document}  \end{document}

Removed from v.4969  
changed lines
  Added in v.5005

ViewVC Help
Powered by ViewVC 1.1.26