db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r689598 - in /db/derby/docs/trunk/src: adminguide/ devguide/ ref/
Date Wed, 27 Aug 2008 20:20:15 GMT
Author: chaase3
Date: Wed Aug 27 13:20:15 2008
New Revision: 689598

URL: http://svn.apache.org/viewvc?rev=689598&view=rev
Log:
DERBY-503:  Documentation should recommend using .newInstance() to instantiate JDBC driver

Modified 4 Admin Guide topics, 3 Developer's Guide topics, and 3 Reference Manual topics.
The topics describe when to use .newInstance() and use it only when it is required.

Patch: DERBY-503-2.diff

Modified:
    db/derby/docs/trunk/src/adminguide/cadminappsxawthdriver.dita
    db/derby/docs/trunk/src/adminguide/cadminembeddedserver.dita
    db/derby/docs/trunk/src/adminguide/radminappsclientxmp.dita
    db/derby/docs/trunk/src/adminguide/radminembeddedserverex.dita
    db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita
    db/derby/docs/trunk/src/devguide/tdevdvlp20349.dita
    db/derby/docs/trunk/src/devguide/tdevdvlp36289.dita
    db/derby/docs/trunk/src/ref/rrefclob.dita
    db/derby/docs/trunk/src/ref/rrefjdbc32052.dita
    db/derby/docs/trunk/src/ref/rrefjdbc4_0summary.dita

Modified: db/derby/docs/trunk/src/adminguide/cadminappsxawthdriver.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminappsxawthdriver.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminappsxawthdriver.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminappsxawthdriver.dita Wed Aug 27 13:20:15 2008
@@ -44,17 +44,14 @@
 XAConnection xaConnection = null;
 Connection conn = null;
 
-String driver = "org.apache.derby.jdbc.ClientDataSource";
 ClientXADataSource ds = new ClientXADataSource();
 
-ds.setDatabaseName ("sample;create=true");
+ds.setDatabaseName ("sample");
+ds.setCreateDatabase("create");
 
 ds.setServerName("localhost");
-
 ds.setPortNumber(1527);
 
-Class.forName(driver);
-
 xaConnection = ds.getXAConnection("auser", "shhhh");
 
 conn = xaConnection.getConnection();</codeblock></example>

Modified: db/derby/docs/trunk/src/adminguide/cadminembeddedserver.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminembeddedserver.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/cadminembeddedserver.dita (original)
+++ db/derby/docs/trunk/src/adminguide/cadminembeddedserver.dita Wed Aug 27 13:20:15 2008
@@ -24,14 +24,13 @@
 <p>In one thread, the embedding application starts the local JDBC driver for
 its own access.</p>
 <codeblock>/*
-    If you are running on JDK 1.6 or higher, then you do not
+    If you are running on JDK 6 or higher, you do not
     need to invoke Class.forName(). In that environment, the
     EmbeddedDriver loads automatically.
 */
-Class.forName("org.apache.derby.jdbc.EmbeddedDriver").newInstance();
+Class.forName("org.apache.derby.jdbc.EmbeddedDriver");
 Connection conn = DriverManager.getConnection(
     "jdbc:derby:sample");
-
 </codeblock>
 <p>In another thread, the same application starts the server framework to allow
 remote access. Starting the server framework from within the application allows

Modified: db/derby/docs/trunk/src/adminguide/radminappsclientxmp.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/radminappsclientxmp.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/radminappsclientxmp.dita (original)
+++ db/derby/docs/trunk/src/adminguide/radminappsclientxmp.dita Wed Aug 27 13:20:15 2008
@@ -50,17 +50,17 @@
 <section><title>Example 4</title><p>The following example shows how
to use
 the network client driver to connect the network client to the Network Server:</p><codeblock>String
databaseURL = "jdbc:derby://localhost:1527/sample";
 <b>//
-// Load Derby Network Client driver class
-// If you are running on JDK 1.6 or higher, then you do not
+// Load Derby Network Client driver class.
+// If you are running on JDK 6 or higher, you do not
 // need to invoke Class.forName(). In that environment, the
 // network client driver loads automatically.
 //</b>
 Class.forName("org.apache.derby.jdbc.ClientDriver");
 <b>// Set user and password properties</b>
 Properties properties = new Properties();
-properties.put("user", "judy");
-properties.put("password", "no12see");
+properties.setProperty("user", "judy");
+properties.setProperty("password", "no12see");
 <b>// Get a connection</b>
