db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-503) Documentation should recommend using .newInstance() to instantiate JDBC driver
Date Thu, 07 Aug 2008 20:22:46 GMT

    [ 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.


Mime
View raw message