public class DriverManager extends Object
NOTE: The DataSource
interface, 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 available JDBC drivers by using:
jdbc.drivers
system property which contains a
colon separated list of fully qualified class names of JDBC drivers. Each
driver is loaded using the system class loader:
jdbc.drivers=foo.bah.Driver:wombat.sql.Driver:bad.taste.ourDriver
java.sql.Driver
class, that are loaded
via the service-provider loading mechanism.
DriverManager
initialization is done lazily and looks up service
providers using the thread context class loader. The drivers loaded and
available to an application will depend on the thread context class loader of
the thread that triggers driver initialization by DriverManager
.
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 class loader
as the current application.
Driver
,
Connection
Modifier and Type | Method | Description |
---|---|---|
static void |
deregisterDriver(Driver driver) |
Removes the specified driver from the
DriverManager 's list of
registered drivers. |
static Stream<Driver> |
drivers() |
Retrieves a Stream with all of the currently loaded JDBC drivers
to which the current caller has access.
|
static Connection |
getConnection(String url) |
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 Connection |
getConnection(String url,
Properties info) |
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.
If a security manager exists, its checkPermission
method is first called with a SQLPermission("setLog")
permission to check that the caller is allowed to call setLogWriter
.
out
- the new logging/tracing PrintStream
object;
null
to disable logging and tracingSecurityException
- if a security manager exists and its
checkPermission
method denies permission to set the log writer.SecurityManager.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:subname
info
- 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
null
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 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:subname
user
- 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
null
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 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:subname
SQLException
- if a database access error occurs or the url is
null
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 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:subname
Driver
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
DriverManager
SQLException
- 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
DriverManager
da
- 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, its checkPermission
method is first called with a SQLPermission("deregisterDriver")
permission to check that the caller is allowed to deregister a JDBC Driver.
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()
drivers()
public static Stream<Driver> drivers()
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(since="1.2") public static void setLogStream(PrintStream out)
setLogWriter
DriverManager
and all drivers.
If a security manager exists, its checkPermission
method is first called with a SQLPermission("setLog")
permission to check that the caller is allowed to call setLogStream
.
out
- the new logging/tracing PrintStream; to disable, set to null
SecurityException
- if a security manager exists and its
checkPermission
method denies permission to set the log stream.SecurityManager.checkPermission(java.security.Permission)
,
getLogStream()
@Deprecated(since="1.2") public static PrintStream getLogStream()
getLogWriter
DriverManager
and all drivers.null
setLogStream(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, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps