FileDocCategorySizeDatePackage
DriverManager.javaAPI DocAndroid 1.5 API16269Wed May 06 22:41:06 BST 2009java.sql

DriverManager

public class DriverManager extends Object
Provides facilities for managing JDBC drivers.

The {@code DriverManager} class loads JDBC drivers during its initialization, from the list of drivers referenced by the system property {@code "jdbc.drivers"}.

since
Android 1.0

Fields Summary
private static PrintStream
thePrintStream
private static PrintWriter
thePrintWriter
private static int
loginTimeout
private static final Set
theDriverSet
private static final SQLPermission
logPermission
Constructors Summary
private DriverManager()

        super();
    
Methods Summary
private static voidcheckLogSecurity()

        SecurityManager securityManager = System.getSecurityManager();
        if (securityManager != null) {
            // Throws a SecurityException if setting the log is not permitted
            securityManager.checkPermission(logPermission);
        }
    
public static voidderegisterDriver(java.sql.Driver driver)
Removes a driver from the {@code DriverManager}'s registered driver list. This will only succeed when the caller's class loader loaded the driver that is to be removed. If the driver was loaded by a different class loader, the removal of the driver fails silently.

If the removal succeeds, the {@code DriverManager} will not use this driver in the future when asked to get a {@code Connection}.

param
driver the JDBC driver to remove.
throws
SQLException if there is a problem interfering with accessing the database.
since
Android 1.0

        if (driver == null) {
            return;
        }
        // BEGIN android-changed
        ClassLoader callerClassLoader = VMStack.getCallingClassLoader();
        // END android-changed

        if (!DriverManager.isClassFromClassLoader(driver, callerClassLoader)) {
            // sql.1=DriverManager: calling class not authorized to deregister JDBC driver
            throw new SecurityException(Messages.getString("sql.1")); //$NON-NLS-1$
        } // end if
        synchronized (theDriverSet) {
            theDriverSet.remove(driver);
        }
    
public static java.sql.ConnectiongetConnection(java.lang.String url)
Attempts to establish a connection to the given database URL.

param
url a URL string representing the database target to connect with.
return
a {@code Connection} to the database identified by the URL. {@code null} if no connection can be established.
throws
SQLException if there is an error while attempting to connect to the database identified by the URL.
since
Android 1.0

        return getConnection(url, new Properties());
    
public static java.sql.ConnectiongetConnection(java.lang.String url, java.util.Properties info)
Attempts to establish a connection to the given database URL.

param
url a URL string representing the database target to connect with
param
info a set of properties to use as arguments to set up the connection. Properties are arbitrary string/value pairs. Normally, at least the properties {@code "user"} and {@code "password"} should be passed, with appropriate settings for the user ID and its corresponding password to get access to the corresponding database.
return
a {@code Connection} to the database identified by the URL. {@code null} if no connection can be established.
throws
SQLException if there is an error while attempting to connect to the database identified by the URL.
since
Android 1.0

        // 08 - connection exception
        // 001 - SQL-client unable to establish SQL-connection
        String sqlState = "08001"; //$NON-NLS-1$
        if (url == null) {
            // sql.5=The url cannot be null
            throw new SQLException(Messages.getString("sql.5"), sqlState); //$NON-NLS-1$
        }
        synchronized (theDriverSet) {
            /*
             * Loop over the drivers in the DriverSet checking to see if one can
             * open a connection to the supplied URL - return the first
             * connection which is returned
             */
            for (Driver theDriver : theDriverSet) {
                Connection theConnection = theDriver.connect(url, info);
                if (theConnection != null) {
                    return theConnection;
                }
            }
        }
        // If we get here, none of the drivers are able to resolve the URL
        // sql.6=No suitable driver
        throw new SQLException(Messages.getString("sql.6"), sqlState); //$NON-NLS-1$ 
    
public static java.sql.ConnectiongetConnection(java.lang.String url, java.lang.String user, java.lang.String password)
Attempts to establish a connection to the given database URL.

param
url a URL string representing the database target to connect with.
param
user a user ID used to login to the database.
param
password a password for the user ID to login to the database.
return
a {@code Connection} to the database identified by the URL. {@code null} if no connection can be established.
throws
SQLException if there is an error while attempting to connect to the database identified by the URL.
since
Android 1.0

        Properties theProperties = new Properties();
        if(null != user){
            theProperties.setProperty("user", user); //$NON-NLS-1$
        }
        if(null != password){
            theProperties.setProperty("password", password); //$NON-NLS-1$
        }
        return getConnection(url, theProperties);
    
public static java.sql.DrivergetDriver(java.lang.String url)
Tries to find a driver that can interpret the supplied URL.

param
url the URL of a database.
return
a {@code Driver} that matches the provided URL. {@code null} if no {@code Driver} understands the URL
throws
SQLException if there is any kind of problem accessing the database.

        // BEGIN android-changed
        ClassLoader callerClassLoader = VMStack.getCallingClassLoader();
        // END android-changed

        synchronized (theDriverSet) {
            /*
             * Loop over the drivers in the DriverSet checking to see if one
             * does understand the supplied URL - return the first driver which
             * does understand the URL
             */
            Iterator<Driver> theIterator = theDriverSet.iterator();
            while (theIterator.hasNext()) {
                Driver theDriver = theIterator.next();
                if (theDriver.acceptsURL(url)
                        && DriverManager.isClassFromClassLoader(theDriver,
                                callerClassLoader)) {
                    return theDriver;
                }
            }
        }
        // If no drivers understand the URL, throw an SQLException
        // sql.6=No suitable driver
        //SQLState: 08 - connection exception
        //001 - SQL-client unable to establish SQL-connection
        throw new SQLException(Messages.getString("sql.6"), "08001"); //$NON-NLS-1$ //$NON-NLS-2$
    
