You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by fu...@apache.org on 2006/10/01 22:20:52 UTC
svn commit: r451802 - /db/derby/docs/trunk/src/devguide/
Author: fuzzylogic
Date: Sun Oct 1 13:20:51 2006
New Revision: 451802
URL: http://svn.apache.org/viewvc?view=rev&rev=451802
Log:
DERBY-1873: Developer's guide improvements from doc review. Commit of
derby1873_3.diff
Committed for Laura Stewart <sc...@gmail.com>
Modified:
db/derby/docs/trunk/src/devguide/cdevconcepts50894.dita
db/derby/docs/trunk/src/devguide/cdevconcepts844813.dita
db/derby/docs/trunk/src/devguide/cdevdeploy11201.dita
db/derby/docs/trunk/src/devguide/cdevdeploy15818.dita
db/derby/docs/trunk/src/devguide/cdevdvlp25889.dita
db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita
db/derby/docs/trunk/src/devguide/cdevdvlp27715.dita
db/derby/docs/trunk/src/devguide/cdevdvlp39943.dita
db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita
db/derby/docs/trunk/src/devguide/cdevdvlp846402.dita
db/derby/docs/trunk/src/devguide/derbydev.ditamap
db/derby/docs/trunk/src/devguide/tdevpreupgrade.dita
db/derby/docs/trunk/src/devguide/tdevupgradedb.dita
db/derby/docs/trunk/src/devguide/tdevupgradesoft.dita
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts50894.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts50894.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts50894.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts50894.dita Sun Oct 1 13:20:51 2006
@@ -27,8 +27,7 @@
<p><ph conref="devconrefs.dita#prod/productshortname"></ph> provides a class
to help you in this situation, <i>org.apache.derby.diag.LockTable</i>. You
can also set the property <i>derby.locks.deadlockTrace</i> to dump additional
-information to the <ph conref="devconrefs.dita#prod/productshortname"></ph>.log
-file about any deadlocks that occur on your system. See the Tuning Guide for
-more information on this property. For information, see the <cite><ph conref="devconrefs.dita#pub/citadmin"></ph></cite>.</p>
+information to the derby.log file about any deadlocks that occur on your system.
+See the Tuning Guide for more information on this property. For information, see the <cite><ph conref="devconrefs.dita#pub/citadmin"></ph></cite>.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevconcepts844813.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevconcepts844813.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevconcepts844813.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevconcepts844813.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -19,19 +19,19 @@
limitations under the License.
-->
<concept id="cdevconcepts844813" xml:lang="en-us">
-<title>Information provided in SQLExceptions</title>
+<title>Information provided in SQL Exceptions</title>
<shortdesc><ph conref="devconrefs.dita#prod/productshortname"></ph> provides
-the message, <i>SQLState</i> values, and error codes.</shortdesc>
+the message, <i>SQLState</i> values, and error codes in SQL exceptions.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>SQLWarnings</indexterm><indexterm>SQLExceptions<indexterm>chaining
-of</indexterm></indexterm><indexterm>Processing SQLExceptions</indexterm>
-</keywords>
+<keywords><indexterm>SQL warnings</indexterm><indexterm>SQL exceptions<indexterm>chaining</indexterm></indexterm>
+<indexterm>SQL exceptions<indexterm>processing</indexterm></indexterm></keywords>
</metadata></prolog>
<conbody>
<p>Use the <codeph><i>getSQLState</i></codeph> and <codeph><i>getMessage</i></codeph> methods
to view the <codeph><i>SQLState</i></codeph> and error messages. Use <codeph><i>getErrorCode</i></codeph> to
see the error code. The error code defines the severity of the error and is
-not unique to each exception. The severity levels are described in<codeph><i>org.apache.derby.types.ExceptionSeverity</i></codeph>.</p>
+not unique to each exception. <note>Severity is not standardized in <ph conref="devconrefs.dita#prod/productshortname"></ph>.
+Applications should not depend on the severity returned from SQL exceptions.</note></p>
<p>Applications should also check for and process <i>java.sql.SQLWarnings</i>,
which are processed in a similar way. <ph conref="devconrefs.dita#prod/productshortname"></ph> issues
an <codeph><i>SQLWarning</i></codeph> if the <codeph><i>create=true</i></codeph> attribute
Modified: db/derby/docs/trunk/src/devguide/cdevdeploy11201.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdeploy11201.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdeploy11201.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdeploy11201.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -22,7 +22,7 @@
<title>Accessing a read-only database in a zip/jar file</title>
<shortdesc>To access a database in a zip/jar, you specify the jar in the subsubprotocol.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Read-only databases<indexterm>accessing in zip/jar files</indexterm></indexterm>
+<keywords><indexterm>read-only databases<indexterm>accessing in zip/jar files</indexterm></indexterm>
</keywords>
</metadata></prolog>
<conbody>
@@ -38,7 +38,5 @@
<codeblock>jdbc:derby:jar:(C:/dbs.jar)/products/boiledfood</codeblock>
<p>Databases in a jar or zip file are always opened read-only and there is
currently no support to allow updates of any type.</p>
-<p>Databases in a jar or zip file are not booted automatically when <ph conref="devconrefs.dita#prod/productshortname"></ph> is
-started, unless they are explicitly listed as <i>derby.service</i> properties.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevdeploy15818.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdeploy15818.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdeploy15818.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdeploy15818.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -20,16 +20,17 @@
-->
<concept id="cdevdeploy15818" xml:lang="en-us">
<title>Create jar files for your application</title>
-<shortdesc>Include any Java classes in a jar file intended for <ph conref="devconrefs.dita#prod/productshortname"></ph> class
-loading except these.</shortdesc>
+<shortdesc>Include any Java classes in a jar file that are intended for <ph
+conref="devconrefs.dita#prod/productshortname"></ph> class loading, except
+the following classes:</shortdesc>
<prolog></prolog>
<conbody>
<ul>
-<li>the standard Java packages (<i>java.*</i>, <codeph><i>javax.*</i></codeph>)
+<li>The standard Java packages (<i>java.*</i>, <codeph><i>javax.*</i></codeph>)
<p><ph conref="devconrefs.dita#prod/productshortname"></ph> does not prevent
you from storing such a jar file in the database, but these classes <i>are
never loaded</i> from the jar file.</p></li>
-<li>those supplied with your Java environment (for example, <i>sun.*</i>)</li>
+<li>The classes that are supplied with your Java environment (for example, <i>sun.*</i>)</li>
</ul>
<p>A running <ph conref="devconrefs.dita#prod/productshortname"></ph> system
can load classes from any number of jar files from any number of schemas and
@@ -43,15 +44,14 @@
you have a choice:</p>
<ul>
<li><i>Extract the required third-party classes from their jar file and include
-only those in your jar file.</i> <p>Best if you need only a small subset
-of the classes in the third-party jar file.</p></li>
-<li><i>Store the third-party jar file in the database.</i> <p>Best if you
-need most or all of the classes in the third-party jar file, since your application
-and third-party logic can be upgraded separately.</p></li>
-<li><i>Deploy the third-party jar file in the user's class path.</i> <p>Best
-if the classes are often already installed on a user's machine (for example,
-Objectspace's JGL classes).</p></li>
+only those classes in your jar file.</i> <p>Use this option when you need
+only a small subset of the classes in the third-party jar file.</p></li>
+<li><i>Store the third-party jar file in the database.</i> <p>Use this option
+when you need most or all of the classes in the third-party jar file, since
+your application and third-party logic can be upgraded separately.</p></li>
+<li><i>Deploy the third-party jar file in the user's class path.</i> <p>Use
+this option when the classes are already installed on a user's machine (for
+example, Objectspace's JGL classes).</p></li>
</ul>
-<p>Include the class files and resources needed for your application.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp25889.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp25889.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp25889.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp25889.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -21,7 +21,7 @@
<concept id="cdevdvlp25889" xml:lang="en-us">
<title>The error log</title>
<shortdesc>Once you create or connect to a database within a system, <ph conref="devconrefs.dita#prod/productshortname"></ph> begins
-outputting information and error messages, if any.</shortdesc>
+outputting information and error messages to the error log.</shortdesc>
<prolog><metadata>
<keywords><indexterm>Error log<indexterm>description</indexterm></indexterm>
</keywords>
@@ -30,9 +30,10 @@
<p>Typically, <ph conref="devconrefs.dita#prod/productshortname"></ph> writes
this information to a log called <i>derby.log</i> in the system directory,
although you can also have <ph conref="devconrefs.dita#prod/productshortname"></ph> send
-messages to a stream, using a property. By default, <ph conref="devconrefs.dita#prod/productshortname"></ph> overwrites <i>derby.log</i> when
+messages to a stream, using the <codeph>derby.stream.error.method</codeph> property.
+By default, <ph conref="devconrefs.dita#prod/productshortname"></ph> overwrites <i>derby.log</i> when
you start the system. You can configure <ph conref="devconrefs.dita#prod/productshortname"></ph> to
-append to the log with the <codeph><i>derby.infolog.append</i></codeph> property.
+append to the log with the <codeph>derby.infolog.append</codeph> property.
For information on setting this and other properties, see <cite><ph conref="devconrefs.dita#pub/cittuning"></ph></cite>.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp27610.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -53,9 +53,6 @@
href="cdevdvlp25889.dita#cdevdvlp25889"></xref>).</p>
<p>Each database within that system is contained in a subdirectory, which
has the same name as the database (see <xref href="cdevdvlp21955.dita#cdevdvlp21955"></xref>).</p>
-<p>You can use a property (see <i>"derby.service" </i> in <cite><ph conref="devconrefs.dita#pub/cittuning"></ph></cite>)
-to include databases in other directories or in subdirectories of the system
-directory in the current system when you start it up.</p>
<p>In addition, if you connect to a database outside the current system, it
automatically becomes part of the current system.</p>
</conbody>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp27715.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp27715.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp27715.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp27715.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -39,10 +39,11 @@
it remains active until the <ph conref="devconrefs.dita#prod/productshortname"></ph> system
has been shut down or until you shut down the database individually.</p>
<p>When <ph conref="devconrefs.dita#prod/productshortname"></ph> boots a database,
-it prints a message in the error log:</p>
-<codeblock>2005-06-10 03:54:06.196 GMT: Booting <ph conref="devconrefs.dita#prod/productshortname"></ph> version <ph
+a message is added to the error log. The message includes the <ph conref="devconrefs.dita#prod/productshortname"></ph> version
+that the database was booted with, for example:</p>
+<codeblock>2006-10-04 03:54:06.196 GMT: Booting <ph conref="devconrefs.dita#prod/productshortname"></ph> version <ph
conref="devconrefs.dita#prod/productlongname"></ph>
-- 10.0.0.1 - (29612): instance c013800d-00fd-0cb0-e736-ffffd1025a25 on
+- 10.2.1.5 - (448900): instance c013800d-00fd-0cb0-e736-ffffd1025a25 on
database directory sample</codeblock>
<p>The number of databases running in a <ph conref="devconrefs.dita#prod/productshortname"></ph> system
is limited only by the amount of memory available in the JVM.</p>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp39943.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp39943.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp39943.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp39943.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -21,15 +21,16 @@
<concept id="cdevdvlp39943" xml:lang="en-us">
<title>derby.properties</title>
<shortdesc>The text file <i>derby.properties</i> contains the definition of
-properties, or configuration parameters valid for the entire system.</shortdesc>
+properties, or configuration parameters that are valid for the entire system.</shortdesc>
<prolog><metadata>
<keywords><indexterm>derby.properties file</indexterm></keywords>
</metadata></prolog>
<conbody>
-<p>This file is not automatically created; if you wish to set <ph conref="devconrefs.dita#prod/productshortname"></ph> properties
-with this file, you need to create it yourself. The file should be in the
-format created by the <codeph><i>java.util.Properties.save</i></codeph> method.
-For more information about properties and the <ph conref="devconrefs.dita#prod/productshortname"></ph>.properties
-file, see <cite><ph conref="devconrefs.dita#pub/cittuning"></ph></cite>.</p>
+<p>The <i>derby.properties</i> file is not automatically created. If you want
+to set <ph conref="devconrefs.dita#prod/productshortname"></ph> properties
+with this file, you need to create the file yourself. The <i>derby.properties</i> file
+should be in the format created by the <codeph><i>java.util.Properties.save</i></codeph> method.
+For more information about properties and the <i>derby.properties</i> file,
+see <cite><ph conref="devconrefs.dita#pub/cittuning"></ph></cite>.</p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -22,9 +22,8 @@
<title>Derby JDBC driver</title>
<shortdesc><ph conref="devconrefs.dita#prod/productshortname"></ph> consists
of both the database engine and an embedded JDBC driver. Applications use
-JDBC to interact with a database. Applications running on JDK 1.5 or
-earlier, must load the driver in order
-to work with the database.</shortdesc>
+JDBC to interact with a database. Applications running on JDK 1.5 or earlier,
+must load the driver in order to work with the database.</shortdesc>
<prolog><metadata>
<keywords><indexterm>JDBC driver<indexterm>description</indexterm></indexterm>
</keywords>
@@ -37,11 +36,9 @@
Class.forName("org.apache.derby.jdbc.EmbeddedDriver");
</codeblock>
<p>For detailed information about loading the <ph conref="devconrefs.dita#prod/productshortname"></ph> JDBC
-driver, see <i>"java.sql.Driver" </i> in the <cite><ph conref="devconrefs.dita#pub/citref"></ph></cite><cite>.</cite><ph> See
-also javadoc for org.apache.derby.util.DriverUtil.</ph></p>
-<p>
-If your application runs on JDK 1.6 or higher, then you do not need to
-explicitly load the EmbeddedDriver. In that environment, the driver loads automatically.
-</p>
+driver, see <i>"java.sql.Driver" </i> in the <cite><ph conref="devconrefs.dita#pub/citref"></ph></cite>.</p>
+<p> If your application runs on JDK 1.6 or higher, then you do not need to
+explicitly load the EmbeddedDriver. In that environment, the driver loads
+automatically. </p>
</conbody>
</concept>
Modified: db/derby/docs/trunk/src/devguide/cdevdvlp846402.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp846402.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp846402.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp846402.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
"../dtd/concept.dtd">
<!--
@@ -25,14 +25,10 @@
path name to identify the database. The way you specify an absolute path is
defined by the host operating system.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Databases<indexterm>connecting to outside system</indexterm></indexterm>
+<keywords><indexterm>databases<indexterm>connecting to outside system</indexterm></indexterm>
</keywords>
</metadata></prolog>
<conbody>
-<p>You must specify a path for a database in a directory other than the system
-directory even if you have defined the <codeph><i>derby.service</i></codeph> property
-to have <ph conref="devconrefs.dita#prod/productshortname"></ph> boot the
-database automatically (see <i>"derby.service"</i> in <cite><ph conref="devconrefs.dita#pub/cittuning"></ph></cite>).</p>
<p>Using the connection URL as described here, you can connect to databases
in more than one directory at a time.</p>
<p>Two examples:</p>
Modified: db/derby/docs/trunk/src/devguide/derbydev.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/derbydev.ditamap?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/derbydev.ditamap (original)
+++ db/derby/docs/trunk/src/devguide/derbydev.ditamap Sun Oct 1 13:20:51 2006
@@ -37,7 +37,8 @@
</relcell>
<relcell>
<topicref href="tdevupgradedb.dita" navtitle="Upgrading a database"></topicref>
-<topicref href="tdevupgradesoft.dita" navtitle="Soft upgrade"></topicref>
+<topicref href="tdevupgradesoft.dita" navtitle="Soft upgrade limitations">
+</topicref>
</relcell>
</relrow>
<relrow>
@@ -45,8 +46,16 @@
<topicref href="tdevupgradedb.dita" navtitle="Upgrading a database"></topicref>
</relcell>
<relcell>
-<topicref href="tdevupgradesoft.dita" navtitle="Soft upgrade"></topicref>
+<topicref href="tdevupgradesoft.dita" navtitle="Soft upgrade limitations">
+</topicref>
</relcell>
+</relrow>
+<relrow>
+<relcell>
+<topicref href="tdevupgradesoft.dita" navtitle="Soft upgrade limitations">
+</topicref>
+</relcell>
+<relcell></relcell>
</relrow>
<relrow>
<relcell>
Modified: db/derby/docs/trunk/src/devguide/tdevpreupgrade.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevpreupgrade.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevpreupgrade.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevpreupgrade.dita Sun Oct 1 13:20:51 2006
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
-
+
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
"../dtd/task.dtd">
<!--
@@ -20,20 +20,27 @@
-->
<task id="tdevpreupgrade" xml:lang="en-us">
<title>Preparing to upgrade</title>
-<shortdesc>Upgrading occurs the first time the new <ph conref="devconrefs.dita#prod/productshortname"></ph> software
+<shortdesc>Upgrading your database occurs the first time the new <ph conref="devconrefs.dita#prod/productshortname"></ph> software
connects to the old database.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Upgrading Derby<indexterm>prerequisites</indexterm></indexterm>
+<keywords><indexterm>upgrading Derby<indexterm>prerequisites</indexterm></indexterm>
</keywords>
</metadata></prolog>
<taskbody>
-<context> <p>Before connecting with the new software:</p></context>
+<context> <p>Before you connect to the database using the new software:</p></context>
<steps>
<step><cmd>Back up your database to a safe location using <ph conref="devconrefs.dita#prod/productshortname"></ph> online/offline
backup procedures.</cmd><info>For more information on backup, see the <ph
-conref="devconrefs.dita#pub/citadmin"></ph>.</info><stepresult>If you do not
-perform a soft upgrade, then once the database is upgraded, it cannot be reverted
-back to the previous version.</stepresult></step>
+conref="devconrefs.dita#pub/citadmin"></ph>.</info></step>
+<step><cmd>Update your CLASSPATH with the latest jar files.</cmd></step>
+<step><cmd>Make sure that there are no older versions of the <ph conref="devconrefs.dita#prod/productshortname"></ph> jar
+files in your CLASSPATH. You can determine if you have multiple versions of <ph conref="devconrefs.dita#prod/productshortname"></ph> in your CLASSPATH by using the sysinfo tool.</cmd>
+<stepxmp>To use the <codeph>sysinfo</codeph> tool,
+execute the following command:<codeblock>java org.apache.derby.tools.sysinfo</codeblock>The <codeph>sysinfo</codeph> tool
+uses information found in the <ph conref="devconrefs.dita#prod/productshortname"></ph> jar
+files to determine the version of any <ph conref="devconrefs.dita#prod/productshortname"></ph> jar in your CLASSPATH. Be sure that you have only one version of
+the <ph conref="devconrefs.dita#prod/productshortname"></ph> jar files specified
+in your CLASSPATH.</stepxmp></step>
</steps>
</taskbody>
</task>
Modified: db/derby/docs/trunk/src/devguide/tdevupgradedb.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevupgradedb.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevupgradedb.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevupgradedb.dita Sun Oct 1 13:20:51 2006
@@ -1,4 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
+
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
"../dtd/task.dtd">
<!--
@@ -20,26 +21,46 @@
<task id="tdevupgradedb" xml:lang="en-us">
<title>Upgrading a database</title>
<shortdesc>To upgrade a database, you must explicitly request an upgrade the
-first time you connect to it with the new version of <ph conref="devconrefs.dita#prod/productshortname"></ph>.</shortdesc>
+first time you connect to the database with the new version of <ph conref="devconrefs.dita#prod/productshortname"></ph>.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Upgrading Derby</indexterm></keywords>
+<keywords><indexterm>upgrading Derby<indexterm>full upgrade</indexterm></indexterm>
+<indexterm>upgrading Derby<indexterm>soft upgrade</indexterm></indexterm>
+<indexterm>upgrading Derby<indexterm>types of upgrades</indexterm></indexterm>
+<indexterm>full upgrade</indexterm><indexterm>soft upgrade</indexterm></keywords>
</metadata></prolog>
<taskbody>
-<prereq>Do not attempt to upgrade a database without first backing it up.</prereq>
-<context> <p>To request an upgrade when connecting to the database:</p></context>
+<prereq>Ensure that you <xref href="tdevpreupgrade.dita">complete the prerequisite
+steps</xref> before you upgrade:<ul>
+<li>Back up your database before you upgrade.</li>
+<li>Ensure that only the new <ph conref="devconrefs.dita#prod/productshortname"></ph> jar
+files are in your CLASSPATH.</li>
+</ul></prereq>
+<context> <p>When you upgrade the database, you can perform a full upgrade
+or soft upgrade:<ul>
+<li>A full upgrade is a complete upgrade of the <ph conref="devconrefs.dita#prod/productshortname"></ph> database.
+When you perform a full upgrade, you cannot connect to the database with an
+older version of <ph conref="devconrefs.dita#prod/productshortname"></ph> and
+you cannot revert back to the previous version. </li>
+<li>A soft upgrade allows you to run a newer version of <ph conref="devconrefs.dita#prod/productshortname"></ph> against
+an existing database without having to fully upgrade the database. This means
+that you can continue to run an older version of <ph conref="devconrefs.dita#prod/productshortname"></ph> against
+the database. However, if you perform a soft upgrade, certain features will
+not be available to you until you perform a full upgrade.</li>
+</ul></p></context>
<steps>
-<step><cmd>Use the <codeph>upgrade=true</codeph> database connection URL attribute,
-as shown in the following example:</cmd><info><codeblock>jdbc:derby:sample;upgrade=true</codeblock></info>
-<stepresult>Once the upgrade is complete, you cannot connect to the database
-with an older version of <ph conref="devconrefs.dita#prod/productshortname"></ph>.</stepresult>
+<step><cmd>To upgrade the database, select the type of upgrade that you want
+to perform:</cmd>
+<choicetable>
+<chhead><choptionhd>Type of upgrade</choptionhd><chdeschd>Action</chdeschd>
+</chhead>
+<chrow><choption>Full upgrade</choption><chdesc>Connect to the database using
+the <codeph>upgrade=true</codeph> database connection URL attribute. For example:<codeblock>jdbc:derby:sample;upgrade=true</codeblock></chdesc>
+</chrow>
+<chrow><choption>Soft upgrade</choption><chdesc>Connect to the database. For
+example: <codeblock>connect 'jdbc:derby:sample'</codeblock>In this example, <codeph>sample</codeph> is
+a database from a previous version of Derby.</chdesc></chrow>
+</choicetable>
</step>
</steps>
-<result>You can find out the version of <ph conref="devconrefs.dita#prod/productshortname"></ph> using
-sysinfo:<codeblock>java org.apache.derby.tools.sysinfo</codeblock>Note that
-this is the version of <ph conref="devconrefs.dita#prod/productshortname"></ph>,
-not the version of the database. Sysinfo uses information found in the <ph
-conref="devconrefs.dita#prod/productshortname"></ph> jar files, so verify
-that only one version of <ph conref="devconrefs.dita#prod/productshortname"></ph>'s
-jar files are in your class path when you run this tool.</result>
</taskbody>
</task>
Modified: db/derby/docs/trunk/src/devguide/tdevupgradesoft.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevupgradesoft.dita?view=diff&rev=451802&r1=451801&r2=451802
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevupgradesoft.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevupgradesoft.dita Sun Oct 1 13:20:51 2006
@@ -1,4 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
+
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
"../dtd/task.dtd">
<!--
@@ -18,40 +19,33 @@
limitations under the License.
-->
<task id="tdevupgradesoft" xml:lang="en-us">
-<title>Soft upgrade</title>
+<title>Soft upgrade limitations</title>
<shortdesc>Soft upgrade allows you to run a newer version of <ph conref="devconrefs.dita#prod/productshortname"></ph> against
an existing database without having to fully upgrade the database. This means
that you can continue to run an older version of <ph conref="devconrefs.dita#prod/productshortname"></ph> against
the database.</shortdesc>
<prolog><metadata>
-<keywords><indexterm>Soft upgrade</indexterm><indexterm>Upgrading Derby<indexterm>Soft
-upgrade</indexterm></indexterm></keywords>
+<keywords><indexterm>soft upgrade<indexterm>limitations</indexterm></indexterm>
+<indexterm>upgrading Derby<indexterm>limitations, soft upgrade</indexterm></indexterm>
+</keywords>
</metadata></prolog>
<taskbody>
<context> <p>If you perform a soft upgrade, you will not be able to perform
certain functions that are not available in older versions of <ph conref="devconrefs.dita#prod/productshortname"></ph>.
For example, the following <ph conref="devconrefs.dita#prod/productshortname"></ph> Version
-10.2 features cannot be used in a database that has been soft upgraded
-from 10.0:
-</p>
-<ul>
+10.2 features cannot be used in a database that has been soft upgraded from
+10.0: </p> <ul>
<li>SYNONYMS</li>
<li>Creating tables using the GENERATED BY DEFAULT option for identity columns</li>
<li>Reclaiming unused space using the SYSCS_UTIL.SYSCS_INPLACE_COMPRESS_TABLE
procedure</li>
-</ul>
-<p>
-The following 10.2 features cannot be accessed from a database which
-has been soft upgraded from 10.1:
-</p>
-<ul>
+</ul> <p> The following 10.2 features cannot be accessed from a database which
+has been soft upgraded from 10.1: </p><ul>
<li>GRANT/REVOKE</li>
-<li>Online backup procedures
-SYSCS_UTIL.SYSCS_ONLINE_BACKUP_DATABASE_NOWAIT and SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT.</li>
+<li>Online backup procedures SYSCS_UTIL.SYSCS_BACKUP_DATABASE_NOWAIT and
+SYSCS_UTIL.SYSCS_BACKUP_DATABASE_AND_ENABLE_LOG_ARCHIVE_MODE_NOWAIT.</li>
<li>The encryption or re-encryption of a database with a new phrase/key.</li>
-</ul>
-<p>
-Other new features in <ph conref="devconrefs.dita#prod/productshortname"></ph> that
+</ul> <p> Other new features in <ph conref="devconrefs.dita#prod/productshortname"></ph> that
do not affect database structure, such as using timestamp arithmetic, are
allowed in a soft upgraded database.</p><p>To perform a soft upgrade on a
database created using an earlier version of <ph conref="devconrefs.dita#prod/productshortname"></ph>:</p></context>