Commit f4f05986 authored by gmantele's avatar gmantele
Browse files

[TAP] New feature: Examples endpoint. 

Can be enabled just by providing a file URI in the TAP configuration file using
the property "examples". It is also possible to add manually a TAP resource
whose the returned name must be "examples" like the new TAP resource is doing:
tap.resource.Examples. This latter take a file URI as the TAP configuration
file does. The referenced file must respect the DALI 1.0 or TAP Notes 1.0
syntax. No check of the file is performed by the library ; it is up to the
author of the referenced file (a XHTML/RDFa file) to write a correct "examples"
endpoint content. Check out the examples provided on the GitHub repository in
the directory examples/tap/examples_endpoint.
parent d9041712

examples/tap/examples_endpoint/Examples_DALI.class.violet.html

0 → 100644
+2305 −0

File added.

Preview size limit exceeded, changes collapsed.

examples/tap/examples_endpoint/Examples_DALI.png

0 → 100644
+58 KiB
Loading image diff...

examples/tap/examples_endpoint/Examples_TAPNotes.class.violet.html

0 → 100644
+1177 −0

File added.

Preview size limit exceeded, changes collapsed.

examples/tap/examples_endpoint/Examples_TAPNotes.png

0 → 100644
+24.5 KiB
Loading image diff...

examples/tap/examples_endpoint/examples_DALI.html

0 → 100644
+111 −0
Original line number Diff line number Diff line 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN"

    "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd">

<html version="XHTML+RDFa 1.1"

      xmlns="http://www.w3.org/1999/xhtml"

      xml:lang="en" lang="en">

	<head>

		<title>TAP examples - DALI</title>

		<meta name="content-language"

		      content="en" />

		<meta http-equiv="Content-Type"

		      content="application/xhtml+xml; charset=utf-8" />

	</head>

	<body>

		<h1>TAP Examples - DALI</h1>

		

		<p>

			A <code>/examples</code> endpoint is an RDFa document. Basically, it

			is an XHTML document whose some nodes have specific attributes.

			These attributes aim to help client automatic processing. Thus,

			clients like <a href="www.star.bris.ac.uk/~mbt/topcat/">TOPCAT</a>

			are able to retrieve the list of examples that a TAP service

			provides (see <a href="http://www.star.bris.ac.uk/~mbt/topcat/sun253/TapTableLoadDialog_query.html">

			TOPCAT documentation</a> for a more specific illustration).

		</p>

		

		<h2>DALI syntax</h2>

		

		<img src="Examples_DALI.png"

		     alt="UML diagram of the structure expected by DALI." />

		

		<p><em>(see <a href="http://www.ivoa.net/documents/DALI">

		DALI IVOA Recommendation document</a> for more details)</em></p>

		

		<h2>Example</h2>

		

		<p>

			Here is a simple example of a such examples list. This list is

			actually included hidden in this XHTML page ; so, if a client like

			<a href="www.star.bris.ac.uk/~mbt/topcat/">TOPCAT</a> can read this

			document and extract this example.

		</p>

		

		<pre>&lt;div vocab="ivo://ivoa.net/std/DALI-examples"&gt;

	&lt;div id="Example1" resource="#Example1" typeof="example"&gt;

		&lt;h3 property="name"&gt;List all tables&lt;/h3&gt;

		&lt;p property="capability"&gt;ivo://ivoa.net/std/TAP/v1.0&lt;/p&gt;

		&lt;span property="table"&gt;TAP_SCHEMA.tables&lt;/span&gt;

		&lt;div property="generic-parameter" typeof="keyval"&gt;

			&lt;span property="key"&gt;QUERY&lt;/span&gt;

			&lt;pre property="value"&gt;SELECT *

FROM TAP_SCHEMA.tables

WHERE schema_name &lt;&gt; 'TAP_SCHEMA'&lt;/pre&gt;

		&lt;/div&gt;

		&lt;div property="generic-parameter" typeof="keyval"&gt;

			&lt;span property="key"&gt;REQUEST&lt;/span&gt;

			&lt;span property="value"&gt;doQuery&lt;/span&gt;

		&lt;/div&gt;

		&lt;div property="generic-parameter" typeof="keyval"&gt;

			&lt;span property="key"&gt;LANG&lt;/span&gt;

			&lt;span property="value"&gt;ADQL&lt;/span&gt;

		&lt;/div&gt;

	&lt;/div&gt;

&lt;/div&gt;

</pre>



		<p>

			Note that you can set the <code>vocab</code> attribute to any XHTML

			node that can have children, including <code>body</code>.

		</p>

		

		<p>

			You should also note that since the ADQL query is written in an

			XHTML document, any <code>&lt;</code> and <code>&gt;</code> should

			be encoded as the XML entities: <code>&amp;lt;</code> and

			<code>&amp;gt;</code>.

		</p>

		

		<!-- List of examples (note: this list may be the "body" node just by

		     moving the "vocab" attribute to the body node ; warning: only one

		     node with a "vocab" attribute must be found in the whole XHTML

		     document). -->

		<div vocab="ivo://ivoa.net/std/DALI-examples" style="display: none">

			<div id="tablesList" resource="#tablesList" typeof="example">

				<!-- MANDATORY - Name of the example -->

				<h3 property="name">List all tables</h3>

				<!-- OPTIONAL - The targeted IVOA service -->

				<p property="capability">ivo://ivoa.net/std/TAP/v1.0</p>

				<!-- OPTIONAL - Table queried in the example ADQL query -->

				<span property="table">TAP_SCHEMA.tables</span>

				<!-- MANDATORY - ADQL Query -->

				<div property="generic-parameter" typeof="keyval">

					<span property="key">QUERY</span>

					<pre property="value">SELECT *

FROM TAP_SCHEMA.tables

WHERE schema_name &lt;&gt; 'TAP_SCHEMA'</pre>

				</div>

				<!-- 2 TAP mandatory parameters, but we could consider them as

				     optional in the /examples endpoint. -->

				<div property="generic-parameter" typeof="keyval">

					<span property="key">REQUEST</span>

					<span property="value">doQuery</span>

				</div>

				<div property="generic-parameter" typeof="keyval">

					<span property="key">LANG</span>

					<span property="value">ADQL</span>

				</div>

			</div>

		</div>

	</body>

</html>