APIdia Launch Partner
Top Description Fields Constructors Methods
java.sql

public Class DriverManager

Additional top-level class in compilation unit: DriverInfo.

extends Object
Class Inheritance
Imports
java.util.ArrayList, .Collections, .Enumeration, .Iterator, .List, .ServiceLoader, java.util.concurrent.CopyOnWriteArrayList, java.util.stream.Stream, jdk.internal.reflect.CallerSensitive, .CallerSensitiveAdapter, .Reflection
The basic service for managing a set of JDBC drivers.

Note

The javax.sql.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:

Implementation Note

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.

Since
1.1
See Also
Driver, Connection

Field Summary

Modifier and TypeField and Description
private static volatile boolean
driversInitialized

private static final String
JDBC_DRIVERS_PROPERTY

private static final Object
lockForInitDrivers

private static volatile int
loginTimeout

private static volatile PrintStream
logStream

private static final Object
logSync

private static volatile PrintWriter
logWriter

private static final CopyOnWriteArrayList<DriverInfo>
registeredDrivers

Constructor Summary

AccessConstructor and Description
private
DriverManager()

Method Summary

Modifier and TypeMethod and Description
public static void
deregisterDriver(Driver
the JDBC Driver to remove
driver)

Removes the specified driver from the DriverManager's list of registered drivers.

public static Stream<Driver>

Returns:

the stream of JDBC Drivers loaded by the caller's class loader
drivers()

Retrieves a Stream with all of the currently loaded JDBC drivers to which the current caller has access.

private static void
ensureDriversInitialized()

public static Connection

Returns:

a Connection to the URL
getConnection(String
a database url of the form jdbc:subprotocol:subname
url, Properties
a list of arbitrary string tag/value pairs as connection arguments; normally at least a "user" and "password" property should be included
info)

Attempts to establish a connection to the given database URL.

public static Connection

Returns:

a connection to the URL
getConnection(String
a database url of the form jdbc:subprotocol:subname
url, String
the database user on whose behalf the connection is being made
user, String
the user's password
password)

Attempts to establish a connection to the given database URL.

public static Connection

Returns:

a connection to the URL
getConnection(String
a database url of the form jdbc:subprotocol:subname
url)

Attempts to establish a connection to the given database URL.

private static Connection
getConnection(String url, Properties info, Class<?> caller)

public static Driver

Returns:

a Driver object representing a driver that can connect to the given URL
getDriver(String
a database URL of the form jdbc:subprotocol:subname
url)

Attempts to locate a driver that understands the given URL.

public static Enumeration<Driver>

Returns:

the list of JDBC Drivers loaded by the caller's class loader
getDrivers()

Retrieves an Enumeration with all of the currently loaded JDBC drivers to which the current caller has access.

private static List<Driver>
getDrivers(Class<?> callerClass)

public static int

Returns:

the driver login time limit in seconds
getLoginTimeout()

Gets the maximum time in seconds that a driver can wait when attempting to log in to a database.

public static PrintStream

Returns:

the logging/tracing PrintStream; if disabled, is null
getLogStream()
Deprecated since 1.2. Use getLogWriter

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

public static PrintWriter

Returns:

a java.io.PrintWriter object
getLogWriter()

Retrieves the log writer.

private static boolean
isDriverAllowed(Driver driver, Class<?> caller)

private static boolean
isDriverAllowed(Driver driver, ClassLoader classLoader)

public static void
println(String
a log or tracing message
message)

Prints a message to the current JDBC log stream.

public static void
registerDriver(Driver
the new JDBC Driver that is to be registered with the DriverManager
driver)

Registers the given driver with the DriverManager.

public static void
registerDriver(Driver
the new JDBC Driver that is to be registered with the DriverManager
driver, DriverAction
the DriverAction implementation to be used when DriverManager#deregisterDriver is called
da)

Registers the given driver with the DriverManager.

