[jira] Commented: (DERBY-503) Documentation should recommend using .newInstance() to instantiate JDBC driver

["Kim Haase (JIRA)" <ji...@apache.org>]

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