svn commit: r875885 - in /websites/staging/jena/trunk/content: ./ documentation/jdbc/index.html

[bu...@apache.org]

Author: buildbot
Date: Fri Aug 23 19:15:08 2013
New Revision: 875885

Log:
Staging update by buildbot for jena

Modified:
    websites/staging/jena/trunk/content/   (props changed)
    websites/staging/jena/trunk/content/documentation/jdbc/index.html

Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Fri Aug 23 19:15:08 2013
@@ -1 +1 @@
-1516977
+1516987

Modified: websites/staging/jena/trunk/content/documentation/jdbc/index.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/jdbc/index.html (original)
+++ websites/staging/jena/trunk/content/documentation/jdbc/index.html Fri Aug 23 19:15:08 2013
@@ -108,9 +108,11 @@
 RDF data model as a relational model through the driver and only SPARQL queries and updates
 are supported.  Otherwise it is a fully fledge type 4 JDBC driver.</p>
 <h2 id="documentation">Documentation</h2>
-<p>A general overview of the functionality of the drivers is given later on this page, the
-following additional documentation topics are also available.</p>
 <ul>
+<li><a href="#overview">Overview</a></li>
+<li><a href="#basic-usage">Basic Usage</a></li>
+<li><a href="#making-queries">Making Queries</a></li>
+<li><a href="#alternatives">Alternatives</a></li>
 <li><a href="drivers.html">Jena JDBC Drivers</a></li>
 <li><a href="custom_driver.html">Implementing a custom Jena JDBC Driver</a></li>
 </ul>
@@ -125,7 +127,47 @@ either SPARQL queries or updates and pro
 </ul>
 <p>These are all built on a core library which can be used to build <a href="custom_driver.html">custom drivers</a>
 if desired.  This means that all drivers share common infrastructure and thus exhibit broadly speaking
-the same behaviors.</p>
+the same behavior around handling queries, updates and results.</p>
+<h3 id="treatment-of-results">Treatment of Results</h3>
+<p>One important behavioral aspect to understand is how results are treated compared to a traditional
+JDBC driver.  SPARQL provides four query forms and thus four forms of results while JDBC assumes all
+results have a simple tabular format.  Therefore one of the main jobs of the core library is to marshal
+the results of each kind of query into a tabular format.  For <code>SELECT</code> queries this is a trivial mapping,
+for <code>CONSTRUCT</code> and <code>DESCRIBE</code> the triples are mapped to columns named <code>Subject</code>, <code>Predicate</code> and <code>Object</code>
+respectively, finally for <code>ASK</code> the boolean is mapped to a single column named <code>ASK</code>.</p>
+<p>The second issue is that JDBC expects uniform column typing throughout a result set which is not
+something that holds true for SPARQL results.  Therefore the core library takes a pragmatic approach to column
+typing and makes the exact behavior configurable by the user.  The default behavior of the core library is
+to type all columns as <code>Types.NVARCHAR</code> with a Java type of <code>String</code>, this provides the widest compatibility
+possible with both the SPARQL results and consuming tools since we can treat everything as a string.  We
+refer to this default behavior as medium compatibility, it is sufficient to allow JDBC tools to interpret
+results for basic display but may be unsuitable for further processing.</p>
+<p>We then provide two alternatives, the first of which we refer to as high compatibility aims to present the
+data in a way that is more amenable to subsequent processing by JDBC tools.  In this mode the column types
+in a result set are detected by sniffing the data in the first row of the result set and assigning appropriate
+types.  For example if the first row for a given column has the value <code>"1234"^^xsd:integer</code> then it would
+be assigned the type <code>Types.BIGINT</code> and have the Java type of <code>Long</code>.  Doing this allows JDBC tools to carry
+out subsequent calculations on the data in a type appropriate way.  It is important to be aware that this
+sniffing may not be accurate for the entire result set so can still result in errors processing some rows.</p>
+<p>The second alternative we refer to as low compatibility and is designed for users who are using the driver
+directly and are fully aware that they are writing SPARQL queries and getting SPARQL results.  In this mode
+we make no effort to type columns in a friendly way instead typing them as <code>Types.JAVA_OBJECT</code> with the Java
+type <code>Node</code> (i.e. the Jena <a href="/documentation/javadoc/jena/com/hp/hpl/jena/graph/Node.html">Node</a> class).</p>
+<p>Regardless of how you configure to do column typing the core library does it best to allow you to marshal values
+into strong types.  For example even if using default compatibility and your columns are typed as strings
+from a JDBC perspective you can still call <code>getLong("column")</code> and if there is a valid conversion the
+library will make it for you.</p>
+<p>Another point of interest is around our support of different result set types.  The drivers support both
+<code>ResultSet.TYPE_FORWARD_ONLY</code> and <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, note that regardless of the type
+chosen and the underlying query type all result sets are <code>ResultSet.CONCUR_READ_ONLY</code> i.e. the <code>setLong()</code>
+style methods cannot be used to update the underlying RDF data.  Users should be aware that the default
+behavior is to use forward only result sets since this allows the drivers to stream the results and
+minimizes memory usage.  When scrollable result sets are used the drivers will cache all the results into
+memory which can use lots of memory when querying large datasets.</p>
+<h2 id="basic-usage">Basic Usage</h2>
+<h3 id="making-a-connection">Making a Connection</h3>
+<h3 id="making-queries">Making Queries</h3>
+<p>You make queries as you would</p>
 <h2 id="alternatives">Alternatives</h2>
 <p>If Jena JDBC does not fulfill your use case you may also be interested in some 3rd party
 projects which do SPARQL over JDBC in other ways:</p>