Class DriverManager

The basic service for managing a set of JDBC drivers.NOTE: The DataSource interface, new in the
JDBC 2.0 API, provides another way to connect to a data source.
The use of a DataSource object is the preferred means of
connecting to a data source.

As part of its initialization, the DriverManager class will
attempt to load the driver classes referenced in the "jdbc.drivers"
system property. This allows a user to customize the JDBC Drivers
used by their applications. For example in your
~/.hotjava/properties file you might specify:

jdbc.drivers=foo.bah.Driver:wombat.sql.Driver:bad.taste.ourDriver

The DriverManager methods getConnection and
getDrivers have been enhanced to support the Java Standard Edition
Service Provider mechanism. JDBC 4.0 Drivers must
include the file META-INF/services/java.sql.Driver. This file contains the name of the JDBC drivers
implementation of java.sql.Driver. For example, to load the my.sql.Driver class,
the META-INF/services/java.sql.Driver file would contain the entry:

my.sql.Driver

Applications no longer need to explicitly load JDBC drivers using Class.forName(). Existing programs
which currently load JDBC drivers using Class.forName() will continue to work without
modification.

When the method getConnection is called,
the DriverManager will attempt to
locate a suitable driver from amongst those loaded at
initialization and those loaded explicitly using the same classloader
as the current applet or application.

Starting with the Java 2 SDK, Standard Edition, version 1.3, a
logging stream can be set only if the proper
permission has been granted. Normally this will be done with
the tool PolicyTool, which can be used to grant permission
java.sql.SQLPermission "setLog".

setLogWriter

Sets the logging/tracing PrintWriter object
that is used by the DriverManager and all drivers.

There is a minor versioning problem created by the introduction
of the method setLogWriter. The
method setLogWriter cannot create a PrintStream object
that will be returned by getLogStream---the Java platform does
not provide a backward conversion. As a result, a new application
that uses setLogWriter and also uses a JDBC 1.0 driver that uses
getLogStream will likely not see debugging information written
by that driver.

Starting with the Java 2 SDK, Standard Edition, version 1.3 release, this method checks
to see that there is an SQLPermission object before setting
the logging stream. If a SecurityManager exists and its
checkPermission method denies setting the log writer, this
method throws a java.lang.SecurityException.

Parameters:

out - the new logging/tracing PrintStream object;
null to disable logging and tracing

Throws:

SecurityException - if a security manager exists and its
checkPermission method denies
setting the log writer

getConnection

Attempts to establish a connection to the given database URL.
The DriverManager attempts to select an appropriate driver from
the set of registered JDBC drivers.

Note: If a property is specified as part of the url and
is also specified in the Properties object, it is
implementation-defined as to which value will take precedence.
For maximum portability, an application should only specify a
property once.

Parameters:

url - a database url of the form
jdbc:subprotocol:subname

info - a list of arbitrary string tag/value pairs as
connection arguments; normally at least a "user" and
"password" property should be included

SQLTimeoutException - when the driver has determined that the
timeout value specified by the setLoginTimeout method
has been exceeded and has at least tried to cancel the
current database connection attempt

getConnection

Attempts to establish a connection to the given database URL.
The DriverManager attempts to select an appropriate driver from
the set of registered JDBC drivers.

Note: If the user or password property are
also specified as part of the url, it is
implementation-defined as to which value will take precedence.
For maximum portability, an application should only specify a
property once.

SQLTimeoutException - when the driver has determined that the
timeout value specified by the setLoginTimeout method
has been exceeded and has at least tried to cancel the
current database connection attempt

SQLTimeoutException - when the driver has determined that the
timeout value specified by the setLoginTimeout method
has been exceeded and has at least tried to cancel the
current database connection attempt

registerDriver

Registers the given driver with the DriverManager.
A newly-loaded driver class should call
the method registerDriver to make itself
known to the DriverManager. If the driver is currently
registered, no action is taken.

Parameters:

driver - the new JDBC Driver that is to be registered with the
DriverManager

registerDriver

Registers the given driver with the DriverManager.
A newly-loaded driver class should call
the method registerDriver to make itself
known to the DriverManager. If the driver is currently
registered, no action is taken.

Parameters:

driver - the new JDBC Driver that is to be registered with the
DriverManager

da - the DriverAction implementation to be used when
DriverManager#deregisterDriver is called

setLogStream

Sets the logging/tracing PrintStream that is used
by the DriverManager
and all drivers.

In the Java 2 SDK, Standard Edition, version 1.3 release, this method checks
to see that there is an SQLPermission object before setting
the logging stream. If a SecurityManager exists and its
checkPermission method denies setting the log writer, this
method throws a java.lang.SecurityException.

Parameters:

out - the new logging/tracing PrintStream; to disable, set to null

Throws:

SecurityException - if a security manager exists and its
checkPermission method denies setting the log stream