Github user rvesse commented on a diff in the pull request:
https://github.com/apache/jena/pull/197#discussion_r92840274
--- Diff: jena-rdfconnection/Documentation.md ---
@@ -0,0 +1,205 @@
+# RDF Connection : SPARQL operations API
+
+`RDFConnection` provides a unified set of operations for working on RDF
+with SPARQL operations. It provides <a
+href="http://www.w3.org/TR/sparql11-query/";>SPARQL Query</a>, <a
+href="http://www.w3.org/TR/sparql11-update/";>SPARQL Update</a> and the <a
+href="http://www.w3.org/TR/sparql11-http-rdf-update/";>SPARQL Graph
+Store</a> operations. The interface is uniform - the same interface
+applies to local data and to remote data using HTTP and the SPARQL
+protocols ( <a href="http://www.w3.org/TR/sparql11-protocol/";>SPARQL
+protocol</a> and <a
+href="http://www.w3.org/TR/sparql11-http-rdf-update/";>SPARQL Graph Store
+Protocol</a>).
+
+## Outline
+
+`RDFConnection` provides a number of different styles for working with RDF
+data in Java. It provides support for try-resource and functional code
+passing styles, as well the more basic sequence of methods calls.
+
+`try-resources` to manage the connection, and two operations, one to load
+some data, and one to make a query:
+
+```
+try ( RDFConnection conn = RDFConnectionFactory.connect(...) ) {
+ conn.load("data.ttl") ;
+ conn.querySelect("SELECT DISTINCT ?s { ?s ?p ?o }", (qs)->
+ Resource subject = qs.getResource("s") ;
+ System.out.println("Subject: "+subject) ;
+ }) ;
+}
+```
+This could have been written as (approximately -- the error handling is
better
+in the example above):
+
+```
+RDFConnection conn = RDFConnectionFactory.connect(...)
+conn.load("data.ttl") ;
+QueryExecution qExec = conn.query("SELECT DISTINCT ?s { ?s ?p ?o }") ;
+ResultSet rs = qExec.execSelect() ;
+while(rs.hasNext()) {
+ QuerySolution qs = rs.next() ;
+ Resource subject = qs.getResource("s") ;
+ System.out.println("Subject: "+subject) ;
+}
+qExec.close() ;
+conn.close() ;
+```
+
+Jena also provides a separate
+[SPARQL over JDBC
driver](http://jena.staging.apache.org/documentation/jdbc/index.html)
+library.
+
+## Transactions
+
+Transactions are the preferred way to work with RDF data.
+Operations on an `RDFConnection` outside of an application-controlled
+transaction will cause the system to add one for the duration of the
+operation. This "autocommit" feature may lead to inefficient operations due
+to excessive overhead.
+
+The `Txn` class provides a Java8-style transaction API. Transactions are
+code passed in the `Txn` library that handles the transaction lifecycle.
+
+```
+try ( RDFConnection conn = RDFConnectionFactory.connect(...) ) {
+ Txn.execWrite(conn, ()-> {
+ conn.load("data1.ttl") ;
+ conn.load("data2.ttl") ;
+ conn.querySelect("SELECT DISTINCT ?s { ?s ?p ?o }", (qs)->
+ Resource subject = qs.getResource("s") ;
+ System.out.println("Subject: "+subject) ;
+ }) ;
+ }) ;
+}
+```
+
+The traditional style of explicit `begin`, `commit`, `abort` is also
available.
+
+```
+try ( RDFConnection conn = RDFConnectionFactory.connect(...) ) {
+ conn.begin(ReadWrite.WRITE) ;
+ try {
+ conn.load("data1.ttl") ;
+ conn.load("data2.ttl") ;
+ conn.querySelect("SELECT DISTINCT ?s { ?s ?p ?o }", (qs)->
+ Resource subject = qs.getResource("s") ;
+ System.out.println("Subject: "+subject) ;
+ }) ;
+ conn.commit() ;
+ } finally { conn.end() ; }
+}
+```
+
+The use of `try-finally` ensures that transactions are properly finished.
+The `conn.end()` provides an abort in case an exception occurs in the
+transaction and a commit has not been issued. The use of `try-finally`
+ensures that transactions are properly finished.
+
+`Txn` is wrapping these steps up and calling the application supplied code
+for the transaction body.
+
+### Remote Transactions
+
+SPARQL does not define a remote transaction standard protocol. Each remote
+operation shuld be atomic (all happens or nothing happens) - this is the
+responsibility of the remote server.
+
+An `RDFConenction` will at least provide the client-side locking features.
+This means that overlapping operations that chnage data are naturally
--- End diff --
Typo: chnage -> change
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
