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