-Connection conn = DriverManager.getConnection(databaseURL, properties); </codeblock></section>
+Connection conn = DriverManager.getConnection(databaseURL, properties);</codeblock></section>
 </refbody>
 </reference>

Modified: db/derby/docs/trunk/src/adminguide/radminembeddedserverex.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/radminembeddedserverex.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/adminguide/radminembeddedserverex.dita (original)
+++ db/derby/docs/trunk/src/adminguide/radminembeddedserverex.dita Wed Aug 27 13:20:15 2008
@@ -40,15 +40,15 @@
 driver:</p></section>
 <section><p> <codeblock>String nsURL="jdbc:derby://localhost:1527/sample";
 
 java.util.Properties props = new java.util.Properties();
-props.put("user","usr");
-props.put("password","pwd");
+props.setProperty("user","usr");
+props.setProperty("password","pwd");
 
 /*
-    If you are running on JDK 1.6 or higher, then you do not
+    If you are running on JDK 6 or higher, you do not
     need to invoke Class.forName(). In that environment, the
-    EmbeddedDriver loads automatically.
+    ClientDriver loads automatically.
 */
-Class.forName("org.apache.derby.jdbc.ClientDriver").newInstance();
+Class.forName("org.apache.derby.jdbc.ClientDriver");
 Connection conn = DriverManager.getConnection(nsURL, props);
 
 /*interact with <ph conref="../conrefs.dita#prod/productshortname"></ph>*/
@@ -58,4 +58,3 @@
 "SELECT * FROM HotelBookings");</codeblock></p></section>
 </refbody>
 </reference>
-

Modified: db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita (original)
+++ db/derby/docs/trunk/src/devguide/cdevdvlp40653.dita Wed Aug 27 13:20:15 2008
@@ -22,7 +22,7 @@
 <title>Derby JDBC driver</title>
 <shortdesc><ph conref="../conrefs.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,
+JDBC to interact with a database. Applications running on JDK 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>
@@ -33,16 +33,19 @@
 <p>The <ph conref="../conrefs.dita#prod/productshortname"></ph> driver
 class name for the embedded environment is <i>org.apache.derby.jdbc.EmbeddedDriver</i>.</p>
 <p>In a Java application, you typically load the driver with the static <i>Class.forName</i>
method
-or with the <codeph><i>jdbc.drivers</i></codeph> system property.
For example:</p>
+or with the <i>jdbc.drivers</i> system property. For example:</p>
 <codeblock>
 Class.forName("org.apache.derby.jdbc.EmbeddedDriver");
 </codeblock>
-<codeblock>java -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver <i>applicationClass</i>
+<codeblock>java -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver<i> applicationClass</i>
 </codeblock>
 <p>For detailed information about loading the <ph conref="../conrefs.dita#prod/productshortname"></ph>
JDBC
 driver, see "java.sql.Driver interface" in the <cite><ph conref="../conrefs.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>
+<p>If your application runs on JDK 6 or higher, you do not need to
+explicitly load the <codeph>EmbeddedDriver</codeph>. In that environment, the
+driver loads automatically.</p>
+<p>If your application shuts down Derby or calls the <i>DriverManager.unload</i>
+method, and you then want to reload the driver, call the
+<i>Class.forName().newInstance()</i> method.</p>
 </conbody>
 </concept>

Modified: db/derby/docs/trunk/src/devguide/tdevdvlp20349.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevdvlp20349.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevdvlp20349.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevdvlp20349.dita Wed Aug 27 13:20:15 2008
@@ -27,28 +27,26 @@
 </metadata></prolog>
 <taskbody>
 <context> <p>If the application that started the embedded <ph conref="../conrefs.dita#prod/productshortname"></ph>
quits
-but leaves the JVM running, <ph conref="../conrefs.dita#prod/productshortname"></ph>
continues
+but leaves the Java Virtual Machine (JVM) running, <ph conref="../conrefs.dita#prod/productshortname"></ph>
continues
 to run and is available for database connections.</p><p>In an embedded system,
 the application shuts down the <ph conref="../conrefs.dita#prod/productshortname"></ph>
system
 by issuing the following JDBC call:</p><codeblock>DriverManager.getConnection("jdbc:derby:;shutdown=true");</codeblock><p>Shutdown
 commands always raise <i>SQLExceptions</i>.</p><p>When a <ph conref="../conrefs.dita#prod/productshortname"></ph>
