jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r875885 - in /websites/staging/jena/trunk/content: ./ documentation/jdbc/index.html
Date Fri, 23 Aug 2013 19:15:08 GMT
Author: buildbot
Date: Fri Aug 23 19:15:08 2013
New Revision: 875885

Staging update by buildbot for jena

    websites/staging/jena/trunk/content/   (props changed)

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

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
@@ -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,
-following additional documentation topics are also available.</p>
+<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>
@@ -125,7 +127,47 @@ either SPARQL queries or updates and pro
 <p>These are all built on a core library which can be used to build <a href="custom_driver.html">custom
 if desired.  This means that all drivers share common infrastructure and thus exhibit broadly
-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>
+<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
+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
 projects which do SPARQL over JDBC in other ways:</p>

View raw message