The basic service for managing a set of JDBC drivers.
- * NOTE: The {@link javax.sql.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
+ * The basic service for managing a set of JDBC drivers.
+ *
+ * NOTE: The {@link javax.sql.DataSource} interface, provides + * another way to connect to a data source. + * The use of a {@code 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".
+ * As part of its initialization, the {@code DriverManager} class will
+ * attempt to load available JDBC drivers by using:
+ *
+ * @ImplNote + * {@code 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 {@code DriverManager}. + * + *
When the method {@code getConnection} is called,
+ * the {@code 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.
+ *
* @see Driver
* @see Connection
*/
@@ -137,29 +132,15 @@ public class DriverManager {
/**
* 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.
+ * If a security manager exists, its {@code checkPermission}
+ * method is first called with a {@code SQLPermission("setLog")}
+ * permission to check that the caller is allowed to call {@code setLogWriter}.
*
* @param 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
- *
+ * @throws SecurityException if a security manager exists and its
+ * {@code checkPermission} method denies permission to set the log writer.
* @see SecurityManager#checkPermission
* @see #getLogWriter
* @since 1.2
@@ -374,8 +355,9 @@ public class DriverManager {
* If a {@code null} value is specified for the driver to be removed, then no
* action is taken.
*
- * If a security manager exists and its {@code checkPermission} denies - * permission, then a {@code SecurityException} will be thrown. + * If a security manager exists, its {@code checkPermission} + * method is first called with a {@code 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
@@ -501,17 +483,14 @@ public class DriverManager {
* 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.
+ * If a security manager exists, its {@code checkPermission}
+ * method is first called with a {@code SQLPermission("setLog")}
+ * permission to check that the caller is allowed to call {@code setLogStream}.
*
* @param out the new logging/tracing PrintStream; to disable, set to null
* @deprecated Use {@code setLogWriter}
* @throws SecurityException if a security manager exists and its
- * checkPermission method denies setting the log stream
- *
+ * {@code checkPermission} method denies permission to set the log stream.
* @see SecurityManager#checkPermission
* @see #getLogStream
*/