public class DriverManager extends Object
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".
Driver,
Connection| Modifier and Type | Method and Description |
|---|---|
static void |
deregisterDriver(Driver driver)
Removes the specified driver from the
DriverManager's list of
registered drivers. |
static Connection |
getConnection(String url)
Attempts to establish a connection to the given database URL.
|
static Connection |
getConnection(String url,
Properties info)
Attempts to establish a connection to the given database URL.
|
static Connection |
getConnection(String url,
String user,
String password)
Attempts to establish a connection to the given database URL.
|
static Driver |
getDriver(String url)
Attempts to locate a driver that understands the given URL.
|
static Enumeration<Driver> |
getDrivers()
Retrieves an Enumeration with all of the currently loaded JDBC drivers
to which the current caller has access.
|
static int |
getLoginTimeout()
Gets the maximum time in seconds that a driver can wait
when attempting to log in to a database.
|
static PrintStream |
getLogStream()
Deprecated.
Use
getLogWriter |
static PrintWriter |
getLogWriter()
Retrieves the log writer.
|
static void |
println(String message)
Prints a message to the current JDBC log stream.
|
static void |
registerDriver(Driver driver)
Registers the given driver with the
DriverManager. |
static void |
registerDriver(Driver driver,
DriverAction da)
Registers the given driver with the
DriverManager. |
static void |
setLoginTimeout(int seconds)
Sets the maximum time in seconds that a driver will wait
while attempting to connect to a database once the driver has
been identified.
|
static void |
setLogStream(PrintStream out)
Deprecated.
Use
setLogWriter |
static void |
setLogWriter(PrintWriter out)
Sets the logging/tracing
PrintWriter object
that is used by the DriverManager and all drivers. |
public static PrintWriter getLogWriter()
getLogWriter and setLogWriter
methods should be used instead
of the get/setlogStream methods, which are deprecated.java.io.PrintWriter objectsetLogWriter(java.io.PrintWriter)public static void setLogWriter(PrintWriter out)
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.
out - the new logging/tracing PrintStream object;
null to disable logging and tracingSecurityException - if a security manager exists and its
checkPermission method denies
setting the log writerSecurityManager.checkPermission(java.security.Permission),
getLogWriter()public static Connection getConnection(String url, Properties info) throws SQLException
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.
url - a database url of the form
jdbc:subprotocol:subnameinfo - a list of arbitrary string tag/value pairs as
connection arguments; normally at least a "user" and
"password" property should be includedSQLException - if a database access error occurs or the url is
nullSQLTimeoutException - 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 attemptpublic static Connection getConnection(String url, String user, String password) throws SQLException
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.
url - a database url of the form
jdbc:subprotocol:subnameuser - the database user on whose behalf the connection is being
madepassword - the user's passwordSQLException - if a database access error occurs or the url is
nullSQLTimeoutException - 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 attemptpublic static Connection getConnection(String url) throws SQLException
DriverManager attempts to select an appropriate driver from
the set of registered JDBC drivers.url - a database url of the form
jdbc:subprotocol:subnameSQLException - if a database access error occurs or the url is
nullSQLTimeoutException - 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 attemptpublic static Driver getDriver(String url) throws SQLException
DriverManager attempts to select an appropriate driver from
the set of registered JDBC drivers.url - a database URL of the form
jdbc:subprotocol:subnameDriver object representing a driver
that can connect to the given URLSQLException - if a database access error occurspublic static void registerDriver(Driver driver) throws SQLException
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.driver - the new JDBC Driver that is to be registered with the
DriverManagerSQLException - if a database access error occursNullPointerException - if driver is nullpublic static void registerDriver(Driver driver, DriverAction da) throws SQLException
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.driver - the new JDBC Driver that is to be registered with the
DriverManagerda - the DriverAction implementation to be used when
DriverManager#deregisterDriver is calledSQLException - if a database access error occursNullPointerException - if driver is nullpublic static void deregisterDriver(Driver driver) throws SQLException
DriverManager's list of
registered drivers.
If a null value is specified for the driver to be removed, then no
action is taken.
If a security manager exists and its checkPermission denies
permission, then a SecurityException will be thrown.
If the specified driver is not found in the list of registered drivers, then no action is taken. If the driver was found, it will be removed from the list of registered drivers.
If a DriverAction instance was specified when the JDBC driver was
registered, its deregister method will be called
prior to the driver being removed from the list of registered drivers.
driver - the JDBC Driver to removeSQLException - if a database access error occursSecurityException - if a security manager exists and its
checkPermission method denies permission to deregister a driver.SecurityManager.checkPermission(java.security.Permission)public static Enumeration<Driver> getDrivers()
Note: The classname of a driver can be found using
d.getClass().getName()
public static void setLoginTimeout(int seconds)
seconds - the login time limit in seconds; zero means there is no limitgetLoginTimeout()public static int getLoginTimeout()
setLoginTimeout(int)@Deprecated public static void setLogStream(PrintStream out)
setLogWriterDriverManager
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.
out - the new logging/tracing PrintStream; to disable, set to nullSecurityException - if a security manager exists and its
checkPermission method denies setting the log streamSecurityManager.checkPermission(java.security.Permission),
getLogStream()@Deprecated public static PrintStream getLogStream()
getLogWriterDriverManager
and all drivers.nullsetLogStream(java.io.PrintStream)public static void println(String message)
message - a log or tracing message Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.