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 2011/10/27 02:01:50 UTC
svn commit: r797528 [2/6] -
/websites/staging/jena/trunk/content/jena/documentation/query/
Added: websites/staging/jena/trunk/content/jena/documentation/query/arq-query-eval.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/query/arq-query-eval.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/query/arq-query-eval.html Thu Oct 27 00:01:49 2011
@@ -0,0 +1,631 @@
+<!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 - ARQ - Extending Query Execution</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>
+</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">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></li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a></li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a><ul>
+<li><a href="/jena/documentation/sdb/installation.html">Installation</a></li>
+<li><a href="/jena/documentation/sdb/quickstart.html">Quick start</a></li>
+<li><a href="/jena/documentation/sdb/commands.html">Cmd line</a></li>
+<li><a href="/jena/documentation/sdb/javaapi.html">Java API</a></li>
+<li><a href="/jena/documentation/sdb/configuration.html">Config</a></li>
+<li><a href="/jena/documentation/sdb/databases_supported.html">Databases</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/larq/index.html">LARQ</a></li>
+<li><a href="/jena/documentation/serving_data/index.html">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>
+</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>
+</ul>
+</li>
+<li><a href="/jena/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/jena/documentation/tools/schemagen.html">schemagen</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">ARQ - Extending Query Execution</h1>
+ <p>This page describes the mechanisms that can be used to extend and
+modify query execution within ARQ. Through these mechanisms, ARQ
+can be used to query different graph implementations and to provide
+different query evaluation and optimization strategies for
+particular circumstances. These mechanisms are used by
+<a href="../sdb/">SDB</a> and
+<a href="../tdb">TDB</a>.</p>
+<p>ARQ can be <a href="extension.html">extended in various ways</a> to
+incorporate custom code into a query.
+<a href="extension.html#valueFunctions">Custom filter functions</a> and
+<a href="extension.html#propertyFunctions">property functions</a> provide ways
+to add application specific code. The
+<a href="lucene-arq.html">free text search</a> capabilities, using Apache
+Lucene, are provided via a property function. Custom filter
+functions and property functions should be used where possible.</p>
+<p>Jena itself can be extended by providing a new implementation of
+the <code>Graph</code> interface. This can be used to encapsulate specific
+specialised storage and also for wrapping non-RDF sources to look
+like RDF. There is a common implementation framework provided by
+<code>GraphBase</code> so only one operation, the <code>find</code> method, needs to be
+written for a read-only data source. Basic find works well is many
+cases, and the whole Jena API will be able to use the extension.Â
+For higher SPARQL performance, ARQ can be extended at the
+<a href="#StageGenerator">basic graph matching</a> or
+<a href="#OpExecutor">algebra level</a>.</p>
+<p>Applications writers who extend ARQ at the query execution level
+should be prepared to work with the source code for ARQ for
+specific details and for finding code to reuse. Some example can be
+found in the <code>src-examples</code> directory in the ARQ download.</p>
+<ul>
+<li><a href="#Overview">Overview of ARQ Query Processing</a></li>
+<li><a href="#mainQueryEngine">The Main Query Engine</a></li>
+<li><a href="#StageGenerator">Graph matching and a custom StageGenerator</a></li>
+<li><a href="#OpExecutor">OpExecutor</a></li>
+<li><a href="#quads">Quads</a></li>
+<li><a href="#mixedDatasets">Mixed Graph Implementation Datasets</a></li>
+<li><a href="#CustomQueryEngines">Custom Query Engines</a></li>
+<li><a href="#AlgebraExtensions">Extend the algebra</a></li>
+</ul>
+<h2 id="overview_of_arq_query_processing">Overview of ARQ Query Processing</h2>
+<p>The sequence of actions performed by ARQ to perform a query are
+parsing, algebra generation, execution building, high-level
+optimization, low-level optimization and finally evaluation. It is
+not usual to modify the parsing step nor the conversion from the
+parse tree to the algebra form, which is a fixed algorithm defined
+by the SPARQL standard. Extensions can modify the algebra form by
+transforming it from one algebra expression to another, including
+introducing new operators. See also the documentation on
+<a href="algebra.html">working with the SPARQL algebra in ARQ</a> including
+building algebra expressions programmatically, rather than
+obtaining them from a query string.</p>
+<h3 id="parsing">Parsing</h3>
+<p>The parsing step turns a query string into a <code>Query</code> object. The
+class <code>Query</code> represents the abstract syntax tree (AST) for the
+query and provides methods to create the AST, primarily for use by
+the parser. The query object also provides methods to serialize the
+query to a string. Because this is the AST, the string produced is
+very close to the original query with the same syntactic elements,
+but without comments, and formatted with a whitespace for
+readability. It is not usually the best way to build a query
+programmatically and the AST is not normally an extension point.</p>
+<p>The query object can be used many times. It is not modified once
+created, and in particular it is not modified by query execution.</p>
+<h3 id="algebra_generation">Algebra generation</h3>
+<p>ARQ generates the
+<a href="http://www.w3.org/TR/rdf-sparql-query/#sparqlQuery">SPARQL algebra</a>
+expression for the query. After this a number of transformations
+can be applied (for example, identification of property functions)
+but the first step is the application of the algorithm in the
+SPARQL specification for translating a SPARQL query string, as held
+in a <code>Query</code> object into a SPARQL algebra expression. This includes
+the process of removing joins involving the identity pattern (the
+empty graph pattern).</p>
+<p>For example, the query:</p>
+<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="p">?</span><span class="n">name</span> <span class="p">?</span><span class="n">mbox</span> <span class="p">?</span><span class="n">nick</span>
+<span class="n">WHERE</span> <span class="p">{</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="n">foaf:mbox</span> <span class="p">?</span><span class="n">mbox</span> <span class="o">.</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>
+</pre></div>
+
+
+<p>becomes</p>
+<div class="codehilite"><pre><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">project</span> <span class="p">(?</span><span class="n">name</span> <span class="p">?</span><span class="n">mbox</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:name</span> <span class="p">?</span><span class="n">name</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:mbox</span> <span class="p">?</span><span class="n">mbox</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>
+ <span class="p">)))</span>
+</pre></div>
+
+
+<p>using the <a href="http://openjena.org/wiki/SSE">SSE syntax</a> to write out
+the internal data-structure for the algebra.</p>
+<p>The <a href="http://www.sparql.org/validator.html">online SPARQL validator</a>
+at <a href="http://sparql.org/">sparql.org</a> can be used to see the algebra
+expression for a SPARQL query.</p>
+<h3 id="high-level_optimization_and_transformations">High-Level Optimization and Transformations</h3>
+<p>There is a collection of transformations that can be applied to the
+algebra, such as replacing equality filters with a more efficient
+graph pattern and an assignment. When extending ARQ, a query
+processor for a custom storage layout can choose which
+optimizations are appropriate and can also provide its own algebra
+transformations.</p>
+<p>A transform is code that converts an algebra operation into other
+algebra operations. It is applied using the <code>Transformer</code> class:</p>
+<div class="codehilite"><pre><span class="n">Op</span> <span class="n">op</span> <span class="o">=</span> <span class="o">...</span> <span class="p">;</span>
+<span class="n">Transform</span> <span class="n">someTransform</span> <span class="o">=</span> <span class="o">...</span> <span class="p">;</span>
+<span class="n">op</span> <span class="o">=</span> <span class="n">Transformer</span><span class="o">.</span><span class="n">transform</span><span class="p">(</span><span class="n">someTransform</span><span class="p">,</span> <span class="n">op</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>The <code>Transformer</code> class applies the transform to each operation in
+the algebra expression tree. <code>Transform</code> itself is an interface,
+with one method signature for each operation type, returning a
+replacement for the operator instance it is called on.</p>
+<p>One such transformation is to turn a SPARQL algebra expression
+involving named graphs and triples into one using quads. This
+transformation is performed by a call to <code>Algebra.toQuadForm</code>.</p>
+<p>Transformations proceed from the bottom of the expression tree to
+the top. Algebra expressions are best treated as immutable so a
+change made in one part of the tree should result in a copy of the
+tree above it. This is automated by the <code>TransformCopy</code> class
+which is the commonly used base class for writing transforms. The
+other helper base class is <code>TransformBase,</code> which provides the
+identify operation (returns the node supplied) for each transform
+operation.</p>
+<p>Operations can be printed out in
+<a href="http://openjena.org/wiki/SSE">SSE</a> syntax. The Java <code>toString</code>
+method is overridden to provide pretty printing and the static
+methods in <code>WriterOp</code> provide output to various output objects like
+<code>java.io.OutputStream</code>.</p>
+<h3 id="low-level_optimization_and_evaluation">Low-Level Optimization and Evaluation</h3>
+<p>The step of evaluating a query is the process of executing the
+algebra expression, as modified by any transformations applied, to
+yield a stream of pattern solutions. Low-level optimizations
+include choosing the order in which to evaluate basic graph
+patterns. These are the responsibility of the custom storage layer.
+Low-level optimization can be carried out dynamically as part of
+evaluation.</p>
+<p>Internally, ARQ uses iterators extensively. Where possible,
+evaluation of an operation is achieved by feeding the stream of
+results from the previous stage into the evaluation. A common
+pattern is to take each intermediate result one at a time (use
+<code>QueryIterRepeatApply</code> to be called for each binding) ,
+substituting the variables of pattern with those in the incoming
+binding, and evaluating to a query iterator of all results for this
+incoming row. The result can be the empty iterator (one that always
+returns false for <code>hasNext</code>). It is also common to not have to
+touch the incoming stream at all but merely to pass it to
+sub-operations.</p>
+<h3 id="query_engines_and_query_engine_factories">Query Engines and Query Engine Factories</h3>
+<p>The steps from algebra generation to query evaluation are carried
+out when a query is executed via the <code>QueryExecution.execSelect</code> or
+other <code>QueryExecution</code> exec operation. It is possible to carry out
+storage-specific operations when the query execution is created. A
+query engine works in conjunction with a <code>QueryExecution</code> created
+by the <code>QueryExecutionFactory</code> to provide the evaluation of a query
+pattern. <code>QueryExecutionBase</code> provides all the machinery for the
+different result types and does not need to be modified by
+extensions to query execution.</p>
+<p>ARQ provides three query engine factories; the main query engine
+factory, one for a reference query engine and one to remotely
+execute a query. SDB and TDB provide their own query engine
+factories which they register during sub-system initialization.
+Both extend the main query engine described below.</p>
+<p>The reference query engine is a direct top-down evaluation of the
+expression. It's purpose is to be simple so it can be easily
+verified and checked then its results used to check more
+complicated processing in the main engine and other
+implementations. All arguments to each operator are fully evaluated
+to produce intermediate in-memory tables then a simple
+implementation of the operator is called to calculate the results.
+It does not scale and does not perform any optimizations. It is
+intended to be clear and simple; it is not designed to be
+efficient.</p>
+<p>Query engines are chosen by referring to the registry of query
+engine factories.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">interface</span> <span class="n">QueryEngineFactory</span>
+<span class="p">{</span>
+ <span class="n">public</span> <span class="n">boolean</span> <span class="nb">accept</span><span class="p">(</span><span class="n">Query</span> <span class="n">query</span><span class="p">,</span> <span class="n">DatasetGraph</span> <span class="n">dataset</span><span class="p">,</span> <span class="n">Context</span> <span class="n">context</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">public</span> <span class="n">Plan</span> <span class="n">create</span><span class="p">(</span><span class="n">Query</span> <span class="n">query</span><span class="p">,</span> <span class="n">DatasetGraph</span> <span class="n">dataset</span><span class="p">,</span> <span class="n">Binding</span> <span class="n">inputBinding</span><span class="p">,</span> <span class="n">Context</span> <span class="n">context</span><span class="p">)</span> <span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">boolean</span> <span class="nb">accept</span><span class="p">(</span><span class="n">Op</span> <span class="n">op</span><span class="p">,</span> <span class="n">DatasetGraph</span> <span class="n">dataset</span><span class="p">,</span> <span class="n">Context</span> <span class="n">context</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">public</span> <span class="n">Plan</span> <span class="n">create</span><span class="p">(</span><span class="n">Op</span> <span class="n">op</span><span class="p">,</span> <span class="n">DatasetGraph</span> <span class="n">dataset</span><span class="p">,</span> <span class="n">Binding</span> <span class="n">inputBinding</span><span class="p">,</span> <span class="n">Context</span> <span class="n">context</span><span class="p">)</span> <span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>When the query execution factory is given a dataset and query, the
+query execution factory tries each registered engine factory in
+turn calling the <code>accept</code> method (for query of algebra depending on
+how it was presented). The registry is kept in reverse registration
+order - the most recently registered query engine factory is tried
+first. The first query engine factor to return true is chosen and
+no further engine factories are checked.</p>
+<p>When a query engine factory is chosen, the <code>create</code> method is
+called to return a <code>Plan</code> object for the execution. The main
+operation of the plan interface is to get the <code>QueryIterator</code> for
+the query.</p>
+<p>See the example in
+<code>src-examples/arq.examples.engine.MyQueryEngine</code>.</p>
+<h2 id="the_main_query_engine">The Main Query Engine</h2>
+<p>The main query engine can execute any query. It contains a number
+of basic graph pattern matching implementations including one that
+uses the <code>Graph.find</code> operation so it can work with any
+implementation of the Jena Graph SPI. The main query engine works
+with general purpose datasets but not quad stores directly; it
+evaluates patterns on each graph in turn. The main query engine
+includes optimizations for the standard Jena implementation of
+in-memory graphs.</p>
+<p>High-level optimization is performed by a sequence of
+transformations. This set of optimizations is evolving. A custom
+implementation of a query engine can reuse some or all of these
+transformations (see <code>Algebra.optimize</code> which is the set of
+transforms used by the main query engine).</p>
+<p>The main query engine is a streaming engine. It evaluates
+expressions as the client consumes each query solution. After
+preparing the execution by creating the initial conditions (a
+partial solution of one row and no bound variables or any initial
+bindings of variables), the main query engine calls <code>QC.execute</code>
+which is the algorithm to execute a query. Any extension that
+wished to reuse some of the main query engine by providing it's own
+<code>OpExecutor</code> must call this method to evaluate a sub-operation.</p>
+<p><code>QC.execute</code> finds the currently active <code>OpExecutor</code> factory,
+creates an <code>OpExecutor</code> object and invokes it to evaluate one
+algebra operation.</p>
+<p>There are two points of extension for the main query engine:</p>
+<ul>
+<li>Stage generators, for evaluating basic graph patterns and
+ reusing the rest of the engine.</li>
+<li><code>OpExecutor</code> to execute any algebra operator specially.</li>
+</ul>
+<p>The standard <code>OpExecutor</code> invokes the stage generator mechanism to
+match a basic graph pattern.</p>
+<h2 id="graph_matching_and_a_custom_stagegenerator">Graph matching and a custom StageGenerator</h2>
+<p>The correct point to hook into ARQ for just extending basic graph
+pattern matching (BGPs) is to provide a custom <code>StageGenerator</code>.Â
+(To hook into filtered basic graph patterns, the extension will
+need to provide it's own <code>OpExecutor</code> factory). The advantage of
+the <code>StageGenerator</code> mechanism, as compared to the more general
+<code>OpExecutor</code> described below, is that it more self-contained and
+requires less detail about the internal evaluation of the other
+SPARQL algebra operators. This extension point corresponds to
+section 12.6
+"<a href="http://www.w3.org/TR/rdf-sparql-query/#sparqlBGPExtend">Extending SPARQL Basic Graph Matching</a>".</p>
+<p>Below is the default code to match a BGP from
+<code>OpExecutor.execute(OpBGP, QueryIterator)</code>. It merely calls fixed
+code in the <code>StageBuilder</code> class.The input is a stream of results
+from earlier stages. The execution must return a query iterator
+that is all the possible ways to match the basic graph pattern for
+each of the inputs in turn. Order of results does not matter. </p>
+<div class="codehilite"><pre><span class="n">protected</span> <span class="n">QueryIterator</span> <span class="n">execute</span><span class="p">(</span><span class="n">OpBGP</span> <span class="n">opBGP</span><span class="p">,</span> <span class="n">QueryIterator</span> <span class="n">input</span><span class="p">)</span>
+<span class="p">{</span>
+ <span class="n">BasicPattern</span> <span class="n">pattern</span> <span class="o">=</span> <span class="n">opBGP</span><span class="o">.</span><span class="n">getPattern</span><span class="p">()</span> <span class="p">;</span>
+ <span class="k">return</span> <span class="n">StageBuilder</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">pattern</span><span class="p">,</span> <span class="n">input</span><span class="p">,</span> <span class="n">execCxt</span><span class="p">)</span> <span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The <code>StageBuilder</code> looks for the stage generator by accessing the
+context for the execution:</p>
+<div class="codehilite"><pre><span class="n">StageGenerator</span> <span class="n">stageGenerator</span> <span class="o">=</span> <span class="p">(</span><span class="n">StageGenerator</span><span class="p">)</span><span class="n">context</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">ARQ</span><span class="o">.</span><span class="n">stageGenerator</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>where the context is the global context and any query execution
+specific additions together with various execution control
+elements.</p>
+<p>A <code>StageGenerator</code> is an implementation of:</p>
+<div class="codehilite"><pre> <span class="n">public</span> <span class="n">interface</span> <span class="n">StageGenerator</span>
+ <span class="p">{</span>
+ <span class="n">public</span> <span class="n">QueryIterator</span> <span class="n">execute</span><span class="p">(</span><span class="n">BasicPattern</span> <span class="n">pattern</span><span class="p">,</span>
+ <span class="n">QueryIterator</span> <span class="n">input</span><span class="p">,</span>
+ <span class="n">ExecutionContext</span> <span class="n">execCxt</span><span class="p">)</span> <span class="p">;</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<h3 id="setting_the_stage_generator">Setting the Stage Generator</h3>
+<p>An extension stage generator can be registered on a per-query
+execution basis or (more usually) in the global context.</p>
+<div class="codehilite"><pre> <span class="n">StageBuilder</span><span class="o">.</span><span class="n">setGenerator</span><span class="p">(</span><span class="n">Context</span><span class="p">,</span> <span class="n">StageGenerator</span><span class="p">)</span>
+</pre></div>
+
+
+<p>The global context can be obtained by a call to <code>ARQ.getContext()</code></p>
+<div class="codehilite"><pre> <span class="n">StageBuilder</span><span class="o">.</span><span class="n">setGenerator</span><span class="p">(</span><span class="n">ARQ</span><span class="o">.</span><span class="n">getContext</span><span class="p">(),</span> <span class="n">myStageGenerator</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>In order to allow an extensions to still permit other graphs to be
+used, stage generators are usually chained, with each new custom
+one passing the execution request up the chain if the request is
+not supported by this custom stage generator.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">MyStageGenerator</span> <span class="n">implements</span> <span class="n">StageGenerator</span>
+<span class="p">{</span>
+ <span class="n">StageGenerator</span> <span class="n">above</span> <span class="o">=</span> <span class="n">null</span> <span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">MyStageGenerator</span> <span class="p">(</span><span class="n">StageGenerator</span> <span class="n">original</span><span class="p">)</span>
+ <span class="p">{</span> <span class="n">above</span> <span class="o">=</span> <span class="n">original</span> <span class="p">;</span> <span class="p">}</span>
+
+ <span class="nv">@Override</span>
+ <span class="n">public</span> <span class="n">QueryIterator</span> <span class="n">execute</span><span class="p">(</span><span class="n">BasicPattern</span> <span class="n">pattern</span><span class="p">,</span> <span class="n">QueryIterator</span> <span class="n">input</span><span class="p">,</span> <span class="n">ExecutionContext</span> <span class="n">execCxt</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">Graph</span> <span class="n">g</span> <span class="o">=</span> <span class="n">execCxt</span><span class="o">.</span><span class="n">getActiveGraph</span><span class="p">()</span> <span class="p">;</span>
+ <span class="sr">//</span> <span class="n">Test</span> <span class="n">to</span> <span class="n">see</span> <span class="k">if</span> <span class="n">this</span> <span class="n">is</span> <span class="n">a</span> <span class="n">graph</span> <span class="n">we</span> <span class="n">support</span><span class="o">.</span>
+ <span class="k">if</span> <span class="p">(</span> <span class="o">!</span> <span class="p">(</span> <span class="n">g</span> <span class="n">instanceof</span> <span class="n">MySpecialGraphClass</span> <span class="p">)</span> <span class="p">)</span>
+ <span class="sr">//</span> <span class="n">Not</span> <span class="n">us</span> <span class="o">-</span> <span class="n">bounce</span> <span class="n">up</span> <span class="n">the</span> <span class="n">StageGenerator</span> <span class="n">chain</span>
+ <span class="k">return</span> <span class="n">above</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">pattern</span><span class="p">,</span> <span class="n">input</span><span class="p">,</span> <span class="n">execCxt</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">MySpecialGraphClass</span> <span class="n">graph</span> <span class="o">=</span> <span class="p">(</span><span class="n">MySpecialGraphClass</span> <span class="p">)</span><span class="n">g</span> <span class="p">;</span>
+ <span class="sr">//</span> <span class="n">Create</span> <span class="n">a</span> <span class="n">QueryIterator</span> <span class="k">for</span> <span class="n">this</span> <span class="n">request</span>
+ <span class="o">...</span>
+</pre></div>
+
+
+<p>This is registered by setting the global context (<code>StageBuilder</code>
+has a convenience operation to do this):</p>
+<div class="codehilite"><pre> <span class="sr">//</span> <span class="n">Get</span> <span class="n">the</span> <span class="n">standard</span> <span class="n">one</span><span class="o">.</span>
+ <span class="n">StageGenerator</span> <span class="n">orig</span> <span class="o">=</span> <span class="p">(</span><span class="n">StageGenerator</span><span class="p">)</span><span class="n">ARQ</span><span class="o">.</span><span class="n">getContext</span><span class="p">()</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">ARQ</span><span class="o">.</span><span class="n">stageGenerator</span><span class="p">)</span> <span class="p">;</span>
+ <span class="sr">//</span> <span class="n">Create</span> <span class="n">a</span> <span class="k">new</span> <span class="n">one</span>
+ <span class="n">StageGenerator</span> <span class="n">myStageGenerator</span><span class="o">=</span> <span class="k">new</span> <span class="n">MyStageGenerator</span><span class="p">(</span><span class="n">orig</span><span class="p">)</span> <span class="p">;</span>
+ <span class="sr">//</span> <span class="n">Register</span> <span class="n">it</span>
+ <span class="n">StageBuilder</span><span class="o">.</span><span class="n">setGenerator</span><span class="p">(</span><span class="n">ARQ</span><span class="o">.</span><span class="n">getContext</span><span class="p">(),</span> <span class="n">myStageGenerator</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>Example: <code>src-examples/arq.examples.bgpmatching</code>.</p>
+<h2 id="opexecutor">OpExecutor</h2>
+<p>A <code>StageGenerator</code> provides matching for a basic graph pattern. If
+an extension wishes to take responsibility for more of the
+evaluation then it needs to work with <code>OpExecutor</code>. This includes
+evaluation of filtered basic graph patterns.</p>
+<p>An example query using a filter:</p>
+<div class="codehilite"><pre><span class="n">PREFIX</span> <span class="n">dc:</span> <span class="sr"><http://purl.org/dc/elements/1.1/></span>
+<span class="n">PREFIX</span> <span class="n">books:</span> <span class="sr"><http://example.org/book/></span>
+
+<span class="n">SELECT</span> <span class="o">*</span>
+<span class="n">WHERE</span>
+ <span class="p">{</span> <span class="p">?</span><span class="n">book</span> <span class="n">dc:title</span> <span class="p">?</span><span class="n">title</span> <span class="o">.</span>
+ <span class="n">FILTER</span> <span class="n">regex</span><span class="p">(?</span><span class="n">title</span><span class="p">,</span> <span class="s">"Paddington"</span><span class="p">)</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>results in the algebra expression for the pattern:</p>
+<div class="codehilite"><pre> <span class="p">(</span><span class="n">filter</span> <span class="p">(</span><span class="n">regex</span> <span class="p">?</span><span class="n">title</span> <span class="s">"Paddington"</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">book</span> <span class="n">dc:title</span> <span class="p">?</span><span class="n">title</span><span class="p">)</span>
+ <span class="p">))</span>
+</pre></div>
+
+
+<p>showing that the filter is being applied to the results of a basic
+graph pattern matching.</p>
+<p>Note: this is not the way to provide custom filter operations. See
+the documentation for
+<a href="extension.html#valueFunctions">application-provided filter functions</a>.</p>
+<p>Each step of evaluation in the main query engine is performed by a
+<code>OpExecutor</code> and a new one is created from a factory at each step.Â
+The factory is registered in the execution context. The
+implementation of a specialized <code>OpExecutor</code> can inherit from the
+standard one and override only those algebra operators it wishes to
+deal with, including inspecting the execution and choosing to
+passing up to the super-class based on the details of the
+operation. From the query above, only regex filters might be
+specially handled.</p>
+<p>Registering an <code>OpExecutorFactory</code>:</p>
+<div class="codehilite"><pre><span class="n">OpExecutorFactory</span> <span class="n">customExecutorFactory</span> <span class="o">=</span> <span class="k">new</span> <span class="n">MyOpExecutorFactory</span><span class="p">(</span><span class="o">...</span><span class="p">)</span> <span class="p">;</span>
+<span class="n">QC</span><span class="o">.</span><span class="n">setFactory</span><span class="p">(</span><span class="n">ARQ</span><span class="o">.</span><span class="n">getCOntext</span><span class="p">(),</span> <span class="n">customExecutorFactory</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>QC is a point of indirection that chooses the execution process at
+each stage in a query so if the custom execution wishes to evaluate
+an algebra operation within another operation, it shoudl call
+<code>QC.execute</code>. Be careful not to loop endlessly if the operation is
+itself handled by the custom evaluator. This can be done by
+swapping in a different <code>OpExecutorFactory</code>.</p>
+<div class="codehilite"><pre> <span class="sr">//</span> <span class="n">Execute</span> <span class="n">an</span> <span class="n">operation</span> <span class="n">with</span> <span class="n">a</span> <span class="n">different</span> <span class="n">OpExecution</span> <span class="n">Factory</span>
+
+ <span class="sr">//</span> <span class="n">New</span> <span class="n">context</span><span class="o">.</span>
+ <span class="n">ExecutionContext</span> <span class="n">ec2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ExecutionContext</span><span class="p">(</span><span class="n">execCxt</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">ec2</span><span class="o">.</span><span class="n">setExecutor</span><span class="p">(</span><span class="n">plainFactory</span><span class="p">)</span> <span class="p">;</span>
+
+ <span class="n">QueryIterator</span> <span class="n">qIter</span> <span class="o">=</span> <span class="n">QC</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">op</span><span class="p">,</span> <span class="n">input</span><span class="p">,</span> <span class="n">ec2</span><span class="p">)</span> <span class="p">;</span>
+
+ <span class="n">private</span> <span class="n">static</span> <span class="n">OpExecutorFactory</span> <span class="n">plainFactory</span> <span class="o">=</span>
+ <span class="k">new</span> <span class="n">OpExecutorFactory</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="nv">@Override</span>
+ <span class="n">public</span> <span class="n">OpExecutor</span> <span class="n">create</span><span class="p">(</span><span class="n">ExecutionContext</span> <span class="n">execCxt</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">The</span> <span class="n">default</span> <span class="n">OpExecutor</span> <span class="n">of</span> <span class="n">ARQ</span><span class="o">.</span>
+ <span class="k">return</span> <span class="k">new</span> <span class="n">OpExecutor</span><span class="p">(</span><span class="n">execCxt</span><span class="p">)</span> <span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">}</span> <span class="p">;</span>
+</pre></div>
+
+
+<h2 id="quads">Quads</h2>
+<p>If a custom extension provides named graphs, then it may be useful
+to execute the quad form of the query. This is done by writing a
+custom query engine and overriding <code>QueryEngineMain.modifyOp</code>:</p>
+<div class="codehilite"><pre> <span class="nv">@Override</span>
+ <span class="n">protected</span> <span class="n">Op</span> <span class="n">modifyOp</span><span class="p">(</span><span class="n">Op</span> <span class="n">op</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="sr">//</span> <span class="n">Cope</span> <span class="n">with</span> <span class="n">initial</span> <span class="n">bindings</span><span class="o">.</span>
+ <span class="n">op</span> <span class="o">=</span> <span class="n">Substitute</span><span class="o">.</span><span class="n">substitute</span><span class="p">(</span><span class="n">op</span><span class="p">,</span> <span class="n">initialInput</span><span class="p">)</span> <span class="p">;</span>
+ <span class="sr">//</span> <span class="n">Use</span> <span class="n">standard</span> <span class="n">optimizations</span><span class="o">.</span>
+ <span class="n">op</span> <span class="o">=</span> <span class="n">super</span><span class="o">.</span><span class="n">modifyOp</span><span class="p">(</span><span class="n">op</span><span class="p">)</span> <span class="p">;</span>
+ <span class="sr">//</span> <span class="n">Turn</span> <span class="n">into</span> <span class="n">quad</span> <span class="n">form</span><span class="o">.</span>
+ <span class="n">op</span> <span class="o">=</span> <span class="n">Algebra</span><span class="o">.</span><span class="n">toQuadForm</span><span class="p">(</span><span class="n">op</span><span class="p">)</span> <span class="p">;</span>
+ <span class="k">return</span> <span class="n">op</span> <span class="p">;</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>The extension may need to provide its own dataset implementation so
+that it can detect when queries are directed to its named graph
+storage. <a href="http://openjena.org/SDB">SDB</a> and
+<a href="http://openjena.org/TDB">TDB</a> are examples of this.</p>
+<h2 id="mixed_graph_implementation_datasets">Mixed Graph Implementation Datasets</h2>
+<p>The dataset implementation used in normal operation does not work
+on quads but instead can provide a dataset with a collection of
+graphs each from different implementation sub-systems. In-memory
+graphs can be mixed with database backed graphs as well as custom
+storage systems. Query execution proceeds per-graph so that an
+custom <code>OpExecutor</code> will need to test the graph to work with to
+make sure it is of the right class. The pattern in the
+<code>StageGenerator</code> extension point is an example of design pattern in
+that situation.</p>
+<h2 id="custom_query_engines">Custom Query Engines</h2>
+<p>A custom query engine enables an extension to choose which datasets
+it wishes to handle. It also allows the extension to intercept
+query execution during the setup of the execution so it can modify
+the algebra expression, introduce it's own algebra extensions,
+choose which high-level optimizations to apply and also transform
+to the expression into quad form. Execution can proceed with the
+normal algorithm or a custom <code>OpExecutor</code> or a custom Stage
+Generator or a combination of all three extension mechanism.</p>
+<p>Only a small, skeleton custom query engine is needed to intercept
+the initial setup. See the example in
+<code>src-examples/arq.examples.engine.MyQueryEngine</code>.</p>
+<p>While it is possible to replace the entire process of query
+evaluation, this is a substantial endeavour. <code>QueryExecutionBase</code>
+provides the machinery for result presentation (<code>SELECT</code>,
+<code>CONSTRUCT</code>, <code>DESCRIBE</code>, <code>ASK</code>), leaving the work of pattern
+evaluation to the custom query engine. <code>QueryExecutionFactory</code>
+assumes that <code>QueryExecutionBase</code> will be used.</p>
+<h2 id="algebra_extensions">Algebra Extensions</h2>
+<p>New operators can be added to the algebra using the <code>OpExt</code> class
+as the super-class of the new operator. They can be inserted into
+the expression to be evaluated using a custom query engine to
+intercept evaluation initialization. When evaluation of a query
+requires the evaluation of a sub-class of <code>OpExt</code>, the <code>eval</code>
+method is called. SDB uses this to introduce an operator that is
+implemented in SQL.</p>
+<p><a href="index.html">ARQ documentation index</a></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>
Added: websites/staging/jena/trunk/content/jena/documentation/query/assignment.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/query/assignment.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/query/assignment.html Thu Oct 27 00:01:49 2011
@@ -0,0 +1,241 @@
+<!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 - ARQ - Assignment</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>
+</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">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></li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a></li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a><ul>
+<li><a href="/jena/documentation/sdb/installation.html">Installation</a></li>
+<li><a href="/jena/documentation/sdb/quickstart.html">Quick start</a></li>
+<li><a href="/jena/documentation/sdb/commands.html">Cmd line</a></li>
+<li><a href="/jena/documentation/sdb/javaapi.html">Java API</a></li>
+<li><a href="/jena/documentation/sdb/configuration.html">Config</a></li>
+<li><a href="/jena/documentation/sdb/databases_supported.html">Databases</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/larq/index.html">LARQ</a></li>
+<li><a href="/jena/documentation/serving_data/index.html">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>
+</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>
+</ul>
+</li>
+<li><a href="/jena/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/jena/documentation/tools/schemagen.html">schemagen</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">ARQ - Assignment</h1>
+ <p>ARQ includes support for an explicit assignment of variables.</p>
+<p>This involves is syntactic extension and is available is the query
+is parsed with language <code>Syntax.syntaxARQ</code>.</p>
+<p>See also <a href="select_expr.html">SELECT expressions</a> which is also a
+form of assignment.</p>
+<h2 id="assignment">Assignment</h2>
+<p>The general form is:</p>
+<div class="codehilite"><pre><span class="n">LET</span> <span class="p">(</span> <span class="n">variable</span> <span class="p">:</span><span class="o">=</span> <span class="n">expression</span> <span class="p">)</span>
+</pre></div>
+
+
+<p>For example:</p>
+<div class="codehilite"><pre><span class="n">LET</span> <span class="p">(</span> <span class="p">?</span><span class="n">x</span> <span class="p">:</span><span class="o">=</span> <span class="mi">2</span> <span class="p">)</span>
+
+<span class="p">{</span> <span class="p">?</span><span class="n">x</span> <span class="p">:</span><span class="n">name</span> <span class="p">?</span><span class="n">name</span> <span class="o">.</span>
+ <span class="n">LET</span> <span class="p">(</span> <span class="p">?</span><span class="n">age2</span> <span class="p">:</span><span class="o">=</span> <span class="p">?</span><span class="n">age</span> <span class="o">-</span> <span class="mi">21</span> <span class="p">)</span>
+</pre></div>
+
+
+<p>Note: Assignment is "<strong>:=</strong>"</p>
+<h2 id="assignment_rules">Assignment Rules</h2>
+<p>ARQ assignment is single assignment, that is, once a variable is
+assigned a binding, then it can not be changed in the same query
+solution.</p>
+<p>Only one <code>LET</code> expression per variable is allowed in a single
+scope.</p>
+<p>The execution rules are:</p>
+<ul>
+<li>If the expression does not evaluate (e.g. unbound variable in
+ the expression), no assignment occurs and the query continues.</li>
+<li>If the variable is unbound, and the expression evaluates, the
+ variable is bound to the value.</li>
+<li>If the variable is bound to the same value as the expression
+ evaluates, nothing happens and the query continues.</li>
+<li>If the variable is bound to a different value as the expression
+ evaluates, an error occurs and the current solution will be
+ excluded from the results.</li>
+</ul>
+<p>Note that "same value" means the same as applies to graph pattern
+matching, not to FILTER expressions. Some graph implementation only
+provide same-term graph pattern matching. FILTERs always do
+value-based comparisons for "=" for all graphs.</p>
+<h2 id="use_with_construct">Use with CONSTRUCT</h2>
+<p>One use is to perform some calculation prior to forming the result
+graph in a CONSTRUCT query.</p>
+<div class="codehilite"><pre><span class="n">CONSTRUCT</span> <span class="p">{</span> <span class="p">?</span><span class="n">x</span> <span class="p">:</span><span class="n">lengthInCM</span> <span class="p">?</span><span class="n">cm</span> <span class="p">}</span>
+<span class="n">WHERE</span>
+<span class="p">{</span>
+ <span class="p">?</span><span class="n">x</span> <span class="p">:</span><span class="n">lengthInInches</span> <span class="p">?</span><span class="n">inch</span> <span class="o">.</span>
+ <span class="n">LET</span> <span class="p">(</span> <span class="p">?</span><span class="n">cm</span> <span class="p">:</span><span class="o">=</span> <span class="p">?</span><span class="n">inches</span><span class="o">/</span><span class="mf">2.54</span> <span class="p">)</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="use_with_bound">Use with !BOUND</h2>
+<p>The OPTIONAL/!BOUND/FILTER idiom for performing limited negation of
+a pattern in SPARQL can be inconvenient because it requires a
+variable in the OPTIONAL to be assigned by pattern matching. Using
+a LET can make that easier; here, we assign to ?z (any value will
+do) to mark when the matching pattern included the OPTIONAL
+pattern.</p>
+<p>Example: ?x with no ":p 1" triple:</p>
+<div class="codehilite"><pre><span class="p">{</span>
+ <span class="p">?</span><span class="n">x</span> <span class="n">a</span> <span class="p">:</span><span class="n">FOO</span> <span class="o">.</span>
+ <span class="n">OPTIONAL</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">1</span> <span class="o">.</span> <span class="n">LET</span> <span class="p">(?</span><span class="n">z</span> <span class="p">:</span><span class="o">=</span> <span class="n">true</span><span class="p">)</span> <span class="p">}</span>
+ <span class="n">FILTER</span> <span class="p">(</span> <span class="o">!</span><span class="n">BOUND</span><span class="p">(?</span><span class="n">z</span><span class="p">)</span> <span class="p">)</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Note that <a href="negation.html">negation is supported properly</a> through
+the <code>NOT EXISTS</code> form.</p>
+<p><a href="index.html">ARQ documentation index</a></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>
Added: websites/staging/jena/trunk/content/jena/documentation/query/cmds.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/query/cmds.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/query/cmds.html Thu Oct 27 00:01:49 2011
@@ -0,0 +1,323 @@
+<!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 - ARQ - Command Line Applications</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>
+</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">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></li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a></li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a><ul>
+<li><a href="/jena/documentation/sdb/installation.html">Installation</a></li>
+<li><a href="/jena/documentation/sdb/quickstart.html">Quick start</a></li>
+<li><a href="/jena/documentation/sdb/commands.html">Cmd line</a></li>
+<li><a href="/jena/documentation/sdb/javaapi.html">Java API</a></li>
+<li><a href="/jena/documentation/sdb/configuration.html">Config</a></li>
+<li><a href="/jena/documentation/sdb/databases_supported.html">Databases</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/larq/index.html">LARQ</a></li>
+<li><a href="/jena/documentation/serving_data/index.html">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>
+</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>
+</ul>
+</li>
+<li><a href="/jena/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/jena/documentation/tools/schemagen.html">schemagen</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">ARQ - Command Line Applications</h1>
+ <p>The <code>arq</code> package contains some command line applications to run
+queries, parse queries, process result sets and run test sets.</p>
+<p>You will need to set the classpath, or use the helper scripts, to
+run these applications from the command line. The helper scripts
+are in <code>bin/</code> (Linux, Unix, Cygwin) and <code>bat/</code> (Windows)
+directories. There are ancillary scripts in the directories that
+the main commands need - you should put the relevant directory on
+your command path and set the <code>ARQROOT</code> environment variable after
+checking these scripts are suitable.</p>
+<ul>
+<li>
+<p><a href="#arqquery"><code>arq.query</code></a> is the main query driver.
+ It can be called for SPARQL, ARQ or RDQL queries and there are
+ wrapper commands for each language: <code>arq.sparql</code>, <code>arq.arq</code> and
+ <code>arq.rdql</code>.</p>
+</li>
+<li>
+<p><a href="#arqqparse"><code>arq.qparse</code></a> : parse and print a
+ query.</p>
+</li>
+<li>
+<p><a href="#arqupdate"><code>arq.update</code></a> : execute SPARQL/Update
+ requests.</p>
+</li>
+<li>
+<p><a href="#arqremote"><code>arq.remote</code></a> : execute a query by
+ HTTP on a remote SPARQL endpoint.</p>
+</li>
+<li>
+<p><a href="#arqrset"><code>arq.rset</code></a> : transform result sets.</p>
+</li>
+<li>
+<p><a href="#arqqtest"><code>arq.qtest</code></a> : run a test set.</p>
+</li>
+<li>
+<p><a href="#arqqexpr"><code>arq.qexpr</code></a> : evaluate and print an
+ expression.</p>
+</li>
+<li>
+<p><a href="#arqlarqbuilder"><code>arq.larqbuilder</code></a> : Update a
+ LARQ/Lucene index</p>
+</li>
+<li>
+<p><a href="#arqlarq"><code>arq.larq</code></a> : Query a LARQ/Lucene
+ index</p>
+</li>
+</ul>
+<p>All commands have a <code>--help</code> command for a summary of the
+arguments.</p>
+<p>When using a query in a file, if the query file ends .rq, it is
+assumed to be a SPARQL query. If it ends .arq, it is assumed to be
+an ARQ query (extensions to SPARQL) and if it ends .rdql, it is
+assumed to be an RDQL query. You can specify the syntax
+explicitly.</p>
+<p>The commands <code>jena.query</code>, <code>jena.sparql</code>, <code>jena.qtest</code> and
+<code>jena.rset</code> are equivalent and just call to these commands.</p>
+<h3 id="arqquery"><code>arq.query</code></h3>
+<p>This is the main command for executing queries on data. The
+wrappers just set the query language.</p>
+<ul>
+<li><code>arq.sparql</code> : wrapper for SPARQL queries</li>
+<li><code>arq.arq</code> : wrapper for ARQ queries</li>
+</ul>
+<p>Running <code>arq.query --help</code>prints the usage message. The main
+arguments are:</p>
+<ul>
+<li><code>--query FILE</code> : The file with the query to execute</li>
+<li><code>--data FILE</code> : The data to query. It will be included in the
+ default graph.</li>
+<li><code>--namedgraph FILE</code> : The data to query. It will be included as
+ a named graph.</li>
+<li><code>--desc/--dataset</code>:
+ <a href="http://openjena.org/assembler/">Jena Assembler description</a> of the
+ dataset to be queried, augmented with vocabulary for datasets, not
+ just graphs. See <code>etc/</code> for examples.</li>
+</ul>
+<p>The file extension is used to guess the file serialization format.
+If a data file ends <code>.n3</code>, it is assumed to be N3; if it ends
+<code>.ttl</code> is Turtle; if it is <code>.nt</code> is N-Triples; otherwise it is
+assumed to be RDF/XML. The data serialization can be explicitly
+specified on the command line.</p>
+<h3 id="arqqparse"><code>arq.qparse</code></h3>
+<p>Parse a query and print it out. Can be used to translate between
+syntaxes (but not perfectly - specifically, RDQL value constraints
+need further conversion as complete mechanical translation is not
+possible).</p>
+<p><code>arq.qparse</code> will parse the query, print it out again (with line
+numbers by default) and then parse the serialized query again. If
+your query has a syntax error, a message is printed but no query is
+printed. If a query is printed then you get a syntax error message,
+then your query was syntactically correct but the ARQ serialization
+is broken.</p>
+<p>The command <code>arq.qparse --print=op --file <i>queryFile</i></code>will
+print the SPARQL algebra for the query in
+<a href="http://openjena.org/wiki/SSE">SSE format</a>.</p>
+<h3 id="arqupdate"><code>arq.update</code></h3>
+<p>Execute one or more
+<a href="http://openjena.org/~afs/SPARQL-Update.html">SPARQL/Update</a>
+requests.</p>
+<p>SPARQL/Update is an update language based on SPARQL syntax.</p>
+<ul>
+<li><code>--desc</code>:
+ <a href="http://openjena.org/assembler/">Jena Assembler description</a> of the
+ dataset or graph store to be updated. See <code>etc/</code> for examples.</li>
+</ul>
+<h3 id="arqqtest"><code>arq.qtest</code></h3>
+<p>Execute a test set. In the ARQ directory, <code>qtest --all</code> runs the
+whole ARQ test suite.</p>
+<p>To run a specific test suite, use <code>qtest <em>manifest</em></code>. See
+the working group page
+<a href="http://www.w3.org/2001/sw/DataAccess/tests/">DAWG Testcases</a> for
+details.</p>
+<h3 id="arqrset"><code>arq.rset</code></h3>
+<p>Read and write result sets.</p>
+<p>In particular,</p>
+<div class="codehilite"><pre><span class="n">java</span> <span class="o">-</span><span class="n">cp</span> <span class="o">...</span> <span class="n">arq</span><span class="o">.</span><span class="n">rset</span> <span class="o">--</span><span class="n">in</span> <span class="n">xml</span> <span class="o">--</span><span class="n">out</span> <span class="n">text</span>
+</pre></div>
+
+
+<p>will translate a SPARQL XML Result Set into a tabular text form.</p>
+<h3 id="arqqexpr"><code>arq.qexpr</code></h3>
+<p>Read and print an expression (something that can go in a <code>FILTER</code>
+clause). Indicates whether an evaluation exception occured.</p>
+<p>The <code>-v</code> argument prints the parsed expression.</p>
+<h3 id="arqremote"><code>arq.remote</code></h3>
+<p>Execute a request on a remote SPARQL endpoint using HTTP.</p>
+<ul>
+<li><code>--service URL</code> : The endpoint.</li>
+<li><code>--data FILE</code> : Dataset description (default graph) added to
+ the request.</li>
+<li><code>--namedgraph FILE</code> : Dataset description (named graph) added
+ to the request.</li>
+<li><code>--results FORMAT</code> : Write results in specified format. Does
+ not change the request to the server which is always for an XML
+ form.</li>
+</ul>
+<h3 id="arqlarqbuilder"><code>arq.larqbuilder</code></h3>
+<p>Build or update a <a href="lucene-arq.html">LARQ index</a>. If a dataset is
+given to the command, all graphs are indexed. if a single graph is
+given to the command, that graph is indexed.</p>
+<ul>
+<li><code>--larq</code> : Name of the directory for the Lucene index files.</li>
+<li><code>--subjects</code> : By default literals are indexed against the
+ literal RDF node (<a href="cmds.htm#lPattern_1">pattern 1</a>). Using this
+ argument cause the subject RDF terms to be indexed
+ (<a href="cmds.htm#lPattern_2">pattern 2</a>).</li>
+<li>Dataset description using <code>--data FILE</code> or <code>--desc.</code></li>
+</ul>
+<h3 id="arqlarq"><code>arq.larq</code></h3>
+<p>Issue a Lucene query and print the nodes found (objects or subjects
+as appropriate).</p>
+<ul>
+<li><code>--larq</code> : Name of the directory for the Lucene index files.</li>
+</ul>
+<p><a href="index.html">ARQ documentation index</a></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>
Added: websites/staging/jena/trunk/content/jena/documentation/query/download.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/query/download.html (added)
+++ websites/staging/jena/trunk/content/jena/documentation/query/download.html Thu Oct 27 00:01:49 2011
@@ -0,0 +1,174 @@
+<!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 - ARQ Downloads</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>
+</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">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></li>
+<li><a href="/jena/documentation/tdb/index.html">TDB</a></li>
+<li><a href="/jena/documentation/sdb/index.html">SDB</a><ul>
+<li><a href="/jena/documentation/sdb/installation.html">Installation</a></li>
+<li><a href="/jena/documentation/sdb/quickstart.html">Quick start</a></li>
+<li><a href="/jena/documentation/sdb/commands.html">Cmd line</a></li>
+<li><a href="/jena/documentation/sdb/javaapi.html">Java API</a></li>
+<li><a href="/jena/documentation/sdb/configuration.html">Config</a></li>
+<li><a href="/jena/documentation/sdb/databases_supported.html">Databases</a></li>
+</ul>
+</li>
+<li><a href="/jena/documentation/larq/index.html">LARQ</a></li>
+<li><a href="/jena/documentation/serving_data/index.html">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>
+</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>
+</ul>
+</li>
+<li><a href="/jena/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/jena/documentation/tools/schemagen.html">schemagen</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">ARQ Downloads</h1>
+ <p><a href="https://sourceforge.net/projects/jena/files/ARQ/">ARQ downloads</a>
+<em>TODO</em> - need to change this to point to the Apache download area</p>
+<h2 id="subversion">Subversion</h2>
+<p>Access to the live development version, including a complete
+Eclipse project, is available <a href="https://svn.apache.org/repos/asf/incubator/jena/Jena2/ARQ/">via SVN</a></p>
+<p><a href="index.html">ARQ documentation index</a></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>