[
https://issues.apache.org/jira/browse/DERBY-503?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12620733#action_12620733
]
Kim Haase commented on DERBY-503:
---------------------------------
We need to do a couple things: first, to explain when and why you need to use
Class.forName(driver).newInstance(); second, to use this method call when this
is appropriate.
The most appropriate place in the Developer's Guide to provide the explanation
is probably "Shutting down the system"
(http://db.apache.org/derby/docs/dev/devguide/tdevdvlp20349.html) near the
beginning of the manual. This topic describes how to restart Derby, using the
embedded driver, in the same JVM -- this is when you really need to call
newInstance(). In the Reference Manual, the information should probably also be
added to the topic "java.sql.Driver interface"
(http://db.apache.org/derby/docs/dev/ref/rrefjdbc32052.html).
The following is a list of the occurrences of Class.forName() in the
documentation and comments indicating what changes are needed (if any). I do
have a few questions here and there to which answers would be helpful.
Admin Guide:
http://db.apache.org/derby/docs/dev/adminguide/cadminembeddedserver.html (How
to start an embedded server from an application):
Mostly fine. Already uses newInstance, and specifies that Class.forName is
needed only pre-JDK 1.6 (fix: should be JDK 6).
http://db.apache.org/derby/docs/dev/adminguide/radminembeddedserverex.html
(Embedded server example):
Uses newInstance, and has the JDK 1.6 note (change to JDK 6), but it's
confusing because the note refers to the embedded driver but the app is loading
the client driver. I think the note needs fixing.
(I wish "embedded" did not mean two different things in Derby -- it's very
confusing, though it is explained, more or less, in "The Derby Network Server",
http://db.apache.org/derby/docs/dev/adminguide/cadminov825266.html.)
http://db.apache.org/derby/docs/dev/adminguide/radminappsclientxmp.html
(Network client driver examples):
Add newInstance() and fix JDK 1.6 note to say JDK 6.
http://db.apache.org/derby/docs/dev/adminguide/cadminappsxawthdriver.html
(Using XA with the network client driver):
Shows use of both DataSource instantiation and Class.forName(driver) specifying
the datasource as the driver. Is that OK? It seems redundant (and confusing). I
don't believe Class.forName is needed here at all. Or should there be two
separate code examples, one with a datasource, the other with Class.forName()?
Developer's Guide:
http://db.apache.org/derby/docs/dev/devguide/cdevdvlp40653.html (Derby JDBC
driver):
Add newInstance(). Has JDK 1.6 info (needs to say JDK 6, also JDK 5).
http://db.apache.org/derby/docs/dev/devguide/tdevdvlp20349.html (Shutting down
the system):
See DERBY-3612. Remove the misleading paragraph about garbage collection.
Instead, mention that if you want to shut down Derby and then reload the
driver, you should do so with a Class.forName(driver).newInstance() call. (But
that this is unnecessary if you use JDK 6 because it loads the driver
correctly.)
http://db.apache.org/derby/docs/dev/devguide/tdevdvlp36289.html (Specifying
attributes in a properties object):
Fix, add JDK 6 note (Also fix spacing in code example).
http://db.apache.org/derby/docs/dev/devguide/cdevdeploy12748.html (Code your
applications):
Okay as is: I don't believe this applies, since it isn't about the driver
classes; it's about loading application classes.
http://db.apache.org/derby/docs/dev/devguide/cdevspecialtfexample.html (Example
Derby-style table function):
try { Class.forName( EXTERNAL_DRIVER ); }
Add newInstance() and the JDK 6 note?
BTW, the code example has very long lines that don't look very good in the PDF
version (they wrap over after 72 characters) and are a little hard to read in
the frames HTML too.
Getting Started:
http://db.apache.org/derby/docs/dev/getstart/rwwdactivity3.html (The
WwdEmbedded program):
Needs fix and JDK 6 note.
Reference Manual:
http://db.apache.org/derby/docs/dev/ref/rrefclob.html (CLOB data type):
Uses newInstance(), but needs the JDK 6 note. Also has some odd horizontal
spacing (uses tabs).
http://db.apache.org/derby/docs/dev/ref/rrefjdbc32052.html (java.sql.Driver
interface):
Fix JDK 1.6 info to say JDK 6. Should ".newInstance()" be added to the next
bullet? Also I'm not sure that the explanation is correct ("Our recommended
manner, because it ensures that the class is loaded in all JVMs by creating an
instance at the same time."); I don't understand it, anyway. Should probably be
rewritten.
http://db.apache.org/derby/docs/dev/ref/rrefjdbc4_0summary.html (JDBC 4.0-only
features):
Fix JDK 1.6.
Tools Guide:
http://db.apache.org/derby/docs/dev/tools/rtoolsijcomref39042.html (Driver
command):
Okay as is? Actually, it doesn't point out that you don't have to use the
driver command in order to connect to the database; you can just use connect
with the appropriate URL. Isn't that the case, regardless of whether you are
using JDK 5 or 6? The Getting Started manual doesn't mention any need to use
this command.
> Documentation should recommend using .newInstance() to instantiate JDBC driver
> ------------------------------------------------------------------------------
>
> Key: DERBY-503
> URL: https://issues.apache.org/jira/browse/DERBY-503
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
> Affects Versions: 10.1.1.0
> Reporter: Oyvind Bakksjo
> Assignee: Kim Haase
> Priority: Minor
>
> Using Class.forName("<driver name>").newInstance() is the recommended way to
> load and instantiate the JDBC driver, but the documentation does not contain
> the .newInstance() part.
> Pointers:
> http://db.apache.org/derby/docs/10.1/devguide/cdevdvlp40653.html
> http://db.apache.org/derby/docs/10.1/ref/rrefjdbc32052.html
> The EmbeddedDriver javadoc mentions it:
> "The JDBC specification recommends the Class.ForName method without the
> .newInstance() method call, but adding the newInstance() guarantees that
> Derby will be booted on any Java Virtual Machine."
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