system
-shuts down, a message goes to the error log:</p><codeblock>Sat Jan 10 14:31:54
PDT 2005:
+shuts down, a message goes to the error log:</p><codeblock>2008-08-07 19:23:00.508
GMT:
 Shutting down instance 80000001-00d0-8bdf-d115-000a0a0b2d00</codeblock><p>Typically,
 an application using an embedded <ph conref="../conrefs.dita#prod/productshortname"></ph>
engine
 shuts down <ph conref="../conrefs.dita#prod/productshortname"></ph> just before
 shutting itself down. However, an application can shut down <ph conref="../conrefs.dita#prod/productshortname"></ph>
and
 later restart it in the same JVM session. To restart <ph conref="../conrefs.dita#prod/productshortname"></ph>
successfully,
-the JVM needs to unload <i>org.apache.derby.jdbc.EmbeddedDriver</i>, so that
-it can reload it when it restarts <ph conref="../conrefs.dita#prod/productshortname"></ph>.
-(Loading the local driver starts <ph conref="../conrefs.dita#prod/productshortname"></ph>.)
</p><p>You
-cannot request that the JVM unload a specific class, but you can ask it to
-unload the <i>EmbeddedDriver</i> class by calling
-<codeph><i>System.gc()</i></codeph> to request it to garbage collect
classes
-that are no longer needed. Running with the non-standard option 
-<codeph><i>-Xnoclassgc</i></codeph> definitely <i>prevents</i>
the class from
-being unloaded and makes you unable to restart <ph
-conref="../conrefs.dita#prod/productshortname"></ph> in the same JVM. </p><p>It
-is also possible to shut down a single database instead of the entire <ph
+the application needs to reload <i>org.apache.derby.jdbc.EmbeddedDriver</i> as
+follows:</p>
+<codeblock>Class.forName(org.apache.derby.jdbc.EmbeddedDriver).newInstance();</codeblock>
+<p>Loading the embedded driver starts Derby.</p>
+<p>The JDBC specification does not recommend calling
+<codeph>newInstance()</codeph>, but adding a <codeph>newInstance()</codeph>
call
+guarantees that <ph conref="../conrefs.dita#prod/productshortname"></ph> will
be
+booted on any JVM.</p>
+<p>It is also possible to shut down a single database instead of the entire <ph
 conref="../conrefs.dita#prod/productshortname"></ph> system. See <xref href="tdevdvlp40464.dita#tdevdvlp40464"></xref>.
 You can reboot a database in the same <ph conref="../conrefs.dita#prod/productshortname"></ph>
session
 after shutting it down.</p></context>

Modified: db/derby/docs/trunk/src/devguide/tdevdvlp36289.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/devguide/tdevdvlp36289.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/devguide/tdevdvlp36289.dita (original)
+++ db/derby/docs/trunk/src/devguide/tdevdvlp36289.dita Wed Aug 27 13:20:15 2008
@@ -21,25 +21,34 @@
 <task id="tdevdvlp36289" xml:lang="en-us">
 <title>Specifying attributes in a properties object</title>
 <shortdesc>Instead of specifying attributes on the connection URL, you can
-specify attributes as properties in a <i>Properties</i> object that you pass
-as a second argument to the <codeph><i>DriverManager.getConnection</i></codeph>
method.</shortdesc>
+specify attributes as properties in a <codeph>Properties</codeph> object that
you pass
+as a second argument to the <codeph>DriverManager.getConnection</codeph> method.</shortdesc>
 <prolog><metadata>
 <keywords><indexterm>Attributes (URL), setting as properties</indexterm><indexterm>Attributes
 to database connection URL<indexterm>specifying with Properties object</indexterm></indexterm>
 </keywords>
 </metadata></prolog>
 <taskbody>
-<context> <p>For example, to set the user name and password:</p><codeblock>Class.forName("org.apache.derby.jdbc.EmbeddedDriver");
+<context> <p>For example, to set the user name and password:</p>
+<codeblock>Class.forName("org.apache.derby.jdbc.EmbeddedDriver");
 
 Properties p = new Properties();
 
