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 ch...@apache.org on 2008/08/27 22:20:15 UTC
svn commit: r689598 - in /db/derby/docs/trunk/src: adminguide/ devguide/ ref/
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>