public static java.util.EnumerationgetDrivers()
Returns an {@code Enumeration} that contains all of the loaded JDBC drivers that the current caller can access.

return
An {@code Enumeration} containing all the currently loaded JDBC {@code Drivers}.
since
Android 1.0

        // BEGIN android-changed
        ClassLoader callerClassLoader = VMStack.getCallingClassLoader();
        // END android-changed
        /*
         * Synchronize to avoid clashes with additions and removals of drivers
         * in the DriverSet
         */
        synchronized (theDriverSet) {
            /*
             * Create the Enumeration by building a Vector from the elements of
             * the DriverSet
             */
            Vector<Driver> theVector = new Vector<Driver>();
            Iterator<Driver> theIterator = theDriverSet.iterator();
            while (theIterator.hasNext()) {
                Driver theDriver = theIterator.next();
                if (DriverManager.isClassFromClassLoader(theDriver,
                        callerClassLoader)) {
                    theVector.add(theDriver);
                }
            }
            return theVector.elements();
        }
    
public static java.io.PrintStreamgetLogStream()
Gets the log {@code PrintStream} used by the {@code DriverManager} and all the JDBC Drivers.

deprecated
use {@link #getLogWriter()} instead.
return
the {@code PrintStream} used for logging activities.
since
Android 1.0

        return thePrintStream;
    
public static java.io.PrintWritergetLogWriter()
Retrieves the log writer.

return
A {@code PrintWriter} object used as the log writer. {@code null} if no log writer is set.
since
Android 1.0

        return thePrintWriter;
    
public static intgetLoginTimeout()
Returns the login timeout when connecting to a database in seconds.

return
the login timeout in seconds.
since
Android 1.0

        return loginTimeout;
    
private static booleanisClassFromClassLoader(java.lang.Object theObject, java.lang.ClassLoader theClassLoader)
Determines whether the supplied object was loaded by the given {@code ClassLoader}.

param
theObject the object to check.
param
theClassLoader the {@code ClassLoader}.
return
{@code true} if the Object does belong to the {@code ClassLoader} , {@code false} otherwise

    
        if ((theObject == null) || (theClassLoader == null)) {
            return false;
        }
    
        Class<?> objectClass = theObject.getClass();
    
        try {
            Class<?> checkClass = Class.forName(objectClass.getName(), true,
                    theClassLoader);
            if (checkClass == objectClass) {
                return true;
            }
        } catch (Throwable t) {
            // Empty
        }
        return false;
    
private static voidloadInitialDrivers()

 //$NON-NLS-1$

    /*
     * Load drivers on initialization
     */
     
        loadInitialDrivers();
    
        String theDriverList = System.getProperty("jdbc.drivers", null); //$NON-NLS-1$
        if (theDriverList == null) {
            return;
        }

        /*
         * Get the names of the drivers as an array of Strings from the system
         * property by splitting the property at the separator character ':'
         */
        String[] theDriverNames = theDriverList.split(":"); //$NON-NLS-1$

        for (String element : theDriverNames) {
            try {
                // Load the driver class
                Class
                        .forName(element, true, ClassLoader
                                .getSystemClassLoader());
            } catch (Throwable t) {
                // Ignored
            }
        }
    
public static voidprintln(java.lang.String message)
Prints a message to the current JDBC log stream. This is either the {@code PrintWriter} or (deprecated) the {@code PrintStream}, if set.

param
message the message to print to the JDBC log stream.
since
Android 1.0

        if (thePrintWriter != null) {
            thePrintWriter.println(message);
            thePrintWriter.flush();
        } else if (thePrintStream != null) {
            thePrintStream.println(message);
            thePrintStream.flush();
        }
        /*
         * If neither the PrintWriter not the PrintStream are set, then silently
         * do nothing the message is not recorded and no exception is generated.
         */
        return;
    
public static voidregisterDriver(java.sql.Driver driver)
Registers a given JDBC driver with the {@code DriverManager}.

A newly loaded JDBC driver class should register itself with the {@code DriverManager} by calling this method.

param
driver the {@code Driver} to register with the {@code DriverManager}.
throws
SQLException if a database access error occurs.

        if (driver == null) {
            throw new NullPointerException();
        }
        synchronized (theDriverSet) {
            theDriverSet.add(driver);
        }
    
public static voidsetLogStream(java.io.PrintStream out)
Sets the print stream to use for logging data from the {@code DriverManager} and the JDBC drivers.

deprecated
Use {@link #setLogWriter} instead.
param
out the {@code PrintStream} to use for logging.
since
Android 1.0

        checkLogSecurity();
        thePrintStream = out;
    
public static voidsetLogWriter(java.io.PrintWriter out)
Sets the {@code PrintWriter} that is used by all loaded drivers, and also the {@code DriverManager}.

param
out the {@code PrintWriter} to be used.
since
Android 1.0

        checkLogSecurity();
        thePrintWriter = out;
    
public static voidsetLoginTimeout(int seconds)
Sets the login timeout when connecting to a database in seconds.

param
seconds seconds until timeout. 0 indicates wait forever.
since
Android 1.0

        loginTimeout = seconds;
        return;