svn commit: r1213107 - in /incubator/jena/site/trunk/content/jena/documentation/tdb: index.mdtext tdb_transactions.mdtext

[ij...@apache.org]

Author: ijd
Date: Sun Dec 11 23:37:16 2011
New Revision: 1213107

URL: http://svn.apache.org/viewvc?rev=1213107&view=rev
Log:
Migrated TDB transactions content from Jena wiki

Added:
    incubator/jena/site/trunk/content/jena/documentation/tdb/tdb_transactions.mdtext
Modified:
    incubator/jena/site/trunk/content/jena/documentation/tdb/index.mdtext

Modified: incubator/jena/site/trunk/content/jena/documentation/tdb/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/tdb/index.mdtext?rev=1213107&r1=1213106&r2=1213107&view=diff
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/tdb/index.mdtext (original)
+++ incubator/jena/site/trunk/content/jena/documentation/tdb/index.mdtext Sun Dec 11 23:37:16 2011
@@ -3,7 +3,7 @@ Title: TDB
 TDB is a component of
 [Jena](http://incubator.apache.org/jena) for RDF storage
 and query, as well as the full range of Jena APIs.
-TDB can be used as a high performance, non-transactional, RDF store
+TDB can be used as a high performance RDF store
 on a single machine. This documentation describes the latest version, unless
 otherwise noted.
 
@@ -36,6 +36,7 @@ for query, update and REST update over H
 -   [The TDB Optimizer](optimizer.html)
 -   [TDB Configuration](configuration.html)
 -   [Joseki Integration](joseki_integration.html)
+-   [Transactions](tdb_transactions.html)
 
 ## Downloads
 

Added: incubator/jena/site/trunk/content/jena/documentation/tdb/tdb_transactions.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/tdb/tdb_transactions.mdtext?rev=1213107&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/tdb/tdb_transactions.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/tdb/tdb_transactions.mdtext Sun Dec 11 23:37:16 2011
@@ -0,0 +1,189 @@
+Title: TDB Transactions
+
+TDB provides
+[ACID](http://en.wikipedia.org/wiki/ACID)
+transaction support through the use of
+[write-ahead-logging](http://en.wikipedia.org/wiki/Write-ahead_logging).
+
+This feature is part of version TDB 0.9.0 and later.
+
+Databases created with version of TDB 0.8.X can be used with 0.9.X
+to add transactional capability.
+
+The file format of 0.9.X is compatible with TDB 0.8.X. See below
+for reverting a database to 0.8.X.
+
+## Contents
+
+-   [Status](#status)
+-   [Overview](#overview)
+-   [Limitations](#limitations)
+-   [API for Transactions](#api_for_transactions)
+-   [Examples](#examples)
+-   [Migration from TDB 0.8.X](#migration_from_tdb_0.8.X)
+-   [Reverting to TDB 0.8.X](#reverting_to_tdb_0.8.X)
+-   [Multi JVM](#multi_jvm)
+-   [Bulk loading](#bulk_loading)
+
+## Status
+
+Currently *in development*.
+
+[Development snapshot builds](http://www.openjena.org/repo-dev/com/hp/hpl/jena/tx-tdb/)
+
+[Source code repository](https://svn.apache.org/repos/asf/incubator/jena/Experimental/TxTDB/trunk/)
+
+## Overview
+
+The transaction mechanism in TDB is based on
+[write-ahead-logging](http://en.wikipedia.org/wiki/Write-ahead_logging).
+All changes made inside a write-transaction are written to
+[journals](http://en.wikipedia.org/wiki/Journaling_file_system),
+then propagated to the main database at a suitable moment. This
+design allows for read-transactions to proceed without locking or
+other overhead over the base database.
+
+Transactional TDB supports one active write transaction, and
+multiple read transactions at the same time. Read-transactions
+started before a write-transaction commits see the database in a
+state without any changes visible. Any transaction starting after a
+write-transaction commits sees the database with the changes
+visible, whether fully propagates back to the database or not.
+There can be active read transactions seeing the state of the
+database before the updates, and read transactions seeing the state
+of the database after the updates running at the same time.
+
+Transactional TDB works with SPARQL Query, SPARQL Update, SPARQL
+Graph Store Update as well as the full Jena API.
+
+TDB provides
+[Serializable](http://en.wikipedia.org/wiki/Isolation_(database_systems)#SERIALIZABLE)
+transactions, the highest
+[isolation level](http://en.wikipedia.org/wiki/Isolation_(database_systems)).
+
+The transaction action mechanism is not designed for large-scale
+database changes.
+
+## Limitations
+
+(some of these limitations may be removed in later versions)
+
+-   Bulk loads: the TDB bulk loader is not transactional
+-   No nested update transactions.
+-   Single active writer: no multiple concurrent update
+    transactions.
+-   Some active transaction state is held exclusively in-memory,
+    limiting scalability.
+-   Long-running transactions. Read-transactions cause a build-up
+    of pending changes;
+
+If a single read transaction runs for a long time when there are
+many updates, the system will consume a lot of temporary
+resources.
+
+## API for Transactions
+
+[Development]
+
+*The API currently relies on a mix of TDB-specific low-level operations and general high-level operations. This will be sorted out to be uniform.*
+
+### Read transactions
+
+These are used for SPARQL queries and code using the Jena API
+actions that do not change the data.
+
+### Write transactions
+
+These are used for SPARQL queries, SPARQL updates and any Jena API
+actions.
+
+While it is possible to shared a write transaction between multiple
+threads, this is not encouraged. Applications needing to do so must
+ensure that within the transactions, all threads are acting
+"multiple reader OR single writer". Changes the data within the
+transaction must be executed one at a time.
+
+## Examples
+
+### Read Transaction
+
+     DatasetGraphTxn dsg = sConn.begin(ReadWrite.READ) ;
+     try {
+         Dataset ds = DatasetFactory.create(dsg) ;
+         QueryExecution qExec = QueryExecutionFactory.create("SELECT * { ?s ?p ?o} LIMIT 10", ds) ;
+         ResultSet rs = qExec.execSelect() ;
+         try {
+             ResultSetFormatter.out(rs) ;
+         } finally { qExec.close() ; }
+
+         // Another query - same view of the data.
+         qExec = QueryExecutionFactory.create("SELECT * { ?s ?p ?o} OFFSET 10 LIMIT 10", ds) ;
+         rs = qExec.execSelect() ;
+         try {
+             ResultSetFormatter.out(rs) ;
+         } finally { qExec.close() ; }
+     } finally { dsg.close() ; }
+
+### Write Transaction
+
+     DatasetGraphTxn dsg = sConn.begin(ReadWrite.WRITE) ;
+     try {
+         Dataset ds = DatasetFactory.create(dsg) ;
+         // Query
+         QueryExecution qExec = QueryExecutionFactory.create("SELECT * { ?s ?p ?o} LIMIT 10", ds) ;
+         ResultSet rs = qExec.execSelect() ;
+         try {
+             ResultSetFormatter.out(rs) ;
+         } finally { qExec.close() ; }
+
+         // Update
+         UpdateRequest request = UpdateFactory.create("PREFIX : <http://example/> INSERT DATA { :s :p :o}") ;
+         UpdateProcessor proc = UpdateExecutionFactory.create(request, dsg) ;
+         proc.execute() ;
+         // A query here will see the inserted data.
+         dsg.commit() ;
+     } finally { dsg.close() ; } // WARNING if no commit or abort.
+
+### Nesting Transactions
+
+[Nested write transactions](http://en.wikipedia.org/wiki/Nested_transaction)
+are not supported.
+
+A read transaction may be started inside a write transaction - this
+behaves like a top-level read transaction over the state of the
+database before the write transaction started.
+
+## Migration from TDB 0.8.X
+
+The database files used by TDB 0.9.0 are fully compatible with TDB
+0.8.X; there are no file format changes and application code using
+the interface provided by `TDBFactory` will continue to work as
+before, without transaction capabilities. The only addition is the
+presence of journal files.
+
+Transactions use a new API: the `TDBFactory` API is still present.
+If an application simply uses the TDB 0.9 codebase, it will work as
+before without transactions.
+
+Applications can start using transaction by coding to the new API.
+
+## Reverting to TDB 0.8.X
+
+A database can be reverted to TDB 0.8.X by running `tdb.tdbrecover`
+- this program recovers any committed transaction with pending
+actions. The database can then be used with TDB 0.8.X.
+
+## Multi JVM
+
+Multiple applications, running in multiple JVMs, using the same
+file databases is not supported. There must be a single JVM
+controlling the database directory and files.
+
+Use [Fuseki](http://openjena.org/wiki/Fuseki) to provide a
+database server for multiple applications. Fuseki supports SPARQL
+Query, SPARQL Update, SPARQL Graph Store Update.
+
+## Bulk loading
+
+The bulk loader is not transactional.
+