[jira] Updated: (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:all-tabpanel ]

Kim Haase updated DERBY-503:
----------------------------

    Attachment: DERBY-503.stat
                DERBY-503.zip
                DERBY-503.diff

Attaching DERBY-503.diff, DERBY-503.zip, and DERBY-503.stat.

After further thought, I decided that it makes sense to document the use of newInstance() only in the unusual situation where it is actually required: if you are using the embedded driver and you need to stop Derby and restart it in the course of the application. In that case, you need to call newInstance() when you call Class.forName() to reload the driver. There are three places in the Developer's Guide and one in the Reference Manual where it is useful to mention this.

The rest of the time there is no need for newInstance().

I've still made some corrections: changing "JDK 1.6" and "JDK 1.5" to "JDK 6" and "JDK 5" where needed; changing "put" to "setProperty" when using java.util.Properties (recommended usage); fixing some formatting and index terms in the Reference Manual.

The updates to "java.sql.Driver interface" (rrefjdbc32052.dita) include adding information about the client driver -- it mentioned only the embedded driver up to now. These changes also fix DERBY-2958.

The patch now has the following changes, to 10 files:

Admin Guide:

http://db.apache.org/derby/docs/dev/adminguide/cadminembeddedserver.html (How to start an embedded server from an application): Removed use of newInstance(), fixed JDK 6 reference.

http://db.apache.org/derby/docs/dev/adminguide/radminembeddedserverex.html (Embedded server example): Fixed Properties code and JDK 6 reference, removed newInstance(), changed ClientDriver to EmbeddedDriver.

http://db.apache.org/derby/docs/dev/adminguide/radminappsclientxmp.html (Network client driver examples): Fixed Properties code and JDK 6 reference, fixed a couple typos.

http://db.apache.org/derby/docs/dev/adminguide/cadminappsxawthdriver.html (Using XA with the network client driver): Fixed sample to remove driver instantiation entirely (it is not needed), updated datasource property settings and code spacing.

Dev Guide: 

http://db.apache.org/derby/docs/dev/devguide/cdevdvlp40653.html (Derby JDBC driver): Added explanation of when to use newInstance(). Fixed JDK 5 & 6 references and some typos.

http://db.apache.org/derby/docs/dev/devguide/tdevdvlp20349.html (Shutting down the system): Removed references to garbage collection and added explanation of how to use newInstance() to reload the driver. Also corrected JVM reference and updated error log message.

http://db.apache.org/derby/docs/dev/devguide/tdevdvlp36289.html (Specifying attributes in a properties object): Added explanation of use of Class.forName(). Fixed formatting, Properties code.

Ref Manual:

http://db.apache.org/derby/docs/dev/ref/rrefclob.html (CLOB data type): Added JDK 6 info, removed newInstance(), fixed code formatting.

http://db.apache.org/derby/docs/dev/ref/rrefjdbc32052.html (java.sql.Driver interface): Added information on client driver (DERBY-2958) since the information applies to both client and embedded (please let me know if this is not the case). Added explanation of when to use newInstance(). Removed confusing language and fixed formatting.

http://db.apache.org/derby/docs/dev/ref/rrefjdbc4_0summary.html (JDBC 4.0-only features): Fixed JDK 6 reference.


> 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
>         Attachments: DERBY-503.diff, DERBY-503.stat, DERBY-503.zip
>
>
> 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.