ViewVC logotype

Contents of /trunk/projects/grid/cea/doc/CEAApplicationDM.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 985 - (show annotations)
Mon Apr 20 15:31:06 2009 UTC (11 years, 6 months ago) by harripa
File MIME type: text/plain
File size: 43954 byte(s)
add current (old!) CEA documents
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!-- $Id: CEAApplicationDM.html,v 1.4 2007/05/08 13:01:37 pharriso Exp $ -->
3 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4 <html xmlns="http://www.w3.org/1999/xhtml">
5 <head><title>CEA Application Model (Working Draft)</title>
7 <script src="style/toc.js" language="JavaScript" type="text/javascript" ></script>
9 <link href="style/ivoa_document.css" rel="stylesheet" type="text/css" />
10 <!-- set the class of the body appropriately to change the status of the document -->
11 <link href="style/toc.css" rel="stylesheet" type="text/css" />
12 <link href="style/extra.css" rel="stylesheet" type="text/css" />
13 <link href="schema/viewsource.css" rel="stylesheet" type="text/css" />
14 </head><body bgcolor="white" onload="toc()">
16 <div class="head">
17 <a href="http://www.ivoa.net/"><img alt="IVOA" src="http://www.ivoa.net/pub/images/IVOA_wb_300.jpg" height="169" width="300" /></a>
19 <h1>CEA Application Model: A model of an Application in the Common Application Architecture <br />
20 Version 1.0 </h1>
22 <h2>IVOA Working Draft <!-- #BeginDate format:Sw1 -->27 February, 2008<!-- #EndDate -->
23 </h2>
26 <dl>
27 <dt>This version:</dt>
28 <dd><a href="http://www.ivoa.net/Documents/WD/GWS/CEAApplicationDM-XXXX.html">
29 http://www.ivoa.net/Documents/WD/GWS/CEAApplicationDM-XXXX.html</a></dd>
31 <dt>Latest version:</dt>
32 <dd><a href="http://www.ivoa.net/Documents/latest/CEAApplicationDM.html">
33 http://www.ivoa.net/Documents/latest/CEAApplicationDM.html</a></dd>
35 <dt>Previous versions</dt>
36 </dl>
38 <dl>
39 <dd><a href="http://www.ivoa.net/Documents/WD/ReR/VOResource-20060620.html">
40 </a></dd>
41 <dt>Authors:</dt>
42 <dd>
43 <a href="http://www.ivoa.net/twiki/bin/view/IVOA/PaulHarrison">
44 Paul Harrison</a>, Editor<br />
45 and the IVOA Grid and Web Services Working Group.
46 </dd>
47 </dl>
48 <hr />
49 </div>
51 <h2><a name="abstract" id="abstract">Abstract</a></h2>
53 This document describes the data model for an Application that is used in the Common Execution Architecture (CEA). In addition an XML encoding of this model is presented. The model is expressed by two schema, CEABase-v1.0.xsd which encodes the majority of the metadata and is included in the WSDL interface definition [<a href="#CEAINT">CEAINT</a>] and as a schema VOCEA-v1.0.xsd which defineds a standard for IVOA CEAApplication
54 Metadata which can be used to describe the application in an IVOA interoperable registry.
55 <div class="status">
56 <h2><a name="status" id="status">Status of this document</a></h2>
58 <p>This is an IVOA Working Draft for review by IVOA members and other
59 interested parties. It is a draft document and may be updated,
60 replaced, or obsoleted by other documents at any time. It is
61 inappropriate to use IVOA Working Drafts as reference materials or to
62 cite them as other than "work in progress."</p>
63 <p>Parts that the editor considers should be removed from the document are marked in <span class="draftdelete">red with a strike through line</span>, and parts to be expanded are <span class="draftedit">in green</span></p>
64 <p>
65 Comments on this document are due <span class="draftedit">15 December 2006</span> for consideration in the next version of this
66 document. They should be sent to
67 <a href="mailto:registry@ivoa.net">registry@ivoa.net</a>,
68 a mailing list with a
69 <a href="http://lists.w3.org/Archives/Public/public-webont-comments/">public
70 archive</a> or on the
71 <a href="http://www.ivoa.net/twiki/bin/view/IVOA/RegDMApplications">VOApplication
72 twiki discussion page</a>. General discussion of related technology is
73 also welcome on the
74 <a href="http://www.ivoa.net/twiki/bin/view/IVOA/IVOARegWp03">Rwp03
75 wiki site</a>. </p>
77 <p>
78 A list of <a href="http://www.ivoa.net/Documents/">current IVOA
79 Recommendations and other technical documents</a> can be found at
80 http://www.ivoa.net/Documents/. </p>
81 </div>
82 <h2><a id="acknowledge" name="acknowledge">Acknowledgements</a></h2>
84 <p>This document has been developed with support from the
85 <a href="http://www.pparc.ac.uk/">UK Particle Physics and Astronomy
86 Research Council (PPARC)</a>, and from the
87 <a href="http://fp6.cordis.lu/fp6/home.cfm">Eurpean Commission's Sixth
88 Framework Program</a> via the <a href="http://eurovotech.org/">VOTech project</a>.</p>
90 <a name="conf" id="conf">
91 <h3>Conformance-related definitions</h3></a>
93 The words "MUST", "SHALL", "SHOULD", "MAY", "RECOMMENDED", and
94 "OPTIONAL" (in upper or lower case) used in this document are to be
95 interpreted as described in IETF standard, RFC 2119
96 <a href="#should">[RFC 2119]</a>. <p>
98 The <a name="d:vo" id="d:vo"><strong>Virtual Observatory (VO)</strong></a> is
99 general term for a collection of federated resources that can be used
100 to conduct astronomical research, education, and outreach.
101 <a name="d:ivoa" id="d:ivoa">The</a> <a href="http://www.ivoa.net/"><strong>International
102 Virtual Observatory Alliance (IVOA)</strong></a> is a global
103 collaboration of separately funded projects to develop standards and
104 infrastructure that enable VO applications.</p>
105 <a name="synnot" id="synnot"><h3>Syntax Notation Using XML Schema</h3></a>
107 <p>The eXtensible Markup Language, or XML, is document syntax for marking
108 textual information with named tags and is defined by the
109 World Wide Web Consortium (W3C) Recommendation,
110 <a href="http://www.w3.org/TR/REC-xml">XML 1.0</a>
111 [<a href="#xml">XML</a>]. The set of XML tag names and the syntax
112 rules for their use is referred to as the document schema. One way to
113 formally define a schema for XML documents is using the W3C standard
114 known as XML Schema [<a href="#schema">Schema</a>].</p>
116 <p>
117 This document defines the VOCEA and CEABase schema using XML Schema. The
118 full Schema documents are listed in <a href="#appA">Appendix A</a> and <a href="#appB">Appendix B</a>.
119 Parts of the schema appear within the main sections of this document;
120 however, documentation nodes have been left out for the sake of brevity.
121 </p>
123 <p>
124 Reference to specific elements and types defined in the VOCEA
125 schema include the namespaces prefix, <code>cea</code>, as in
126 <code>cea:CeaApplication</code> (a type defined in the VOCEA schema).
127 Use of the specific <code>cea</code> prefix in compliant instance documents is
128 not required (the actual namespace &quot;http://www.ivoa.net/xml/CEA/v1.0&quot; could be assigned to any prefix); its use in this
129 document is simply to indicate that it is an entity defined in the
130 VOCEA schema. The prefixes for other namespaces are given within the folllowing table </p>
131 <table width="200" border="1">
132 <caption>
133 Namespace prefixes used in this document
134 </caption>
135 <tr>
136 <th scope="col">prefix</th>
137 <th scope="col">namespace</th>
138 </tr>
139 <tr>
140 <td>cea</td>
141 <td>http://www.ivoa.net/xml/CEA/v1.0</td>
142 </tr>
143 <tr>
144 <td>ceab</td>
145 <td>http://www.ivoa.net/xml/CEA/base/v1.0</td>
146 </tr>
147 <tr>
148 <td>vr</td>
149 <td>http://www.ivoa.net/xml/VOResource/v1.0</td>
150 </tr>
151 <tr>
152 <td>vs</td>
153 <td>http://www.ivoa.net/xml/VODataService/v1.0</td>
154 </tr>
155 <tr>
156 <td>va</td>
157 <td>http://www.ivoa.net/xml/VOApplication/v1.0</td>
158 </tr>
159 </table>
160 <p class="draftedit"><span class="draftedit">Note that as this document represents a draft the cea: and ceab: namespaces in attached schema and instance documents have the string &quot;rc&lt;n&gt;&quot; appended where &quot;rc&quot; stands for release candidate and &lt;n&gt; is an integer representing the iteration number of the release candidate draft of the associated namespace. </span>
161 <!-- References to (local) elements are further
162 labelled by enclosing the name in the XML tag brackets, as in
163 <code>&lt;vr:identifier&gt;</code>. -->
164 </p>
165 <div class="contents">
166 <h2><a id="contents" name="contents">Contents</a></h2>
167 <div class="mmhide_toc" id="toc"><div id="toccnt">
168 <ul><ul>
169 <li><a href="#jump1">Introduction</a></li>
170 </ul></ul><ul><ul>
171 <li><a href="#jump13">The VOApplication Data Model</a></li>
172 </ul></ul><ul><ul><ul>
173 <li><a href="#jump17">Core VOApplication Metadata</a></li>
174 </ul></ul></ul><ul><ul>
175 <li><a href="#jump19">Details of the VOApplication Schema </a></li>
177 </ul></ul><ul><ul>
178 <li><a href="#jump25">Appendix A: The complete VOApplication Schema</a></li>
179 </ul></ul><ul><ul>
180 <li><a href="#jump31">Appendix B: Change History</a></li>
181 </ul></ul><ul><ul>
182 <li><a href="#jump35">References</a></li>
183 </ul></ul>
184 </div></div></div>
185 <div id="main">
186 <h2><a name="Intro" id="Intro">Introduction</a></h2>
188 <p>The concept of an abstraction of implementation specific details from the creation of an astronomy specific computing grid was introduced in the IVOA Note &quot;A Proposal for a Common Execution Architecture&quot; [<a href="#CEA">CEA</a>] which described the motivation for and benefits of such an abstraction as well as the concrete schema and web interface definitions that were used by the Astrogrid [AG] implementation of the system at the time. The description of CEA is now split into two parts</p>
189 <ol>
190 <li>The data model for an application, as defined in this document. This model is a general description of what parameters a particular application can accept, and as such it may be regarded as a &quot;language&quot; that is implementation independent to describe at the user-level how the application should be called.</li>
191 <li>A specific web interface (defined in the [CEAIMP] document) for remote invocation of applications that conform to the CEA. The web interface can take a <code>tool</code> XML instance document describing the desired application invocation and actually run the application and return the results in an asynchronous, secure fashion that is consistent with the Universal Worker Pattern ([UWS])</li>
192 </ol>
193 <p>This split between the application model and interface emphasises the fact that the application model could be re-used in other circumstances.</p>
194 <p>The schema that are presented in this document represent an evolution of those presented in [CEA] that incorporates both</p>
195 <ul>
196 <li>Updates to the style and content of the schema to make them consistent with the version 1.0 registry schema model as described in <a href="http://www.ivoa.net/Documents/latest/VOResource.html">VOResource: an XML Encoding Schema for Resource Metadata</a> [<a href="#VR">Plante et al. 2006</a>] (hereafter refered to as the <strong>VR</strong>)</li>
197 <li>Updates to the design of CEA itself as a result of requests for enhanced functionality as a result of the experience gained in writing and operating CEA based services.</li>
198 </ul>
199 <h2><a name="model" id="model">The CEA Application Data Model</a></h2>
200 <p>As presented in [CEA] the basic model for an application is simply a process that can expose a number of &quot;interfaces&quot; which each may have a number of input and output parameters. This means that the UML domain model for the application description is relatively simple as displayed below;</p>
201 <p><img src="images/AppDomain.png" alt="CEA Application domain model" width="309" height="288" /> </p>
202 <p>It is important to realise that the parameter definitions can be reused in multiple interfaces (indicated by the fact that the interfaces are aggregations of parameters) and that the final xml schema representation reflects this by defining all of the parameters for an application first, and then defining the interfaces which contain references to the original parameter definitions. </p>
203 <h3>Design Aims</h3>
204 <p>The main design aims are;</p>
205 <ul>
206 <li>produce a description of an application to allow it to be successfully invoked with the correct parameters, with a degree of validation of the parameters possible before sending to the application. </li>
207 <li>be able to use the description to build a dynamic user interface for specifying the parameters for an application. </li>
208 </ul>
209 <p>In addition the model also needs to be able to specify </p>
210 <ul>
211 <li>parameter types </li>
212 <li>logical groupings of parameters
213 <ul>
214 <li>indicate parameters that have to be given together for semantic reasons</li>
215 <li>indicate parameters that should appear &quot;together&quot; in a user interface. </li>
216 </ul>
217 </li>
218 </ul>
219 <h3>More detail </h3>
220 <p>This diagram does not show the full model that is expressed in the schema, however, a more detailed UML diagram to represent the all of types used in the Application Data model is in <a href="#AppD">Appendix D</a>. The additional complexity that is present in this diagram results from</p>
221 <ul>
222 <li>The ability to specify detail about each parameter definition e.g. default values, ranges etc.. </li>
223 <li>The ability to group and conditionally repeat parameters in an interface. </li>
224 </ul>
225 <h2><a name="ceaBaseDescription" id="ceaBaseDescription"></a>Detailed Description of the CEABase Schema</h2>
226 <p>The two major types within the schema are</p>
227 <ol>
228 <li><span class="element">ApplicationDefinition</span> - This is the description of an application</li>
229 <li><code class="element">Tool</code> - This represents an invocation of an application.</li>
230 </ol>
231 <h3>ApplicationDefinition</h3>
232 <p>The main type that is used to describe an application is the <code>cea:CeaApplication</code> which is derived from <code>va:Application</code>, which in turn is derived from <code>vr:Resource</code>. This means that the start of a such a description would be as below, where the elements possible in the region marked &quot;...&quot; are described in [<a href="#VR">VR</a>] and [<a href="#VA">VA</a>] - the CEA specific part starts with the<code> &lt;applicationDefinition&gt;</code> element. </p>
233 <div class="example">
234 <div class="exampleHeader">Start of the CeaApplication definition</div>
235 <div class="exampleInner">
236 <pre> &lt;Resource xsi:type=&quot;cea:CeaApplication&quot;<br /> created=&quot;2005-09-09T12:28:16&quot; updated=&quot;2005-09-09T12:28:16&quot; status=&quot;active&quot;&gt;<br /> &lt;title&gt;SExtractor&lt;/title&gt;<br /> &lt;shortName&gt;SExtractor&lt;/shortName&gt;<br /> &lt;identifier&gt;ivo://org.astrogrid/SExtractor&lt;/identifier&gt;
237 ...<br /> <br /> &lt;applicationDefinition&gt;</pre>
238 </div>
239 </div>
240 <h4>ApplicationType</h4>
241 <h3>Parameters</h3>
242 <p>The first elemtent of the <span class="element">&lt;applicationDefinition&gt;</span> is the <code>&lt;parameters&gt;</code> element. Parameters are defined once per
243 application, and each parameter is defined with a <code>&lt;parameterDefinition&gt;</code> element which is of type <span class="element">ceab:BaseParameterDefinition</span>, which in turn is derived from vs:BaseParam. This means that the possible attributes and sub-elements of the <code>&lt;parameterDefinition&gt;</code> are listed below. </p>
244 <h4>id attribute </h4>
245 <p>This is the identifier for the parameter - the references to parameters in the interfaces use this value as the parameter identifier. </p>
246 <h4>type attribute </h4>
247 <p>The type of a parameter is CEA is a rather broad concept, with the type ranging from standard atomic types, to aggregate 'types'. The choices were made based on an empirical survey of the most common kinds of parameter that occured in the original target application for CEA namely typical astronomical legacy command-line application. In this sense the types are not intended to be &quot;complete&quot;, but to represent a useful subset of all possible types. </p>
248 <p>It should be noted that the formal type of the parameter value that is passed in the Common Exectution Connector [CEAINT] interface is always an xsd:string - any interpretation of this type information is done at the client or the server, but not by the transport protocol. </p>
249 <p>The choice of what type to declare a parameter is largely a matter of the how much processing or validation of the parameter that the application designer wants the CEA infrastructure to perform - it would be possible to delare just about any parameter as text of binary for instance, which would imply no validation or processing of the value by the CEA client or server. </p>
250 <p class="draftedit">The server side representation of the parameter is determined from the form of the <span class="element">defaultValue</span> element. A concrete example of this is that a boolean value may be represented in many ways on the client as in the table below, but it might be that on the server side that only true/false can be understood, so the defaultValue would be declared 'true'. The server side treatment of parameters is largely implementation dependent, however, the treatment described in this paragraph is that performed by the 'Commandline Common Excecution Controller' [CEAIMP] and as such possibly should be addressed by a separate implementation defined attribute. </p>
251 <table border="1">
252 <tr>
253 <th scope="col">type</th>
254 <th scope="col">Description</th>
255 <th scope="col">String representation </th>
256 </tr>
257 <tr>
258 <td>integer</td>
259 <td>an integer value </td>
260 <td>&nbsp;</td>
261 </tr>
262 <tr>
263 <td><p>real</p> </td>
264 <td>a real value (any precision) </td>
265 <td>&nbsp;</td>
266 </tr>
267 <tr>
268 <td>complex</td>
269 <td>a complex number pair </td>
270 <td>&nbsp;</td>
271 </tr>
272 <tr>
273 <td>text</td>
274 <td>any data that could be interpreted as human readable text in a well known encoding.</td>
275 <td>&nbsp;</td>
276 </tr>
277 <tr>
278 <td>boolean</td>
279 <td>a boolean value </td>
280 <td>0/1 true/false yes/no on /off </td>
281 </tr>
282 <tr>
283 <td>anyURI</td>
284 <td>a string that could be interpreted as a URI. </td>
285 <td>&nbsp;</td>
286 </tr>
287 <tr>
288 <td>VOTable</td>
289 <td>a VOTable conforming to the IVOA specification</td>
290 <td>&nbsp;</td>
291 </tr>
292 <tr>
293 <td class="draftedit">angle</td>
294 <td>Angular measure on the sky</td>
295 <td>sexagesimal allowed</td>
296 </tr>
297 <tr>
298 <td>MJD</td>
299 <td>Modified julian data </td>
300 <td>&nbsp;</td>
301 </tr>
302 <tr>
303 <td>DateTime</td>
304 <td>A date and time in ISO 8601 format</td>
305 <td>&nbsp;</td>
306 </tr>
307 <tr>
308 <td>ADQL</td>
309 <td>Astronomical Query Language</td>
310 <td>&nbsp;</td>
311 </tr>
312 <tr>
313 <td>binary</td>
314 <td>arbitrary </td>
315 <td>&nbsp;</td>
316 </tr>
317 <tr>
318 <td>FITS</td>
319 <td>a file conforming to the [FITS] standard </td>
320 <td>&nbsp;</td>
321 </tr>
322 <tr>
323 <td>xml</td>
324 <td>arbitrary xml </td>
325 <td><p>the schema for the xml is optionally indicated in the UType of the parameter</p>
326 <p>&nbsp; </p></td>
327 </tr>
328 <tr>
329 <td>table</td>
330 <td>some tablular data</td>
331 <td>&nbsp;</td>
332 </tr>
333 <tr>
334 <td>image</td>
335 <td>an astronomical image</td>
336 <td>&nbsp;</td>
337 </tr>
338 <tr>
339 <td>spectrum</td>
340 <td>a spectrum</td>
341 <td>&nbsp;</td>
342 </tr>
343 </table>
344 <p>Future versions of the allowed enumerations for values of this attribute will be influenced by the work of other IVOA standards working groups, particularly in the areas of Semantics, Theory and Applications. </p>
345 <h4>array attribute</h4>
346 <p>If present this attribute specifies that the parameter is an array, and it also defines the shape and size of the array. This definition is essentially the same as for the arraySize attribute in VOTable [<a href="#VOTABLE">VOTABLE</a>], where the first specified dimension changes fastest, and the final dimension can be specified as an asterisk which means unbounded, or an integer followed by an asterisk which means guarenteed to be less than or equal to the attribute.</p>
347 <div class="example">
348 <div class="exampleHeader">example of the array attribute </div>
349 <div class="exampleInner">
350 <pre>
351 </pre>
352 array=&quot;64*10*x&quot; </div>
353 </div>
355 <p class="note">Note that strings (the text type above) do not follow the same conventions as VOTable in that they are not considered as arrays of characters. </p>
356 <h4>name element </h4>
357 <p>This is used to present a name of the parameter in a user interface - This is included because the id attribute of the parameter will often be tied to the name that the underlying application uses, and that name might not be very &quot;human-readable&quot;. </p>
358 <h4>description element </h4>
359 <p>This can be used to present a human-readable description of the purpose and meaning of the parameter. </p>
360 <h4>unit element</h4>
361 <p>The physical unit of the parameter. The actual strings used to denote units follow the same conventions as for the unit attribute of [<a href="#VOTABLE">VOTABLE</a>].</p>
362 <h4>ucd element</h4>
363 <p>A UCD for the parameter if appropriate.</p>
364 <h4>UType element</h4>
365 <p>The UType of the parameter if appropriate.</p>
366 <h4>mimeType element</h4>
367 <p>The mimeType of the parameter if appropriate. </p>
368 <h4>defaultValue element</h4>
369 <p>A default value for the parameter - note that this is simply for presentation to the user interface - in a tool element the value for the parameter should be explicitly given - it is not part of CEA that the parameter description will be reparsed to obtain a default value for a missing parameter. </p>
370 <h4>optionList element</h4>
371 <p>This can be used to specify that a parameter can have only an enumerated list of values. The client is expected to enforce this requirement. </p>
372 <div class="example">
373 <div class="exampleHeader">example of the optionList</div>
374 <div class="exampleInner">
375 <pre>
376 </pre>
377 &lt;optionList&gt;<br />
378 &lt;optionVal&gt;NONE&lt;/optionVal&gt;<br />
379 &lt;optionVal&gt;BLANK&lt;/optionVal&gt;<br />
380 &lt;optionVal&gt;CORRECT&lt;/optionVal&gt;<br />
381 &lt;/optionList&gt;</div>
382 </div>
384 <p>&nbsp;</p>
385 <h4>range element</h4>
386 <p>This element can be used to specify the range of values that a parameter may have</p>
387 <h3>Interfaces</h3>
388 <p>An application needs at least one interface to be callable. Interfaces are identified by their &quot;id&quot; attribute. The 4 possible sub-elements of the &lt;interface&gt; element are </p>
389 <ul>
390 <li>&lt;constants&gt; - parameters that should have a constant value for the interface are defined here by using &lt;pval&gt; elements, which are described <a href="#pval">below</a>. These constants are intended to be supplied by the server side of a CEA application. </li>
391 <li>&lt;input&gt; - the input parameters for the application.</li>
392 <li>&lt;output&gt; - the output parameters for the application. </li>
393 <li>&lt;description&gt; - an optional description of the interface that could be used to present a description in a user interface.</li>
394 </ul>
395 <p>The exact order and grouping of parameters within the input and output sections is made using the pref, pgroup and cgroupHead elements which are described in more detail below </p>
396 <h4>pref</h4>
397 <p>This element is the principal method of making a reference to a parameter definition, and the use is illustrated below. </p>
398 <div class="example">
399 <div class="exampleHeader">A pref element referring to the corresponding parameterDefinition</div>
400 <div class="exampleInner">
401 <pre> ...
402 &lt;parameterDefinition id=&quot;<span class="attribute-value">PHOT_APERTURES</span>&quot;<br /> type=&quot;integer&quot;&gt;<br /> &lt;name&gt;Photometry apertures&lt;/name&gt;<br /> &lt;description&gt;<br /> MAG_APER aperture diameter(s) in pixels<br /> &lt;/description&gt;<br /> &lt;ucd /&gt;<br /> &lt;defaultValue&gt;5&lt;/defaultValue&gt;<br /> &lt;/parameterDefinition&gt;<br /> &lt;/parameters&gt;<br /> &lt;interfaces&gt;<br /> &lt;interfaceDefinition id=&quot;qa&quot;&gt;<br /> &lt;input&gt;<br /> &lt;pref maxOccurs=&quot;1&quot; minOccurs=&quot;1&quot;<br /> ref=&quot;<span class="attribute-value">PHOT_APERTURES</span>&quot; /&gt;
403 ...
404 </pre>
405 </div>
406 </div>
408 <p>&nbsp;</p>
409 <p>The <span class="attribute-name">ref</span> attribute of the <span class="element">pref</span> element must have a value that corresponds to the <span class="attribute-name">id</span> attribute of a <span class="element">&lt;parameterDefinition&gt;</span> to make a valid reference to a parameter in an interface, as illustrated by the blue text in the example above. In addition the <span class="element">&lt;pref&gt; </span>element can have the following attribute</p>
410 <dl>
411 <dt>minOccurs</dt>
412 <dd>The minimum number of times that the parameter should occur in the interface. The default value is 1.</dd>
413 <dt>maxOccurs</dt>
414 <dd>The maximum number of times that the parameter should occur in the interace. A value of 0 is interpreted as the parameter being allowed to be repeated an unbounded number of times. The default value is 1.</dd>
415 <dt>hidden</dt>
416 <dd class="draftedit">If true this is a hint to a client side GUI builder that this parameter should be hidden </dd>
417 </dl>
418 <h4>pgroup</h4>
419 <p>A &lt;pgroup&gt; element can be used to group parameters in the interface. This grouping can be done for two primary reasons.</p>
420 <ol>
421 <li>To specify that a set of parameters should be repeated as a group</li>
422 <li>To give hints to the client side GUI builder that the parameters should be presented to the used in a grouped fashion.</li>
423 </ol>
424 <p>The example below shows that the 'targets' and 'matches' parameters should be repeated as a pairs (if at all, as minOccurs takes the default value of 1). </p>
425 <div class="example">
426 <div class="exampleHeader">The use of pgroup to group parameter references, so that they need to be repeated in pairs. </div>
427 <div class="exampleInner">
428 <pre> &lt;input&gt;<br /> &lt;pgroup maxOccurs=&quot;2&quot;&gt;<br /> &lt;pref ref=&quot;targets&quot; /&gt;<br /> &lt;pref ref=&quot;matches&quot; /&gt;<br /> &lt;/pgroup&gt;<br /> &lt;pgroup&gt;<br /> &lt;pref ref=&quot;matchRadius&quot; /&gt;<br /> &lt;pref ref=&quot;radMax&quot; /&gt;<br /> &lt;/pgroup&gt;</pre>
429 </div>
430 </div>
432 <p>&nbsp;</p>
433 <h4>cgroupHead &amp; cgroup </h4>
434 <p>These constructs allow a set of alternative groups of parameters to be required dependent on the value of another parameter. In the example below different parameters need to be specified depending on the value of the 'output' parameter - if it takes on the value of &quot;html&quot; then a parameter called &quot;htmlversion&quot; will be required, and if it has the value &quot;VOTABLE&quot; a parameter 'votableserialization' will be required. </p>
435 <div class="example">
436 <div class="exampleHeader">The use of a conditional group. </div>
437 <div class="exampleInner">
438 <pre> &lt;cgroupHead ref=&quot;output&quot; &gt;<br /> &lt;cgroup name=&quot;html options&quot;&gt;<br /> &lt;value&gt;html&lt;/value&gt;<br /> &lt;pref ref=&quot;htmlversion&quot; /&gt;<br /> &lt;/cgroup&gt;<br /> &lt;cgroup name=&quot;votable options&quot;&gt;<br /> &lt;value&gt;VOTABLE&lt;/value&gt;<br /> &lt;pref ref=&quot;votableserialization&quot; /&gt;<br /> &lt;/cgroup&gt;<br /> &lt;/cgroupHead&gt;
439 </pre>
440 </div>
441 </div>
443 <h4>&nbsp;</h4>
444 <p>As well as giving instruction to a client side GUI building tool, the cgroupHead and cgroup constructs should also be used by the server side CEA component to do basic validity checking on the parameters that it actually receives.</p>
445 <h3>Tool</h3>
446 <p>The ceab:Tool type represents an invocation of the application, i.e. it specifies which interface to use and supplies values for all of the necessary parameters. This is principally of interest of course when calling an application via the CEA interfaces and is discussed more fully in [<a href="#CEAINT">CEAINT</a>]. An important feature of CEA is that the parameter values that are passed to the server side CEA component are fully specified by this &lt;tool&gt; element, and the description of the application specified by ApplicationDefinition is used by the server side CEA component merely for validation purposes - no parameter value would be changed by the server side CEA component. The application that is to be run is identified by the id attribute and the particular interface by the interface attribute of the tool element.</p>
447 <h4><a name="pval" id="pval"></a>pval</h4>
448 <p>The &lt;pval&gt; element is the principal element that carries parameter values, which are always passed within a &lt;value&gt; element, whether directly or within an &lt;array&gt;. The schema type of the value element is always xs:string.</p>
449 <div class="example">
450 <div class="exampleHeader">A complete tool invocation</div>
451 <div class="exampleInner">
452 <pre>&lt;tool xsi:type=&quot;ceab:Tool&quot; xmlns:ceab=&quot;http://www.ivoa.net/xml/CEA/base/v1.0&quot;<br /> xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;<br /> xsi:schemaLocation=&quot;http://www.ivoa.net/xml/CEA/base/v1.0 ../v11/CEABase.xsd&quot;<br /> id=&quot;ivo://dummy&quot; interface=&quot;test&quot;&gt;<br /> &lt;input&gt;<br /> &lt;pval id=&quot;p1&quot;&gt;<br /> &lt;array&gt;<br /> &lt;value&gt;1&lt;/value&gt;<br /> &lt;value&gt;2&lt;/value&gt;<br /> &lt;/array&gt;<br /> &lt;/pval&gt;<br /> &lt;pval id=&quot;p2&quot;&gt;<br /> &lt;value&gt;hello&lt;/value&gt;<br /> &lt;/pval&gt;<br /> &lt;/input&gt;<br /> &lt;output&gt;<br /> &lt;pval id=&quot;out&quot; indirect=&quot;true&quot;&gt;<br /> &lt;value&gt;vos://org.test!vospace/mydata&lt;/value&gt;<br /> &lt;/pval&gt;<br /> &lt;/output&gt;<br />&lt;/tool&gt;</pre>
453 </div>
454 </div>
456 <p>&nbsp;</p>
457 <p><span class="draftedit">Note on ordering of parameter values</span>. </p>
458 <h2>Generating User Interfaces</h2>
459 <h3>Names and descriptions</h3>
460 <h3>Default Values</h3>
461 <p>Default values where specified for parameter values are intended for client side GUI builders only, and are not substituted by the server side components for missing parameters.</p>
462 <h3>Validity Checking </h3>
463 <p>The client should attempt to perform validity checking on parameters wherever possible, however this is not manadatory as the server must perform validity checking of parameters and will reject requests to run applications with invalid parameter value specifications. </p>
464 <h3>Repeatable parameters </h3>
465 <p>Where a parameter is repeatable (or deletable) the GUI should attempt to inform the user of such a possibility to the user either by using some direct visual form such as an icon next to the parameter input widget, or by enabling or disabling a &quot;repeat parameter&quot; functionality in another GUI element such as a toolbar or pop-up menu when the parameter is selected. </p>
466 <h3>Parameter Groups</h3>
467 <p>One of the intentions of parameter groups is to provide formatting hints to a client producing an automatic user interface. The client should attempt to show this grouping by means of devices such as &quot;tab panes&quot;.</p>
468 <p class="draftedit">needs diagram illustrating typical GUI widgets </p>
469 <h2>Registering CEA Applications and CEA Services</h2>
470 <p>To register CEA Applications and services, types from the VOCEA.xsd schema need to be used. The relationships between the types defined by that schema are illustrated below. The main type that is used to register the description of an application is a <span class="element">CeaApplication</span>, which contains standard <span class="element">Resource</span> metadata, as well as an <span class="element">&lt;applicationDefinition &gt; </span>element which contains the actual CEA application description as detailed in the desciption of the CEABase schema <a href="#ceaBaseDescription">above</a>. A service that can run one or more of CEA Applications is registered with a <span class="element">Service</span> type that has a <span class="element">&lt;capability&gt;</span> element of type <span class="element">CeaCapability</span>. The <span class="element">CeaCapability</span> lists references to the ivoa identifiers of the <span class="element">CeaApplications</span> that particular service can offer, as well as detailing which particular CEA interface can be used. </p>
471 <p>The preceding paragraph describes all of the structures necessary to register CEA applications and services, however there is one convenience type CeaApplicationExtension that can be useful in describing a family of similar applications. The CeaApplicationExtension defines a limited form of application description subclassing, in that it is assumed to inherit all of the parameter and interface definitions of the parent CeaApplication (the one referred to by the extends attribute). It is then allowed to define additional parameters and interfaces, but it should be considered an error if the CeaApplicationExtension tries to redefine an existing parameter. </p>
472 <p><img src="images/VOCEA.png" alt="Class diagram of CEA Registry Types" width="994" height="1102" /></p>
473 <p>There is a fully annotated example of the registration entries for a CEA application and server in <a href="#appC">appendix C</a></p>
474 <h2>Recommendations for Application Description Authors</h2>
475 <h2>Validation</h2>
476 <h4>Optional Parameters or different interfaces? <span class="draftedit">TBC</span> </h4>
477 <h3>Comparision with other &quot;Parameter Models&quot; <span class="draftedit">TBC</span> </h3>
478 <p>There have been a number of other parameter systems implemented in astronomical software systems and it is worthwhile to see the ways in which CEA is different and also the features that CEA has copied to obtain a deeper understanding of the best ways to use the CEA Model.</p>
479 <h4>AIPS</h4>
480 <h4>IRAF ICL</h4>
481 <h4>Starlink ADAM </h4>
482 <ul>
483 <li>CEA does not attempt to define any sort of parameter storage mechanism for presenting the &quot;current&quot; values of parameters in the user interface.</li>
484 <li>The formal (XML) type of the parameter values that is passed is always of type string</li>
485 </ul>
486 <p>&nbsp;</p>
487 <h2>Summary of updates since [CEA]</h2>
488 <p>The following represent updates to the CEA Application model since the publication of the original IVOA Note [<a href="#CEA">CEA</a>].</p>
489 <ul>
490 <li>Schema have been changed to conform with VOResource 1.0 style
491 <ul>
492 <li>new &quot;Capability/Interface&quot; model</li>
493 <li>element capitalization changed</li>
494 <li>local elements are in &quot;null&quot; namespace.</li>
495 </ul>
496 </li>
497 <li>The number of schema files and hence namespaces has been reduced.</li>
498 <li>A number of types have been factored out as &quot;implementation details&quot;, and moved to another schema that does not form part of this specification.</li>
499 <li>Changes to the application model
500 <ul>
501 <li>parameters may be arrays as well as scalar.</li>
502 <li>UType description of parameter. </li>
503 <li>parameter groups
504 <ul>
505 <li>grouped repetition.</li>
506 <li>GUI grouping.</li>
507 <li>possibility of a group being required dependent on value of another parameter. </li>
508 </ul>
509 </li>
510 <li>repeatable output parameters.</li>
511 <li>cea:CeaApplicationExtension.</li>
512 </ul>
513 </li>
514 </ul>
515 <h2><a name="appA" id="appA"></a>Appendix A: The complete CEABase Schema</h2>
516 <p>Note that this schema can be found on-line at <a href="http://www.ivoa.net/xml/CEABase/1.0">http://www.ivoa.net/xml/CEABase/v1.0</a> (i.e. the target namespace can also be used as a URL for the schema.) This location should represent the definitive source, the schema is only copied below for completeness of this document. </p>
517 <div class="schemaOuter">
518 <div class="schemaHeader"><a name="s:VOResource" id="s:VOResource">The Complete CEABase Schema</a></div>
519 <div class="schemaInner">
520 <iframe src="schema/CEABase.xsd" title="CEABase-v1.0.xsd schema" width="100%" height="600">This should be the contents of schema/CEABase-v1.0.xsd</iframe>
521 </div>
522 </div>
523 <h2><a name="appB" id="appB"></a>Appendix B: The complete VOCEA Schema </h2>
524 <p>Note that this schema can be found on-line at <a href="http://www.ivoa.net/xml/VOCEA/1.0">http://www.ivoa.net/xml/VOCEA/v1.0</a> (i.e. the target namespace can also be used as a URL for the schema.) This location should represent the definitive source, the schema is only copied below for completeness of this document. </p>
525 <div class="schemaOuter">
526 <div class="schemaHeader">The Complete VOCEA Schema</div>
527 <div class="schemaInner">
528 <iframe src="schema/VOCEA-v1.0.xsd" title="VOCEA-v1.0.xsd schema" width="100%" height="600">This should be the contents of schema/VOCEA-v1.0.xsd</iframe>
529 </div>
530 </div>
531 <h2><a name="appC" id="appC"></a>Appendix C: An example VOCEA Instance </h2>
532 <div class="schemaOuter">
533 <div class="schemaHeader"><a name="s:VOResource" id="s:VOResource">A VOCEA instance</a></div>
534 <div class="schemaInner">
535 <iframe src="schema/cea.xml" title="cea instance" width="100%" height="600">This should be the contents of schema/cea.xml</iframe>
536 </div>
537 </div>
538 <h2><a name="AppD" id="AppD"></a>Appendix D: Full UML diagram for VOCEA and CEABase schema</h2>
539 <p><img src="images/CEAApplicationFull.png" alt="CEA Application Model Full" width="1320" height="1036" />This diagram presents more detail than the average author of a CEA application definition will need to understand as instance documents typically have a simpler looking structure because of the choice of common element names. It is included as a aid to authors of CEA based service implementations where the detailed relationships could be more important. </p>
540 <ul>
541 <li>The diagram represents the relationships with other IVOA standard schema types, which are displayed in pink.</li>
542 <li>The full lists of possible attribute values are presented. </li>
543 <li>It is representing the types in the XML schema rather than a conceptual model, and the style of schema authoring dictated by [VR] mandates a number of intermediate types that would not be necessary in other styles. </li>
544 </ul>
546 <h2>Appendix : Change History</h2>
547 <p>This is the first version that has been made public - it is derived from IVOA WG wiki content, and the original [<a href="#CEA">CEA</a>] document. </p>
548 <h2><a id="References">References</a></h2>
550 <dl>
551 <dt> <a name="should" id="should">[RFC 2119]</a> </dt>
552 <dd> Bradner, S. 1997. <cite><a href="http://www.ietf.org/rfc/rfc2119.txt">
553 Key words for use in RFCs to Indicate Requirement
554 Levels</a></cite>, IETF RFC 2119,
555 <code>http://www.ietf.org/rfc/rfc2119.txt</code> </dd>
557 <dt> <a name="RM" id="RM">[RM]</a> </dt>
558 <dd> Hanisch, Robert (ed.) 2004. <cite><a href="http://www.ivoa.net/Documents/REC/ResMetadata/RM-20040426.htm"> Resource Metadata for the Virtual Observatory, Version 1.01</a></cite>, IVOA Recommendation, <code>http://www.ivoa.net/Documents/REC/ResMetadata/RM-20040426.htm</code> </dd>
559 <dt> <a name="VR" id="VR">[VR]</a> </dt>
560 <dd> Plante, Ray (ed.) 2006. <a href="http://www.ivoa.net/Documents/latest/VOResource.html">VOResource: an XML Encoding Schema for Resource Metadata</a>, IVOA Working Draft, <code>http://www.ivoa.net/Documents/latest/VOResource.html</code></dd>
561 <dt> <a name="VA" id="VA">[VA]</a> </dt>
562 <dd> Harrison, Paul. (ed.) 2007. <a href="http://www.ivoa.net/Documents/latest/VOApplicationDM.html">VOApplication: an XML Encoding Schema for Application Resource Metadata</a>, IVOA Working Draft, <code>http://www.ivoa.net/Documents/latest/VOApplicationDM.html</code></dd>
563 <dt> <a name="VSTD" id="VSTD">[VSTD]</a> </dt>
564 <dd> Harrison, Paul. (ed.) 2007. <a href="http://www.ivoa.net/Documents/latest/VOStandard.html">VOStandard: an XML Encoding Schema for IVOA Standards</a>, IVOA Working Draft, <code>http://www.ivoa.net/Documents/latest/VOResource.html</code></dd>
565 <dt></dt>
566 <dt> <a name="VOTABLE" id="VOTABLE">[VOTABLE]</a> </dt>
567 <dd> Ochsenbein &amp; Williams. (eds.) 2004. <a href="http://www.ivoa.net/Documents/latest/VOT.html">VOTable Format Definition</a>, version 1.1, <code>http://www.ivoa.net/Documents/latest/VOT.html</code></dd>
568 <dt></dt>
569 <dt></dt>
570 <dt> <a name="UCD" id="UCD">[UCD]</a> </dt>
571 <dd> Derriere et. al. 2004. <a href="http://www.ivoa.net/Documents/latest/UCD.html">An IVOA Standard for Unified Content Descriptors</a>, version 1.10, <code>http://www.ivoa.net/Documents/latest/UCD.html</code></dd>
572 <dt></dt>
573 <dt></dt>
574 <dt>&nbsp; </dt>
575 <dt> <a name="CEA" id="CEA">[CEA]</a> </dt>
576 <dd> Harrison, Paul. 2005. <a href="http://www.ivoa.net/Documents/latest/CEA.html">A Proposal for a Common Execution Architecture </a>, IVOA Working Draft, <code>http://www.ivoa.net/Documents/latest/CEA.html</code></dd>
577 <dt><a name="CEAINT" id="CEAINT">[CEAINT]</a> </dt>
578 <dd> Harrison, Paul. 2007. <a href="http://www.ivoa.net/Documents/latest/CEAInterface.html">CEA Interfaces: How to Invoke Applications in the Common Execution Architecture</a>, IVOA Working Draft, <code>http://www.ivoa.net/Documents/latest/CEAInterface.html</code></dd>
579 <dt></dt>
580 <dt>&nbsp; </dt>
581 <dt> <a name="xml" id="xml">[xml]</a>
582 </dt><dd> Bray, Tim, Paoli, Jean, Sperberg-McQueen, C. M., Maler, Eve,
583 Yergeau, Francois (editors) 2004,
584 <cite><a href="http://www.w3.org/TR/REC-xml">Extensible Markup
585 Language (XML) 1.0 (Third Edition)</a></cite>, W3C
586 /TR/REC-xml</code>
588 </dd>
589 <dt> <a name="schema" id="schema">[schema]</a>
590 </dt><dd> Fallside, David C., Walmsley, Priscilla (editors) 2004,
591 <cite><a href="http://www.w3.org/TR/xmlschema-0/">XML Schema
592 Part 0: Primer Second Edition</a></cite>, W3C Recommendation 28
593 October 2004, <code>http://www.w3.org/TR/xmlschema-0/</code>
595 </dd><dt> <a name="iso8601" id="iso8601">[ISO8601]</a>
596 </dt><dd> Wolf, Misha and Wicksteed, Charles 1997,
597 <cite><a href="http://www.w3.org/TR/NOTE-datetime">Date and
598 Time Format</a></cite>, <code>http://www.w3.org/TR/NOTE-datetime</code>.
600 </dd><dt> <a name="oai" id="oai">[OAI]</a>
601 </dt><dd> Lagoze, Carl, Van de Sompel, Herbert, Nelson, Michael, and
602 Warner, Simeon 2004, <cite>
603 <a href="http://www.openarchives.org/OAI/openarchivesprotocol.html">
604 The Open Archives Initiative Protocol for Metadata Harvesting</a></cite>,
605 <code>http://www.openarchives.org/OAI/openarchivesprotocol.html</code>.
607 </dd>
608 <dt> <a name="ID" id="ID">[ID]</a> </dt>
609 <dd> Plante, R., Linde, T., Williams, R., Noddle, K. 2005, <cite> <a href="http://www.ivoa.net/Documents/REC/Identifiers/Identifiers-200505XX.html"> IVOA Identifiers v1.1</a></cite>, <code>http://www.ivoa.net/Documents/REC/Identifiers/Identifiers-200505XX.html</code>. </dd>
610 <dt></dt>
611 <dt> <a name="FITS" id="FITS">[FITS]</a> </dt>
612 <dd> FITS: Flexible Image Transport Specification, specifically the Binary Tables Extension, <a href="http://fits.gsfc.nasa.gov/">http://fits.gsfc.nasa.gov/</a>. </dd>
613 <dt></dt>
614 <dt> <a name="WSDL" id="WSDL">[WSDL]</a>
615 </dt><dd> Christensen, E., Curbera, F., Meredith, G., Weerawarana, S. <cite>
616 <a href="http://www.w3.org/TR/wsdl">Web Services Description
617 Language (WSDL) 1.1</a></cite>, W3C Note 15 March 2001,
618 <code>http://www.w3.org/TR/wsdl</code>.
620 </dd><dt> <a name="SOAP" id="SOAP">[SOAP]</a>
621 </dt><dd> Box, D., Ehnebuske, D., Kakivaya, G., Layman, A., Mendolsohn,
622 N., Neilsen, H.F., Thatte, S., Winer, D. <cite>
623 <a href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">
624 Simple Object Access Protocol (SOAP) 1.1</a></cite>, W3C Note
625 08 May 2000,
626 <code>http://www.w3.org/TR/2000/NOTE-SOAP-20000508/</code>.
627 </dd></dl>
629 <hr />
630 <font size="-3">
631 <!-- hhmts start -->
632 Last modified:
633 <!-- #BeginDate format:En2m -->27-Feb-2008 11:49<!-- #EndDate -->
634 <!-- hhmts end -->
635 </font>
636 </div>
637 </div>
638 </body>
639 </html>


Name Value
svn:mime-type text/plain

ViewVC Help
Powered by ViewVC 1.1.26