public static void
setLoginTimeout(int
the login time limit in seconds; zero means there is no limit
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.

public static void
setLogStream(PrintStream
the new logging/tracing PrintStream; to disable, set to null
out)
Deprecated since 1.2. Use setLogWriter

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

public static void
setLogWriter(PrintWriter
the new logging/tracing PrintStream object; null to disable logging and tracing
out)

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

driversInitializedback to summary
private static volatile boolean driversInitialized
JDBC_DRIVERS_PROPERTYback to summary
private static final String JDBC_DRIVERS_PROPERTY
lockForInitDriversback to summary
private static final Object lockForInitDrivers
loginTimeoutback to summary
private static volatile int loginTimeout
logStreamback to summary
private static volatile PrintStream logStream
logSyncback to summary
private static final Object logSync
logWriterback to summary
private static volatile PrintWriter logWriter
registeredDriversback to summary
private static final CopyOnWriteArrayList<DriverInfo> registeredDrivers

Constructor Detail

DriverManagerback to summary
private DriverManager()

Method Detail

deregisterDriverback to summary
public static void deregisterDriver(Driver driver) throws SQLException

Removes the specified driver from the DriverManager's list of registered drivers.

If a null value is specified for the driver to be removed, then no action is taken.

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.

Parameters
driver:Driver

the JDBC Driver to remove

Annotations
@CallerSensitive
Exceptions
SQLException:
if a database access error occurs
driversback to summary
public static Stream<Driver> drivers()

Retrieves a Stream with all of the currently loaded JDBC drivers to which the current caller has access.

Returns:Stream<Driver>

the stream of JDBC Drivers loaded by the caller's class loader

Annotations
@CallerSensitive
Since
9
ensureDriversInitializedback to summary
private static void ensureDriversInitialized()
getConnectionback to summary
public static Connection getConnection(String url, Properties info) throws SQLException

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:String

a database url of the form jdbc:subprotocol:subname

info:Properties

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

Returns:Connection

a Connection to the URL

Annotations
@CallerSensitive
Exceptions
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 attempt
getConnectionback to summary
public static Connection getConnection(String url, String user, String password) throws SQLException

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.

Parameters
url:String

a database url of the form jdbc:subprotocol:subname

user:String

the database user on whose behalf the connection is being made

password:String

the user's password

Returns:Connection

a connection to the URL

Annotations
@CallerSensitive
Exceptions
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 attempt
getConnectionback to summary
public static Connection getConnection(String url) throws SQLException

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.

Parameters
url:String

a database url of the form jdbc:subprotocol:subname

Returns:Connection

a connection to the URL

Annotations
@CallerSensitive
Exceptions
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 attempt
getConnectionback to summary
private static Connection getConnection(String url, Properties info, Class<?> caller) throws SQLException
Annotations
@CallerSensitiveAdapter
getDriverback to summary
public static Driver getDriver(String url) throws SQLException

Attempts to locate a driver that understands the given URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers.

Parameters
url:String

a database URL of the form jdbc:subprotocol:subname

Returns:Driver

a Driver object representing a driver that can connect to the given URL

Annotations
@CallerSensitive
Exceptions
SQLException:
if a database access error occurs
getDriversback to summary
public static Enumeration<Driver> getDrivers()

Retrieves an Enumeration with all of the currently loaded JDBC drivers to which the current caller has access.

Note

The classname of a driver can be found using d.getClass().getName()

Returns:Enumeration<Driver>

the list of JDBC Drivers loaded by the caller's class loader

Annotations
@CallerSensitive
See Also
drivers()
getDriversback to summary
private static List<Driver> getDrivers(Class<?> callerClass)
getLoginTimeoutback to summary
public static int getLoginTimeout()

Gets the maximum time in seconds that a driver can wait when attempting to log in to a database.

Returns:int

the driver login time limit in seconds

See Also
setLoginTimeout
getLogStreamback to summary
public static PrintStream getLogStream()

Deprecated

since 1.2.

Use getLogWriter

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

Returns:PrintStream

the logging/tracing PrintStream; if disabled, is null

Annotations
@Deprecated
since:1.2
See Also
setLogStream
getLogWriterback to summary
public static PrintWriter getLogWriter()

Retrieves the log writer. The getLogWriter and setLogWriter methods should be used instead of the get/setlogStream methods, which are deprecated.

Returns:PrintWriter

a java.io.PrintWriter object

Since
1.2
See Also
setLogWriter
isDriverAllowedback to summary
private static boolean isDriverAllowed(Driver driver, Class<?> caller)
isDriverAllowedback to summary
private static boolean isDriverAllowed(Driver driver, ClassLoader classLoader)
printlnback to summary
public static void println(String message)

Prints a message to the current JDBC log stream.

Parameters
message:String

a log or tracing message

registerDriverback to summary
public static void registerDriver(Driver driver) throws SQLException

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:Driver

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

Exceptions
SQLException:
if a database access error occurs
NullPointerException:
if driver is null
registerDriverback to summary
public static void registerDriver(Driver driver, DriverAction da) throws SQLException

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:Driver

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

da:DriverAction

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

Exceptions
SQLException:
if a database access error occurs
NullPointerException:
if driver is null
Since
1.8
setLoginTimeoutback to summary
public 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.

Parameters
seconds:int

the login time limit in seconds; zero means there is no limit

See Also
getLoginTimeout
setLogStreamback to summary
public static void setLogStream(PrintStream out)

Deprecated

since 1.2.

Use setLogWriter

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

Parameters
out:PrintStream

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

Annotations
@Deprecated
since:1.2
See Also
getLogStream
setLogWriterback to summary
public static void setLogWriter(PrintWriter out)

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

Parameters
out:PrintWriter

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

Since
1.2
See Also
getLogWriter