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] Updated: (DERBY-503) Documentation should recommend using .newInstance() to instantiate JDBC driver
Date Wed, 20 Aug 2008 18:36:44 GMT

     [ 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

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

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:
>            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()
> 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.

View raw message