-p.put("user", "sa");
-
-p.put("password", "manager");
-
+p.setProperty("user", "sa");
+p.setProperty("password", "manager");
+p.setProperty("create", "true");
 
 Connection conn = DriverManager.getConnection(
-
-    "jdbc:derby:mynewDB", p);</codeblock></context>
+    "jdbc:derby:mynewDB", p);</codeblock>
+<p>If you are running on JDK 6 or higher, you do not normally need to invoke
+<codeph>Class.forName()</codeph>. In that environment, the
+<codeph>EmbeddedDriver</codeph> loads automatically. The only exception to this
+rule is when you need to shut down
+<ph conref="../conrefs.dita#prod/productshortname"></ph> in the middle of your
+application and then restart it. To restart
+<ph conref="../conrefs.dita#prod/productshortname"></ph>, create a new instance
+of the driver as follows:</p>
+<codeblock>Class.forName("org.apache.derby.jdbc.EmbeddedDriver").newInstance();</codeblock>
+</context>
 </taskbody>
 </task>

Modified: db/derby/docs/trunk/src/ref/rrefclob.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefclob.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefclob.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefclob.dita Wed Aug 27 13:20:15 2008
@@ -41,15 +41,20 @@
 
 public class clob
 {
-	public static void main(String[] args) {
-		try {
-			String url = "jdbc:derby:clobberyclob;create=true";
+    public static void main(String[] args) {
+        try {
+            String url = "jdbc:derby:clobberyclob;create=true";
+
+            // Load the driver. This code is not needed if you are using 
+            // JDK 6, because in that environment the driver is loaded 
+            // automatically when the application requests a connection.
+            Class.forName("org.apache.derby.jdbc.EmbeddedDriver");
 
-			Class.forName("org.apache.derby.jdbc.EmbeddedDriver").newInstance();
-			Connection conn = DriverManager.getConnection(url);
+            Connection conn = DriverManager.getConnection(url);
 
             Statement s = conn.createStatement();
-            s.executeUpdate("CREATE TABLE documents (id INT, text CLOB(64 K))");
+            s.executeUpdate(
+                "CREATE TABLE documents (id INT, text CLOB(64 K))");
             conn.commit();
 
             // --- add a file
@@ -68,8 +73,8 @@
             conn.commit();
 
             // --- reading the columns
-            ResultSet rs = s.executeQuery("SELECT text FROM documents
-             WHERE id = 1477");
+            ResultSet rs = s.executeQuery(
+                "SELECT text FROM documents WHERE id = 1477");
             while (rs.next()) {
                 java.sql.Clob aclob = rs.getClob(1);
                 java.io.InputStream ip = rs.getAsciiStream(1);

Modified: db/derby/docs/trunk/src/ref/rrefjdbc32052.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbc32052.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbc32052.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbc32052.dita Wed Aug 27 13:20:15 2008
@@ -20,37 +20,52 @@
 <reference id="rrefjdbc32052" xml:lang="en-us">
 <title>java.sql.Driver interface</title>
 <prolog><metadata>
-<keywords><indexterm>java.sql.Driver interface</indexterm><indexterm>JDBC
driver<indexterm>loading</indexterm></indexterm>
+<keywords><indexterm>java.sql.Driver interface</indexterm>
+<indexterm>JDBC driver<indexterm>loading</indexterm></indexterm>
+<indexterm>jdbc.drivers system property<indexterm>using to load driver</indexterm></indexterm>
 </keywords>
 </metadata></prolog>
 <refbody>
 <section><p>The class that loads <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
 local JDBC driver is the class <i>org.apache.derby.jdbc.EmbeddedDriver</i>.
-Listed below are some of the ways to create instances of that class. Do not use the class
directly through the <i>java.sql.Driver</i> interface.
-Use the <i>DriverManager</i> class to create connections.   <ul id="i1012571">
-<li>If your application runs on JDK 1.6 or higher, you do not need to
-do any of the following. The EmbeddedDriver will load automatically
-when your application asks for its first Connection.<p> </p></li>
-<li id="i1012580"><i id="jdbc10841">Class.forName("org.apache.derby.jdbc.EmbeddedDriver")</i>

- <p>Our recommended manner, because it ensures that the class is loaded in
-all JVMs by creating an instance at the same time.</p></li>
-<li><i>new org.apache.derby.jdbc.EmbeddedDriver()</i>   <p>Same as
<i><xref
-href="#rrefjdbc32052/jdbc10841">Class.forName("org.apache.derby.jdbc.EmbeddedDriver")</xref>,</i>
except
+The class that loads <ph conref="../conrefs.dita#prod/productshortname"></ph>'s
+network client driver is the class <i>org.apache.derby.jdbc.ClientDriver</i>.
+Listed below are some of the ways to create instances of these classes. Do not use the classes
directly through the <i>java.sql.Driver</i> interface.
+Use the <i>DriverManager</i> class to create connections.</p>  
+<p>If your application runs on JDK 6 or higher, you do not need to
+do any of the following. The driver will load automatically
+when your application asks for its first connection.</p>
+<ul>
+<li><pre id="jdbc10841">Class.forName("org.apache.derby.jdbc.EmbeddedDriver");
+Class.forName("org.apache.derby.jdbc.ClientDriver");</pre>
+<p>The recommended way to load the driver class.</p>
+<p>With the embedded driver, if your application shuts down Derby or calls the
+<i>DriverManager.unload</i> method, and you then want to reload the driver, call
+the <i>Class.forName().newInstance()</i> method to do so:</p>
+<pre>Class.forName("org.apache.derby.jdbc.EmbeddedDriver").newInstance();</pre>
+</li>
+<li><pre>new org.apache.derby.jdbc.EmbeddedDriver();
+new org.apache.derby.jdbc.ClientDriver();</pre>   <p>Same as using
+<i>Class.forName()</i>, except
 that it requires the class to be found when the code is compiled.</p></li>
-<li><i>Class c = org.apache.derby.jdbc.EmbeddedDriver.class</i>   <p>This
-is also the same as <i><xref href="rrefjdbc32052.dita#rrefjdbc32052/jdbc10841">Class.forName("org.apache.derby.jdbc.EmbeddedDriver")</xref>,</i>
except
+<li><pre>Class c = org.apache.derby.jdbc.EmbeddedDriver.class;
+Class c = org.apache.derby.jdbc.ClientDriver.class;</pre>   <p>This
+is also the same as using <i>Class.forName()</i>, except
 that it requires the class to be found when the code is compiled. The pseudo-static
 field <i>class</i> evaluates to the class that is named.</p></li>
-<li><i>Setting the System property jdbc.drivers<ph><indexterm>JDBC
driver<indexterm>loading</indexterm></indexterm></ph><ph><indexterm>jdbc.drivers
-system property<indexterm>using to load driver</indexterm></indexterm></ph></i>

- <p>To set a System property, you alter the invocation command line or the
+<li><i>Setting the system property jdbc.drivers</i> 
+ <p>To set a system property, you alter the invocation command line or the
 system properties within your application. It is not possible to alter system
-properties within an applet.</p></li>
-</ul></p></section>
-<example><codeblock><b>java -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver
-    applicationClass</b></codeblock></example>
+properties within an applet.</p>
+<codeblock>java -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver
+    applicationClass
+
+java -Djdbc.drivers=org.apache.derby.jdbc.ClientDriver
+    applicationClass</codeblock></li>
+</ul></section>
 <section><p>The actual driver that gets registered in the <i>DriverManager</i>
to
-handle the <i>jdbc:derby:</i> protocol is not the class <i>org.apache.derby.jdbc.EmbeddedDriver</i>;
+handle the <i>jdbc:derby:</i> protocol is not the class <i>org.apache.derby.jdbc.EmbeddedDriver</i>
+or <i>org.apache.derby.jdbc.ClientDriver</i>;
 that class simply detects the type of <ph conref="../conrefs.dita#prod/productshortname"></ph>
driver
 needed and then causes the appropriate <ph conref="../conrefs.dita#prod/productshortname"></ph>
driver
 to be loaded.</p></section>

Modified: db/derby/docs/trunk/src/ref/rrefjdbc4_0summary.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefjdbc4_0summary.dita?rev=689598&r1=689597&r2=689598&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefjdbc4_0summary.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefjdbc4_0summary.dita Wed Aug 27 13:20:15 2008
@@ -38,7 +38,7 @@
 JDBC 4.0 adds some functionality to the core API. This section
 documents the features supported by <ph conref="../conrefs.dita#prod/productshortname"></ph>.
 </p>
-<p><note>These features are present only in a JDK 1.6 or higher
+<p><note>These features are present only in a JDK 6 or higher
 environment.
 </note></p>
 </section>



Mime
View raw message