svn commit: r170787 - /incubator/derby/docs/trunk/src/tuning/rtunproperdurability.dita

[jt...@apache.org]

Author: jta
Date: Wed May 18 11:14:36 2005
New Revision: 170787

URL: http://svn.apache.org/viewcvs?rev=170787&view=rev
Log:
DERBY-271 (http://issues.apache.org/jira/browse/DERBY-271):
Added documentation for the new derby.system.durability property to the
Tuning Guide.

Added:
    incubator/derby/docs/trunk/src/tuning/rtunproperdurability.dita

Added: incubator/derby/docs/trunk/src/tuning/rtunproperdurability.dita
URL: http://svn.apache.org/viewcvs/incubator/derby/docs/trunk/src/tuning/rtunproperdurability.dita?rev=170787&view=auto
==============================================================================
--- incubator/derby/docs/trunk/src/tuning/rtunproperdurability.dita (added)
+++ incubator/derby/docs/trunk/src/tuning/rtunproperdurability.dita Wed May 18 11:14:36 2005
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE reference PUBLIC "-//IBM//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<!-- 
+Copyright 1997, 2004 The Apache Software Foundation or its licensors, as applicable.  
+
+Licensed under the Apache License, Version 2.0 (the "License");  
+you may not use this file except in compliance with the License.  
+You may obtain a copy of the License at      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<reference id="rtunproperdurability" xml:lang="en-us">
+<title>derby.system.durability</title>
+<prolog><metadata>
+<keywords><indexterm>derby.system.durability</indexterm></keywords>
+</metadata></prolog>
+<refbody>
+<section><title>Function</title>This property changes the default durability
+of <ph conref="tunconrefs.dita#prod/productshortname"></ph> to improve performance
+at the expense of consistency and durability of the database. The only valid
+supported case insensitive value is <codeph>test</codeph>. If this property
+is set to any value other than <codeph>test</codeph>, this property setting
+is ignored.  When <codeph>derby.system.durability</codeph> is set to <codeph>test</codeph>,
+the store system will not force I/O synchronization calls for:<ul>
+<li>the log file at each commit.</li>
+<li>the log file before a data page is forced to disk.</li>
+<li>page allocation when a file is grown.</li>
+<li>for data writes during checkpoints.</li>
+</ul><p>While performance is improved, note that under these conditions, a
+commit no longer guarantees that the transaction's modification will survive
+a system crash or JVM termination, the database may not recover successfully
+upon restart, a near-full disk at runtime may cause unexpected errors, and
+the database may be in an inconsistent state.</p><p>If you boot the database
+with this property set to <codeph>test</codeph>, the following warning message
+is logged in the <codeph>derby.log</codeph> file:<codeblock>WARNING: The database is booted with derby.system.durability=test.
+In this mode, it is possible that database may not be able 
+to recover, committed transactions may be lost, and the database 
+may be in an inconsistent state. Please use this mode only when 
+these consequences are acceptable.</codeblock>A similar message will appear
+in the <codeph>derby.log</codeph> file if the database was booted with derby.system.durability=test
+at any time previously.</p><p>Once the database is booted with <codeph>derby.system.durability=test</codeph>,
+there are no guarantees that the database is consistent.</p></section>
+<section><title>Default</title><p>This property is ignored by default.</p> </section>
+<section><title>Supported values</title><p>The only supported value is <codeph>test</codeph>.</p></section>
+<example><title>Example</title><codeblock><b>derby.system.durability=test</b></codeblock><p>Since
+this is a system property, you can set it in the <codeph>derby.properties</codeph> file
+or on the command line of the JVM when starting the application.</p><p>You
+might enable this property when using <ph conref="tunconrefs.dita#prod/productshortname"></ph> as
+a test database where consistency or recoverability is not an issue.</p></example>
+<section><title>Dynamic or static</title><p>This property is static; if you
+change it while <ph conref="tunconrefs.dita#prod/productshortname"></ph> is
+running, the change does not take effect until you reboot.</p> </section>
+</refbody>
+</reference>