svn commit: r917083 - in /websites/staging/jena/trunk/content: ./ documentation/tdb/faqs.html

[bu...@apache.org]

Author: buildbot
Date: Tue Jul 22 10:37:32 2014
New Revision: 917083

Log:
Staging update by buildbot for jena

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

Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Jul 22 10:37:32 2014
@@ -1 +1 @@
-1612532
+1612537

Modified: websites/staging/jena/trunk/content/documentation/tdb/faqs.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/tdb/faqs.html (original)
+++ websites/staging/jena/trunk/content/documentation/tdb/faqs.html Tue Jul 22 10:37:32 2014
@@ -154,6 +154,8 @@
 <li><a href="#java-heap">How large a Java heap size should I use for TDB?</a></li>
 <li><a href="#fuseki-tdb-memory-leak">Does Fuseki/TDB have a memory leak?</a></li>
 <li><a href="#ssd">Should I use a SSD?</a></li>
+<li><a href="#lock-exception">Why do I get the exception <em>Can't open database at location /path/to/db as it is already locked by the process with PID 1234</em> when trying to open a TDB database?</a></li>
+<li><a href="#no-lock-warning">I see a warning that <em>Location /path/to/db was not locked, if another JVM accessed this location simultaneously data corruption may have occurred</em> in my logs?</a></li>
 </ul>
 <p><a name="transactions"></a></p>
 <h2 id="does-tdb-support-transactions">Does TDB support transactions?</h2>
@@ -172,6 +174,8 @@ transactionally.</p>
 file databases is <strong>not</strong> supported and has a high risk of data corruption.  Once corrupted a database cannot be repaired
 and must be rebuilt from the original source data. Therefore there <strong>must</strong> be a single JVM
 controlling the database directory and files.</p>
+<p>From 1.1.0 onwards TDB includes automatic prevention of multi-JVM usage which prevents this under most circumstances and helps
+protect your data from corruption.</p>
 <p>If you wish to share a TDB dataset between applications use our <a href="../serving_data/">Fuseki</a> component which provides a 
 database server. Fuseki supports <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 protocol</a>.
@@ -233,6 +237,23 @@ memory faster.</p>
 <p>SSDs will make the most difference when performing bulk loads since the on-disk database format for TDB is entirely portable and may be
 safely copied between systems (provided there is no process accessing the database at the time).  Therefore even if you can't run your production
 system with a SSD you can always perform your bulk load on a SSD equipped system first and then move the database to your production system.</p>
+<p><a name="lock-exception"></a></p>
+<h2 id="why-do-i-get-the-exception-cant-open-database-at-location-pathtodb-as-it-is-already-locked-by-the-process-with-pid-1234-when-trying-to-open-a-tdb-database">Why do I get the exception <em>Can't open database at location /path/to/db as it is already locked by the process with PID 1234</em> when trying to open a TDB database?</h2>
+<p>This exception is a result of TDBs automatic multi-JVM usage prevention, as noted in the earlier 
+<a href="#multi-jvm">Can I share a TDB dataset between multiple applications?</a> question a TDB database can only be safely used by a single JVM otherwise
+data corruption may occur.  From 1.1.0 onwards TDB automatically enforces this restriction wherever possible and you will get this exception if you
+attempt to access a database which is being accessed from another JVM.</p>
+<p>To investigate this error look use the process management tools for your OS to see what the process ID referenced in the error is.  If it is another JVM
+then the error is entirely valid and you should follow the advice about sharing a TDB dataset between applications.  In rare circumstances you may find 
+that the process is entirely unrelated (this can happen due to stale lock files since they are not always automatically cleared up) in which case you can
+try and manually remove the <code>tdb.lock</code> file from the database directory.  Please only do this if you are certain that the other process is not accessing
+the TDB database.</p>
+<p><a name="no-lock-warning"></a></p>
+<h2 id="i-see-a-warning-that-location-pathtodb-was-not-locked-if-another-jvm-accessed-this-location-simultaneously-data-corruption-may-have-occurred-in-my-logs">I see a warning that <em>Location /path/to/db was not locked, if another JVM accessed this location simultaneously data corruption may have occurred</em> in my logs?</h2>
+<p>This warning can occur in rare circumstances when TDB detects that you are releasing a database location via <code>StoreConnection.release()</code> and that the
+database was eligible to be locked but wasn't.  This can usually only occur if you circumvented the normal TDB database opening procedures somehow.</p>
+<p>As the warning states data corruption may occur if another JVM accesses the location while your process is accessing it.  Ideally you should follow the
+advice on <a href="#multi-jvm">multi-JVM usage</a> if this might happen, otherwise the warning can likely be safely ignored.</p>
   </div>
 </div>