You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by bu...@apache.org on 2012/01/13 14:11:55 UTC
svn commit: r802536 - in
/websites/staging/jena/trunk/content/jena/documentation: notes/sse.html
tdb/optimizer.html tdb/tdb_transactions.html
Author: buildbot
Date: Fri Jan 13 13:11:55 2012
New Revision: 802536
Log:
Staging update by buildbot for jena
Added:
websites/staging/jena/trunk/content/jena/documentation/notes/sse.html
Modified:
websites/staging/jena/trunk/content/jena/documentation/tdb/optimizer.html
websites/staging/jena/trunk/content/jena/documentation/tdb/tdb_transactions.html
Added: websites/staging/jena/trunk/content/jena/documentation/notes/sse.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/notes/sse.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/notes/sse.html Fri Jan 13 13:11:55 2012
@@ -0,0 +1,604 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/jena/css/jena.css" rel="stylesheet" type="text/css">
+ <title>Apache Jena - SPARQL S-Expressions (or "SPARQL Syntax Expressions")</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <script src="/jena/js/jquery-1.6.4.min.js" type="text/javascript"></script>
+ <script src="/jena/js/jena-navigation.js" type="text/javascript"></script>
+</head>
+
+<body>
+ <div id="header">
+ <div id="logoblock">
+ <img alt="Apache Jena" src="/jena/images/jena-logo/jena-logo-small.png"/>
+ </div>
+
+ <div id="titleblock">
+ <h1 class="title">Apache Jena</h1>
+ <div id="topmenu" class="tabbar round-10">
+ <ul>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/index.html" id="home_menu">Home</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/help_and_support/index.html">Support</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/getting_started/index.html">Getting started</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/tutorials/index.html">Tutorials</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/jena/documentation/index.html">Documentation</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div id="navigation" class="clear">
+ <h1 id="quick_links">Quick links</h1>
+<ul>
+<li><a href="/jena/index.html">Home</a></li>
+<li><a href="/jena/download/index.html">Downloads</a></li>
+<li><a href="/jena/help_and_support/index.html">Help and support</a></li>
+<li><a href="/jena/help_and_support/bugs_and_suggestions.html">Report a bug</a></li>
+<li><a href="/jena/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/jena/getting_involved/index.html">Getting involved</a></li>
+<li><a href="/jena/documentation/">Documentation</a></li>
+</ul>
+<h1 id="about_jena">About Jena</h1>
+<ul>
+<li><a href="/jena/index.html">Home</a></li>
+<li><a href="/jena/about_jena/about.html">About Jena</a></li>
+<li><a href="/jena/about_jena/architecture.html">Architecture</a></li>
+<li><a href="/jena/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/jena/about_jena/team.html">Project team</a></li>
+<li><a href="/jena/about_jena/contributions.html">Related projects</a></li>
+</ul>
+<h1 id="download">Download</h1>
+<ul>
+<li><a href="/jena/download/index.html">Downloading Jena</a></li>
+<li><a href="/jena/download/maven.html">Using Maven</a></li>
+<li><a href="/jena/download/osgi.html">Using OSGi</a></li>
+</ul>
+<h1 id="help_and_support">Help and support</h1>
+<ul>
+<li><a href="/jena/help_and_support/index.html">Getting help</a></li>
+<li><a href="/jena/help_and_support/bugs_and_suggestions.html">Bugs and suggestions</a></li>
+</ul>
+<h1 id="getting_started">Getting Started</h1>
+<ul>
+<li><a href="/jena/getting_started/index.html">A first Jena project</a></li>
+<li><a href="/jena/getting_started/rdf_api.html">RDF API overview</a></li>
+<li><a href="/jena/getting_started/sparql.html">Querying RDF with SPARQL</a></li>
+<li><a href="/jena/getting_started/fuseki.html">Serving RDF over HTTP</a></li>
+<li><a href="/jena/getting_started/tell_me_how.html">Tell me how to ...</a></li>
+</ul>
+<h1 id="tutorials">Tutorials</h1>
+<ul>
+<li><a href="/jena/tutorials/index.html">Tutorials index</a></li>
+<li><a href="/jena/tutorials/rdf_api.html">RDF tutorial</a></li>
+<li><a href="/jena/tutorials/sparql.html">SPARQL queries</a></li>
+<li><a href="/jena/tutorials/using_jena_with_eclipse.html">Using Jena with Eclipse</a></li>
+</ul>
+<h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="/jena/documentation/index.html">Overview</a></li>
+<li><a href="/jena/documentation/javadoc">Javadoc</a></li>
+<li><a href="/jena/documentation/rdf/index.html">RDF</a></li>
+<li><a href="/jena/documentation/query/index.html">SPARQL (ARQ)</a><ul>
+<li><a href="/jena/documentation/query/app_api.html">Application API</a></li>
+<li><a href="/jena/documentation/query/cmds.html">Command line utilities</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a><ul>
+<li><a href="/jena/documentation/tdb/tdb_transactions.html">API for Transactions</a></li>
+<li><a href="/jena/documentation/tdb/assembler.html">Dataset Assembler</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a></li>
+<li><a href="/jena/documentation/larq/index.html">LARQ</a></li>
+<li><a href="/jena/documentation/serving_data/index.html">Fuseki: Serving Data</a></li>
+<li><a href="/jena/documentation/ontology/index.html">Ontology</a></li>
+<li><a href="/jena/documentation/inference/index.html">Inference</a></li>
+<li><a href="/jena/documentation/assembler/index.html">Assembler</a><ul>
+<li><a href="/jena/documentation/assembler/assembler-howto.html">Assembler how-to</a></li>
+<li><a href="/jena/documentation/assembler/inside-assemblers.html">Inside assemblers</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/io/index.html">I/O</a><ul>
+<li><a href="/jena/documentation/io/iohowto.html">I/O how-to</a></li>
+<li><a href="/jena/documentation/io/riot.html">RIOT</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/notes/index.html">Notes</a><ul>
+<li><a href="/jena/documentation/notes/concurrency-howto.html">Concurrency how-to</a></li>
+<li><a href="/jena/documentation/notes/event-handler-howto.html">Event handler how-to</a></li>
+<li><a href="/jena/documentation/notes/file-manager.html">File manager how-to</a></li>
+<li><a href="/jena/documentation/notes/model-factory.html">Model factory how-to</a></li>
+<li><a href="/jena/documentation/notes/rdf-frames.html">RDF frames</a></li>
+<li><a href="/jena/documentation/notes/reification.html">Reification how-to</a></li>
+<li><a href="/jena/documentation/notes/typed-literals.html">Typed literals how-to</a></li>
+<li><a href="/jena/documentation/notes/iri.html">Support for IRI's</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/jena/documentation/tools/schemagen.html">schemagen</a></li>
+<li><a href="/jena/documentation/tools/eyeball-getting-started.html">eyeball</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="getting_involved">Getting Involved</h1>
+<ul>
+<li><a href="/jena/getting_involved/index.html">Contributing to Jena</a></li>
+</ul>
+<h1 id="asf_links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+
+ <div id="content">
+ <h1 class="title">SPARQL S-Expressions (or "SPARQL Syntax Expressions")</h1>
+ <p>A way to write down data structures in an RDF-centric syntax.</p>
+<p>But not an idea for another RDF serialization format.</p>
+<h2 id="contents">Contents</h2>
+<ul>
+<li><a href="#Need">1 Need</a></li>
+<li><a href="#Design_Intent">2 Design Intent</a></li>
+<li><a href="#Other_Approaches">3 Other Approaches</a><ul>
+<li><a href="#RDF">3.1 RDF</a></li>
+<li><a href="#Lisp">3.2 Lisp</a></li>
+<li><a href="#XML">3.3 XML</a></li>
+<li><a href="#JSON">3.4 JSON</a></li>
+</ul>
+</li>
+<li>
+<p><a href="#Design">4 Design</a></p>
+<ul>
+<li><a href="#Tokens">4.1 Tokens</a></li>
+<li><a href="#SSE_Comments">4.2 SSE Comments</a></li>
+<li><a href="#SSE_Escapes">4.3 SSE Escapes</a></li>
+<li><a href="#Structures">4.4 Structures</a></li>
+</ul>
+</li>
+<li>
+<p><a href="#Tagged_Structures">5 Tagged Structures</a></p>
+<ul>
+<li><a href="#IRI_resolution">5.1 IRI resolution</a><ul>
+<li><a href="#base">5.1.1 base</a></li>
+<li><a href="#prefix">5.1.2 prefix</a></li>
+<li><a href="#Nesting">5.1.3 Nesting</a></li>
+</ul>
+</li>
+<li>
+<p><a href="#Links">5.2 Links</a></p>
+</li>
+</ul>
+</li>
+<li>
+<p><a href="#Building_Java_Objects">6 Building Java Objects</a></p>
+<ul>
+<li><a href="#SSE_Factory">6.1 SSE Factory</a></li>
+</ul>
+</li>
+<li>
+<p><a href="#Mapping_to_RDF">7 Mapping to RDF</a></p>
+</li>
+<li><a href="#SSE_Files">8 SSE Files</a></li>
+<li><a href="#Longer_Examples">9 Longer Examples</a><ul>
+<li><a href="#Query_1">9.1 Query 1</a></li>
+<li><a href="#Complete_SPARQL_Execution">9.2 Complete SPARQL Execution</a></li>
+</ul>
+</li>
+<li>
+<p><a href="#SSE_Grammar">10 SSE Grammar</a></p>
+</li>
+</ul>
+<h2 id="need">Need</h2>
+<p>The <a href="http://www.w3.org/TR/sparql11-query/#sparqlAlgebra">SPARQL algebra</a>
+defines the semantics of a SPARQL graph pattern. Every SPARQL query
+string (the syntax) is mapped to a SPARQL algebra expression.</p>
+<p>It is convenient to be able to print out such algebra expressions for
+discussion between people and for debugging. Further, if algebra
+expressions can be read back in as well, testing of specific parts of an
+implementation is also easier.</p>
+<p>This is an example of a general problem : how to express data structures
+where the basic elements of RDF are based on RDF nodes.</p>
+<p>RDF itself is often the most appropriate way to do this, but sometimes
+it isn't so convenient. An algebra expression is a tree, and order
+matters.</p>
+<p>When expressing a data structure, there are certain key structure that
+need to be expressible: arrays and maps, then sets and bags, but
+expression of a data structure is not the same as the high-level
+semantics of the data structure.</p>
+<p>A stack can be expressed as a list. And because we want to express the
+structure, and not express the operations on the structures, data
+structures that operational meaning don't enter the picture. There are
+no operations, no <em>push</em>, <em>pop</em> or <em>peek</em>.</p>
+<p>Note that this is to <em>express</em> a data structure, not <em>encode</em> or
+<em>repressent</em> it. By <em>express</em> we mean communicate it, between people or
+between cooperating machines. The structures are not completely
+self-representing. But we do discuss a way to express in RDF that does
+give a self-describing nature through the use of tagged structures.</p>
+<h2 id="design_intent">Design Intent</h2>
+<ul>
+<li>Concise (=> for people to write conveniently) format for data
+ structures</li>
+<li>RDF-centric</li>
+</ul>
+<p>Non-goals:</p>
+<ul>
+<li>to directly represent any data structure.</li>
+<li>to be another RDF syntax.</li>
+</ul>
+<p>So desirable features are:</p>
+<ul>
+<li>Concise syntax for RDF terms</li>
+<li>Datastructures</li>
+</ul>
+<h2 id="other_approaches">Other Approaches</h2>
+<h3 id="rdf">RDF</h3>
+<p>RDF is "map-centric" but not all data structures are conveniently
+expressible in maps. RDF has lists, and these lists have convenient
+syntax in Turtle or N3.</p>
+<p>If your data structure fits the RDF paradigm, then RDF is a better
+choice that SSE. <a href="#Mapping_to_RDF">Below</a> is a possible mapping from SSE
+to RDF as Turtle.</p>
+<h3 id="lisp">Lisp</h3>
+<p>Lacks convenient syntax for the RDF terms themselves.</p>
+<p>SSE syntax is almost valid
+<a href="http://www.schemers.org" title="http://www.schemers.org">Scheme</a>; literal
+language tags and datatypes get split a separate list symbols but the
+information is recoverable. Scheme doesn't use <code>[]</code> lists or
+single-quoted strings.</p>
+<h3 id="xml">XML</h3>
+<p>Too verbose.</p>
+<h3 id="json">JSON</h3>
+<p><a href="http://json.org/" title="http://json.org/">JSON</a> provides values (strings,
+numbers, booleans, null), arrays and object (which are maps). <a href="http://www.w3.org/TR/rdf-sparql-json-res/" title="http://www.w3.org/TR/rdf-sparql-json-res/">SPARQL
+Query Results in
+JSON</a>
+shows how JSON might be used. It describes how RDF terms are encoded
+into further substructures. Alternatively, we could put encoded terms in
+strings like "<http://w3.org/>" and have a parser-within-a-parser. But
+both these approaches do not make the writing of RDF terms as easy as it
+could be.</p>
+<h2 id="design">Design</h2>
+<p><a href="http://en.wikipedia.org/wiki/S-expression" title="http://en.wikipedia.org/wiki/S-expression">S-expressions</a>
+using RDF terms.</p>
+<p>The command <code>arq.qparse --print=op --file queryFile</code> will print the
+SPARQL algebra for the query in SSE format.</p>
+<h3 id="tokens">Tokens</h3>
+<p>Tokens are the atomic elements of the syntax.</p>
+<table>
+<thead>
+<tr>
+<th>Example</th>
+<th>Explaination</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>"abc"</code></td>
+<td>string</td>
+</tr>
+<tr>
+<td><code>"abc"@en</code></td>
+<td>string with language tag.</td>
+</tr>
+<tr>
+<td><code>123</code></td>
+<td>number, specifically an xsd;integer.</td>
+</tr>
+<tr>
+<td><code><http://example.org/></code></td>
+<td>IRI (or URI).</td>
+</tr>
+<tr>
+<td><code>_:abc</code></td>
+<td>blank node.</td>
+</tr>
+<tr>
+<td><code>?x</code></td>
+<td>variable</td>
+</tr>
+<tr>
+<td><code>?</code></td>
+<td>variable</td>
+</tr>
+<tr>
+<td><code>ex:thing</code></td>
+<td>prefixed name</td>
+</tr>
+<tr>
+<td><code>ex:123</code></td>
+<td>prefixed name</td>
+</tr>
+<tr>
+<td><code>SELECT</code></td>
+<td>symbol</td>
+</tr>
+<tr>
+<td><code>+</code></td>
+<td>symbol</td>
+</tr>
+<tr>
+<td><code>@xyz</code></td>
+<td>symbol</td>
+</tr>
+</tbody>
+</table>
+<p>For <code>?</code> (no name), a unique, internal name for a fresh variable will be
+allocated; every use of <code>?</code> is a different variable.</p>
+<p><code>??x</code> creates a non-distinguished variable. <code>??</code> creates a fresh
+non-distinguished variable.</p>
+<p><code>_:</code> creates a fresh blank node.</p>
+<p><code>@xyz</code> - this is a symbol because a language tags only follow a lexical
+form.</p>
+<p>Almost any sequence of characters which is not an RDF term or variable
+is a symbol that can be given special meaning by processing software.</p>
+<h3 id="sse_comments">SSE Comments</h3>
+<p><code>#</code> or <code>;</code> introduce comments, which run to the end of line, including
+the end-of-line characters.</p>
+<h3 id="sse_escapes">SSE Escapes</h3>
+<p><code>\u</code> and <code>\U</code> escape sequences for arbitrary Unicode codepoints. These
+apply to the input character stream before parsing. They don't, for
+example, permit a space in a symbol.</p>
+<p>Strings provide <code>\n</code>, <code>\t</code>, <code>\r</code>, <code>\b</code>, <code>\b</code>, <code>\f</code>, <code>\"</code>, <code>\'</code> and <code>\\</code>
+escape sequences as in SPARQL.</p>
+<h3 id="structures">Structures</h3>
+<p><code>(?x ns:p "abc")</code> - list of 3 elements: a variable, a prefixed name and
+a string</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">bgp</span>
+ <span class="p">[?</span><span class="n">x</span> <span class="n">ns:p</span> <span class="s">"abc"</span><span class="p">])</span>
+</pre></div>
+
+
+<p>A list of 2 elements: a symbol (<code>bgp</code>) and a list of 3 elements. Both
+<code>()</code> and <code>[]</code> delimit lists; they must match but otherwise it's a free
+choice. Convention is that compact lists use <code>[]</code>; large lists use <code>()</code>.</p>
+<h2 id="tagged_structures">Tagged Structures</h2>
+<p>The basic syntax defines tokens and lists. Higher level processing
+happens on this basic syntax and can be extended by interpreting the
+structure.</p>
+<p>Layers on top of the basic abstract syntax produce specialised data
+structures. This can be a transformation into a new SSE structure or the
+production of programming language objects.</p>
+<p>This is driven by tagged (data) objects in an SSE expression. The tag is
+a symbol and the elements of the data object are the rest of the list.</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="o">+</span> <span class="mi">1</span> <span class="mi">2</span><span class="p">)</span>
+</pre></div>
+
+
+<p>is tagged with symbol <code>+</code></p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">triple</span> <span class="p">?</span><span class="n">s</span> <span class="p">?</span><span class="n">p</span> <span class="s">"text"</span><span class="nv">@en</span><span class="p">)</span>
+</pre></div>
+
+
+<p>is tagged with symbol <code>triple</code></p>
+<h3 id="iri_resolution">IRI resolution</h3>
+<p>One such layer is IRI and prefix name resolution, using tags <code>base</code> and
+<code>prefix</code>.</p>
+<p>Basic syntax includes unresolved IRIs, (example <code><abc></code>) and prefixed
+names (example <code>foaf:name</code>). These are turned into absolute IRIs and the
+<code>base</code> and <code>prefix</code> tagged object wrappers are removed.</p>
+<p>This is sufficiently important that the SSE library handles this in an
+optimized fashion where the IRI processing directly rewrites the
+streamed output of the parser.</p>
+<h4 id="base"><code>base</code></h4>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">base</span> <span class="sr"><http://example/></span>
+ <span class="p">(</span><span class="n">triple</span> <span class="sr"><xyz></span> <span class="p">?</span><span class="n">p</span> <span class="s">"lex"</span><span class="o">^^</span><span class="sr"><thing></span><span class="p">))</span>
+</pre></div>
+
+
+<p>becomes</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">triple</span> <span class="sr"><http://example/xyz></span> <span class="p">?</span><span class="n">p</span> <span class="s">"lex"</span><span class="o">^^</span><span class="sr"><http://example/thing></span><span class="p">)</span>
+</pre></div>
+
+
+<h4 id="prefix"><code>prefix</code></h4>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">prefix</span> <span class="p">((:</span> <span class="sr"><http://example/></span><span class="p">)</span>
+ <span class="p">(</span><span class="n">ns:</span> <span class="sr"><http://example/ns#></span><span class="p">))</span>
+ <span class="p">(</span><span class="n">triple</span> <span class="p">:</span><span class="n">x</span> <span class="n">ns:p</span> <span class="s">"lex"</span><span class="o">^^</span><span class="n">ns:type</span><span class="p">))</span>
+</pre></div>
+
+
+<p>becomes</p>
+<div class="codehilite"><pre> <span class="p">(</span><span class="n">triple</span> <span class="sr"><http://example/x></span> <span class="sr"><http://example/ns#p></span> <span class="s">"lex"</span><span class="o">^^</span><span class="sr"><http://example/ns#type></span><span class="p">)</span>
+</pre></div>
+
+
+<h4 id="nesting">Nesting</h4>
+<p>The tagged structures can be combined and nested. The base or prefixes
+declared only apply to the body of the data object.</p>
+<div class="codehilite"><pre> <span class="p">(</span><span class="n">prefix</span> <span class="p">((:</span> <span class="sr"><http://jena.hpl.hp.com/2007/></span><span class="p">)</span>
+ <span class="p">(</span><span class="n">foaf:</span> <span class="sr"><http://xmlns.com/foaf/0.1/></span><span class="p">))</span>
+ <span class="p">(</span><span class="n">triple</span> <span class="p">(</span><span class="n">base</span> <span class="sr"><http://jena.hpl.hp.com/></span> <span class="sr"><afs></span> <span class="n">foaf:name</span> <span class="s">"Andy"</span><span class="p">)))</span>
+</pre></div>
+
+
+<p>Combined with the triple builder, this will produce a triple:</p>
+<div class="codehilite"><pre> <span class="sr"><http://jena.hpl.hp.com/afs></span> <span class="sr"><http://xmlns.com/foaf/0.1/name></span> <span class="s">"Andy"</span> <span class="o">.</span>
+</pre></div>
+
+
+<h3 id="links">Links</h3>
+<p><em>Not implemented</em></p>
+<p>Not all data structures can be conveniently expressed as nested lists.
+Sub-element sharing matters. A structure with shared elements can't be
+serialized as a strict tree and some form of reference is needed.</p>
+<p>Name a place in the structure: <code>(name@ symbol X)</code></p>
+<p>Link to it: <code>(@link symbol)</code></p>
+<p>The link layer will produce an SSE structure without these tags, having
+replaced all <code>name@</code> and <code>@link</code> with the shared structure <em>X</em>.</p>
+<p><em><code>@</code> is a convention for referencing.</em></p>
+<h2 id="building_java_objects">Building Java Objects</h2>
+<p>Builders are code classes that process the structure into Java objects.
+Writing builders is straight-forward because low-level parsing details
+have been taken care of in the basic syntax. A typical builder is a
+recursive-decent parser over the abstract syntax tree, coding one is
+primarily walking the structure, with a tagged object to Java instance
+mapping being applied.</p>
+<p>Some tagged objects with builders are:</p>
+<ul>
+<li><code>(triple S P O)</code> where <em>X</em> is an RDF node (RDF term or variable).</li>
+<li><code>(quad G S P O)</code></li>
+<li><code>(graph triple*)</code></li>
+<li><code>(graph@ URL)</code> â Read a URL.</li>
+</ul>
+<p><em>@@ Need to write the abstract syntax for each tagged object</em></p>
+<p>Many builders have convenience syntax. Triples can be abbreviated by
+omitting the tag <code>triple</code> because usually the fact it is a triple is
+clear.</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">bgp</span> <span class="p">(</span><span class="n">triple</span> <span class="p">?</span><span class="n">s</span> <span class="p">?</span><span class="n">p</span> <span class="p">?</span><span class="n">o</span><span class="p">))</span>
+<span class="p">(</span><span class="n">bgp</span> <span class="p">(?</span><span class="n">s</span> <span class="p">?</span><span class="n">p</span> <span class="p">?</span><span class="n">o</span><span class="p">))</span>
+</pre></div>
+
+
+<p>Quads have a similar abbreviation as 4-lists. In addition, <code>_</code> is a quad
+on the default graph.</p>
+<p>Elements for executing SPARQL:</p>
+<ul>
+<li>SPARQL algebra operators and basic graph patterns</li>
+<li>Filter expressions (in prefix notation <code>(+ 1 2)</code>)</li>
+<li>Query solutions (Bindings) and tables.</li>
+</ul>
+<h3 id="sse_factory">SSE Factory</h3>
+<p>The class <code>SSE</code> in package <code>com.hp.hpl.jena.sparql.sse</code> provides many
+convenience functions to call builders for RDF and SPARQL structures.</p>
+<div class="codehilite"><pre><span class="n">Node</span> <span class="n">n</span> <span class="o">=</span> <span class="n">SSE</span><span class="o">.</span><span class="n">parseNode</span><span class="p">(</span><span class="s">"<http://example/node>"</span><span class="p">)</span> <span class="p">;</span>
+<span class="n">Triple</span> <span class="n">t</span> <span class="o">=</span> <span class="n">SSE</span><span class="o">.</span><span class="n">parseTriple</span><span class="p">(</span><span class="s">"(?s ?p ?o)"</span><span class="p">)</span> <span class="p">;</span>
+<span class="n">Op</span> <span class="n">op</span> <span class="o">=</span> <span class="n">SSE</span><span class="o">.</span><span class="n">parseOp</span><span class="p">(</span><span class="s">"(filter (> ?v 123) (bgp (?s ?p ?v)))"</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>Most of the operations have forms that allow a <code>PrefixMapping</code> to be
+specified - this is wrapped around the parser run so prefixed names can
+be used without explicit prefix declarations.</p>
+<p>There is a default prefix mapping with a few common prefixes: <code>rdf</code>,
+<code>rdfs</code>, <code>owl</code>, <code>xsd</code> and <code>fn</code> (the XPath/XQuery functions and operators
+namespace).</p>
+<h2 id="mapping_to_rdf">Mapping to RDF</h2>
+<p>The syntax of SSE is very close to Turtle lists because the syntax for
+IRIs and literals are the same.: to produce Turtle (outline):</p>
+<ol>
+<li>Replace symbols by IRIs: prepend a common URI and %-encode any
+ characters necesary.</li>
+<li>Replace variables by IRIs: prepend a common URI.</li>
+<li>Move prefixes to be <code>@prefix</code> directives.</li>
+<li>Put a dot at the end of the file.</li>
+</ol>
+<p>The result is an RDF model using only the properties <code>rdf:first</code> and
+<code>rdf:rest</code> so it records the data structure, but not what hthe data
+structure represents.</p>
+<h2 id="sse_files">SSE Files</h2>
+<p>The file extension is <code>.sse</code> and all files are UTF-8.</p>
+<p>A quick and pragmatic Emacs mode is given by:</p>
+<div class="codehilite"><pre><span class="p">;;</span> <span class="o">====</span> <span class="n">SSE</span> <span class="n">mode</span>
+<span class="p">(</span><span class="n">define</span><span class="o">-</span><span class="n">derived</span><span class="o">-</span><span class="n">mode</span> <span class="n">sse</span><span class="o">-</span><span class="n">mode</span> <span class="n">lisp</span><span class="o">-</span><span class="n">mode</span> <span class="s">"SSE"</span> <span class="n">nil</span>
+ <span class="p">(</span><span class="n">make</span><span class="o">-</span><span class="nb">local</span><span class="o">-</span><span class="n">variable</span> <span class="s">'lisp-indent-function)</span>
+<span class="s"> (setq lisp-indent-function '</span><span class="n">sse</span><span class="o">-</span><span class="n">indent</span><span class="o">-</span><span class="n">function</span><span class="p">)</span>
+ <span class="p">)</span>
+
+<span class="p">;;</span> <span class="n">Everything</span> <span class="n">in</span> <span class="n">SSE</span> <span class="n">is</span> <span class="s">"def"</span> <span class="n">like</span>
+<span class="p">(</span><span class="n">defun</span> <span class="n">sse</span><span class="o">-</span><span class="n">indent</span><span class="o">-</span><span class="n">function</span> <span class="p">(</span><span class="n">indent</span><span class="o">-</span><span class="n">point</span> <span class="n">state</span><span class="p">)</span>
+ <span class="p">(</span><span class="n">lisp</span><span class="o">-</span><span class="n">indent</span><span class="o">-</span><span class="n">defform</span> <span class="n">state</span> <span class="n">indent</span><span class="o">-</span><span class="n">point</span><span class="p">))</span>
+
+<span class="p">(</span><span class="n">setq</span> <span class="n">auto</span><span class="o">-</span><span class="n">mode</span><span class="o">-</span><span class="n">alist</span>
+ <span class="p">(</span><span class="n">cons</span> <span class="err">'</span><span class="p">(</span><span class="s">"\\.sse"</span> <span class="o">.</span> <span class="n">sse</span><span class="o">-</span><span class="n">mode</span><span class="p">)</span> <span class="n">auto</span><span class="o">-</span><span class="n">mode</span><span class="o">-</span><span class="n">alist</span><span class="p">))</span>
+</pre></div>
+
+
+<h2 id="longer_examples">Longer Examples</h2>
+<h3 id="query_1">Query 1</h3>
+<div class="codehilite"><pre><span class="n">PREFIX</span> <span class="n">foaf:</span> <span class="sr"><http://xmlns.com/foaf/0.1/></span>
+<span class="n">SELECT</span> <span class="n">DISTINCT</span> <span class="p">?</span><span class="n">name</span> <span class="p">?</span><span class="n">nick</span>
+<span class="p">{</span>
+ <span class="p">?</span><span class="n">x</span> <span class="n">foaf:mbox</span> <span class="sr"><mailt:person@server></span> <span class="o">.</span>
+ <span class="p">?</span><span class="n">x</span> <span class="n">foaf:name</span> <span class="p">?</span><span class="n">name</span>
+ <span class="n">OPTIONAL</span> <span class="p">{</span> <span class="p">?</span><span class="n">x</span> <span class="n">foaf:nick</span> <span class="p">?</span><span class="n">nick</span> <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="p">(</span><span class="n">prefix</span> <span class="p">((</span><span class="n">foaf:</span> <span class="sr"><http://xmlns.com/foaf/0.1/></span><span class="p">))</span>
+ <span class="p">(</span><span class="n">distinct</span>
+ <span class="p">(</span><span class="n">project</span> <span class="p">(?</span><span class="n">name</span> <span class="p">?</span><span class="n">nick</span><span class="p">)</span>
+ <span class="p">(</span><span class="n">leftjoin</span>
+ <span class="p">(</span><span class="n">BGP</span>
+ <span class="p">[</span><span class="n">triple</span> <span class="p">?</span><span class="n">x</span> <span class="n">foaf:mbox</span> <span class="sr"><mailto:person@server></span><span class="p">]</span>
+ <span class="p">[</span><span class="n">triple</span> <span class="p">?</span><span class="n">x</span> <span class="n">foaf:name</span> <span class="p">?</span><span class="n">name</span><span class="p">]</span>
+ <span class="p">)</span>
+ <span class="p">(</span><span class="n">BGP</span> <span class="p">[</span><span class="n">triple</span> <span class="p">?</span><span class="n">x</span> <span class="n">foaf:nick</span> <span class="p">?</span><span class="n">nick</span><span class="p">])</span>
+ <span class="p">))))</span>
+</pre></div>
+
+
+<h3 id="complete_sparql_execution">Complete SPARQL Execution</h3>
+<p>The following is a complete query execution, data and query. There is an
+inline dataset and a query of</p>
+<div class="codehilite"><pre> <span class="n">PREFIX</span> <span class="p">:</span> <span class="sr"><http://example/></span>
+ <span class="n">SELECT</span> <span class="o">*</span>
+ <span class="p">{</span>
+ <span class="n">GRAPH</span> <span class="p">:</span><span class="n">g1</span> <span class="p">{</span> <span class="p">?</span><span class="n">x</span> <span class="p">?</span><span class="n">p</span> <span class="p">?</span><span class="n">v</span> <span class="p">}</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>The tag <code>graph</code> is used twice, with different meanings. First, for an
+RDF graph, and second in <code>GRAPH</code> SPARQL pattern. In a data structrure,
+context sorts out the different usages.</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">prefix</span> <span class="p">((:</span> <span class="sr"><http://example/></span><span class="p">))</span>
+ <span class="p">(</span><span class="nb">exec</span>
+ <span class="p">(</span><span class="n">dataset</span>
+ <span class="p">(</span><span class="n">default</span> <span class="p">(</span><span class="n">graph</span>
+ <span class="p">(:</span><span class="n">x</span> <span class="p">:</span><span class="n">p</span> <span class="mi">1</span><span class="p">)</span>
+ <span class="p">(:</span><span class="n">x</span> <span class="p">:</span><span class="n">p</span> <span class="mi">2</span><span class="p">)))</span>
+ <span class="p">(</span><span class="n">namedgraph</span> <span class="p">:</span><span class="n">g1</span>
+ <span class="p">(</span><span class="n">graph</span>
+ <span class="p">(:</span><span class="n">x</span> <span class="p">:</span><span class="n">gp</span> <span class="mi">1</span><span class="p">)</span>
+ <span class="p">(:</span><span class="n">x</span> <span class="p">:</span><span class="n">gp</span> <span class="mi">2</span><span class="p">)))</span>
+ <span class="p">(</span><span class="n">namedgraph</span> <span class="p">:</span><span class="n">g2</span>
+ <span class="p">(</span><span class="n">graph</span>
+ <span class="p">(:</span><span class="n">y</span> <span class="p">:</span><span class="n">gp</span> <span class="mi">1</span><span class="p">)</span>
+ <span class="p">(:</span><span class="n">y</span> <span class="p">:</span><span class="n">gp</span> <span class="mi">2</span><span class="p">)))</span>
+ <span class="p">)</span>
+
+ <span class="p">(</span><span class="n">graph</span> <span class="p">:</span><span class="n">g1</span>
+ <span class="p">(</span><span class="n">bgp</span> <span class="p">(?</span><span class="n">x</span> <span class="p">?</span><span class="n">p</span> <span class="p">?</span><span class="n">v</span><span class="p">)))</span>
+ <span class="p">))</span>
+</pre></div>
+
+
+<h2 id="sse_grammar">SSE Grammar</h2>
+<p><em>@@ insert grammar here</em></p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2011 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache Jena, Jena, the Apache Jena project logo,
+ Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Modified: websites/staging/jena/trunk/content/jena/documentation/tdb/optimizer.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/tdb/optimizer.html (original)
+++ websites/staging/jena/trunk/content/jena/documentation/tdb/optimizer.html Fri Jan 13 13:11:55 2012
@@ -207,10 +207,28 @@ be appeciated. Mail to
<p>TDB chooses the basic graph pattern optimizer by the presence of a
file in the database directory.</p>
<p>Optimizer control files</p>
-<p>File name | Effect
-<code>none.opt</code> | No reordering - execute triple patterns in the order in the query
-<code>fixed.opt</code> | Use a built-in reordering based on the number of variables in a triple pattern.
-<code>stats.opt</code> | The contents of this file are the weighing rules (see below).</p>
+<table>
+<thead>
+<tr>
+<th>File name</th>
+<th>Effect</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>none.opt</code></td>
+<td>No reordering - execute triple patterns in the order in the query</td>
+</tr>
+<tr>
+<td><code>fixed.opt</code></td>
+<td>Use a built-in reordering based on the number of variables in a triple pattern.</td>
+</tr>
+<tr>
+<td><code>stats.opt</code></td>
+<td>The contents of this file are the weighing rules (see below).</td>
+</tr>
+</tbody>
+</table>
<p>The contents of the files <code>none.opt</code> and <code>fixed.opt</code> are not read
and don't matter. They can be zero-length files.</p>
<p>If more then one file is found, the choice is made: <code>stats.opt</code>
Modified: websites/staging/jena/trunk/content/jena/documentation/tdb/tdb_transactions.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/tdb/tdb_transactions.html (original)
+++ websites/staging/jena/trunk/content/jena/documentation/tdb/tdb_transactions.html Fri Jan 13 13:11:55 2012
@@ -176,8 +176,6 @@ for reverting a database to 0.8.X.</p>
<li><a href="#multi_jvm">Multi JVM</a></li>
<li><a href="#bulk_loading">Bulk loading</a></li>
</ul>
-<h2 id="status">Status</h2>
-<p>Transactions are part of the 0.9.0 release.</p>
<h2 id="overview">Overview</h2>
<p>The transaction mechanism in TDB is based on
<a href="http://en.wikipedia.org/wiki/Write-ahead_logging">write-ahead-logging</a>.
@@ -225,10 +223,10 @@ it should be used transactionally after
<h3 id="read_transactions">Read transactions</h3>
<p>These are used for SPARQL queries and code using the Jena API
actions that do not change the data. The general pattern is:</p>
-<div class="codehilite"><pre><span class="n">dataset</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="o">.</span><span class="n">READ</span><span class="p">)</span> <span class="p">;</span>
-<span class="n">try</span> <span class="p">{</span>
- <span class="o">...</span>
-<span class="p">}</span> <span class="n">finally</span> <span class="p">{</span> <span class="n">dataset</span><span class="o">.</span><span class="n">end</span><span class="p">()</span> <span class="p">;</span> <span class="p">}</span>
+<div class="codehilite"><pre> <span class="n">dataset</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="o">.</span><span class="n">READ</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="o">...</span>
+ <span class="p">}</span> <span class="n">finally</span> <span class="p">{</span> <span class="n">dataset</span><span class="o">.</span><span class="n">end</span><span class="p">()</span> <span class="p">;</span> <span class="p">}</span>
</pre></div>
@@ -259,13 +257,13 @@ actions that do not change the data. Th
actions that modify the data. Beware that large <code>model.read</code>
operations consume large amounts of temporary space.</p>
<p>The general pattern is:</p>
-<div class="codehilite"><pre><span class="n">dataset</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="o">.</span><span class="n">WRITE</span><span class="p">)</span> <span class="p">;</span>
-<span class="n">try</span> <span class="p">{</span>
- <span class="o">...</span>
- <span class="n">dataset</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="p">;</span>
-<span class="p">}</span> <span class="n">finally</span> <span class="p">{</span>
+<div class="codehilite"><pre> <span class="n">dataset</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="o">.</span><span class="n">WRITE</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="o">...</span>
+ <span class="n">dataset</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="p">;</span>
+ <span class="p">}</span> <span class="n">finally</span> <span class="p">{</span>
<span class="n">dataset</span><span class="o">.</span><span class="n">end</span><span class="p">()</span> <span class="p">;</span>
-<span class="p">}</span>
+ <span class="p">}</span>
</pre></div>