svn commit: r810456 - in /websites/staging/jena/trunk/content: ./ jena/documentation/tdb/tdb_transactions.html

[bu...@apache.org]

Author: buildbot
Date: Wed Mar 28 21:39:32 2012
New Revision: 810456

Log:
Staging update by buildbot for jena

Modified:
    websites/staging/jena/trunk/content/   (props changed)
    websites/staging/jena/trunk/content/jena/documentation/tdb/tdb_transactions.html

Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Mar 28 21:39:32 2012
@@ -1 +1 @@
-1306478
+1306606

Modified: websites/staging/jena/trunk/content/jena/documentation/tdb/tdb_transactions.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/tdb/tdb_transactions.html (original)
+++ websites/staging/jena/trunk/content/jena/documentation/tdb/tdb_transactions.html Wed Mar 28 21:39:32 2012
@@ -236,7 +236,7 @@ actions that do not change the data.  Th
 <p>The <code>dataset.end()</code> declares the end of the read transaction.  Applications may also call
 <code>dataset.commit()</code> or <code>dataset.abort()</code> which all have the same effect for a read transaction.</p>
 <div class="codehilite"><pre> <span class="n">Location</span> <span class="n">location</span> <span class="o">=</span> <span class="o">...</span> <span class="p">;</span>
- <span class="n">Dataset</span> <span class="n">dataset</span> <span class="o">=</span>  <span class="n">TDBFactory</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">location</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">Dataset</span> <span class="n">dataset</span> <span class="o">=</span> <span class="o">...</span> <span class="p">;</span>
  <span class="n">dataset</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="o">.</span><span class="n">READ</span><span class="p">)</span> <span class="p">;</span>
 
  <span class="n">try</span> <span class="p">{</span>
@@ -277,7 +277,7 @@ operations consume large amounts of temp
 needs to start a new transaction to perform further operations on the 
 dataset.</p>
 <div class="codehilite"><pre> <span class="n">Location</span> <span class="n">location</span> <span class="o">=</span> <span class="o">...</span> <span class="p">;</span>
- <span class="n">Dataset</span> <span class="n">dataset</span> <span class="o">=</span>  <span class="n">TDBFactory</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">location</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">Dataset</span> <span class="n">dataset</span> <span class="o">=</span> <span class="o">...</span> <span class="p">;</span>
  <span class="n">dataset</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="o">.</span><span class="n">WRITE</span><span class="p">)</span> <span class="p">;</span>
 
  <span class="n">try</span> <span class="p">{</span>
@@ -316,17 +316,33 @@ dataset.</p>
 
 
 <h2 id="multi-threaded-use">Multi-threaded use</h2>
-<p>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 transaction, all threads are acting
-"multiple reader OR single writer". Change to the data within the
-transaction must be executed one at a time.</p>
-<p>It is better not to share the same Dataset reference between different 
-threads. Dataset objects are quite cheap to create via 
-TDBFactory.create(location) and this ensure correct transaction
-handling. If, for some reason, in-memory TDB databases are needed, 
-then the use of "named memory locations" is recommended: Location.mem("X").<br />
-</p>
+<p>The usual idiom for working with multi-threaded applications is to have 
+one dataset per thread.  There is one transaction per datset object.</p>
+<p>Thread 1:</p>
+<div class="codehilite"><pre> <span class="n">Dataset</span> <span class="n">dataset</span> <span class="o">=</span> <span class="n">TDBFactory</span><span class="o">.</span><span class="n">createDataset</span><span class="p">(</span><span class="n">location</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">dataset</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="o">.</span><span class="n">WRITE</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">try</span> <span class="p">{</span>
+   <span class="o">...</span>
+   <span class="n">dataset</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="p">;</span>
+ <span class="p">}</span> <span class="n">finally</span> <span class="p">{</span> <span class="n">dataset</span><span class="o">.</span><span class="n">end</span><span class="p">()</span> <span class="p">;</span> <span class="p">}</span>
+</pre></div>
+
+
+<p>Thread 2:</p>
+<div class="codehilite"><pre> <span class="n">Dataset</span> <span class="n">dataset</span> <span class="o">=</span> <span class="n">TDBFactory</span><span class="o">.</span><span class="n">createDataset</span><span class="p">(</span><span class="n">location</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">dataset</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">ReadWrite</span><span class="o">.</span><span class="n">READ</span><span class="p">)</span> <span class="p">;</span>
+ <span class="n">try</span> <span class="p">{</span>
+   <span class="o">...</span>
+ <span class="p">}</span> <span class="n">finally</span> <span class="p">{</span> <span class="n">dataset</span><span class="o">.</span><span class="n">end</span><span class="p">()</span> <span class="p">;</span> <span class="p">}</span>
+</pre></div>
+
+
+<p>Each thread has a separate <code>dataset</code> object; these share internally the 
+same storage but each can have it's own transaction.</p>
+<p>While it is possible to shared a transaction between multiple
+threads, this is not encouraged.  Applications needing to do so must
+ensure that only one thread starts the transaction, via a <code>Dataset</code> object,
+and that all threads are acting "multiple reader OR single writer". </p>
 <h2 id="multi-jvm">Multi JVM</h2>
 <p>Multiple applications, running in multiple JVMs, using the same
 file databases is not supported. There must be a single JVM