From 49393dbb14a0c7d32ef80429f3f856c48bd4e7b1 Mon Sep 17 00:00:00 2001 From: Lance Andersen Date: Thu, 15 Dec 2016 16:24:33 -0500 Subject: [PATCH] 8169806: DriverManager javadoc clarifications Reviewed-by: mchung --- .../share/classes/java/sql/DriverManager.java | 111 +++++++----------- 1 file changed, 45 insertions(+), 66 deletions(-) diff --git a/jdk/src/java.sql/share/classes/java/sql/DriverManager.java b/jdk/src/java.sql/share/classes/java/sql/DriverManager.java index a32cf8f564d..7fe59001940 100644 --- a/jdk/src/java.sql/share/classes/java/sql/DriverManager.java +++ b/jdk/src/java.sql/share/classes/java/sql/DriverManager.java @@ -41,46 +41,41 @@ import jdk.internal.reflect.Reflection; /** - *

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 */