Database connections

Opening a connection

When you want to access a database, you may obtain a java.sql.Connection object from the JDBC management layer's java.sql.DriverManager.getConnection method.

The DriverManager.getConnection method takes a URL string as an argument. The JDBC management layer will attempt to locate a driver that can connect to the database represented by the URL. The JDBC management layer does this by asking each driver in turn if it can connect to the given URL. Drivers should examine the URL to see if it specifies a subprotocol that they support, and if so, they should attempt to connect to the specified database. If they succeed in establishing a connection, then they should return an appropriate java.sql.Connection object.

From the java.sql.Connection object it is possible to obtain java.sql.Statement, java.sql.PreparedStatement , and java.sql.CallableStatement objects that can be used to execute SQL statement s.

We also permit applications to bypass the JDBC management layer during connection open and explicitly select and use a particular driver.

Choosing between drivers

It may sometimes be the case that several JDBC drivers are capable of connecting to a given URL. For example, when connecting to a given remote database it might be possible to use either a JDBC-ODBC bridge driver, or a JDBC to generic network protocol driver, or to use a driver supplied by the database vendor.

JDBC allows users to specify a driver list by setting a Java property "jdbc.drivers". If this property is defined,then it should be a colon separated list of driver class names, such as "acme.wonder.Driver :foobaz.openNet.Driver:vendor.OurDriver".

When searching for a driver, JDBC will use the first driver it finds that can successfully connect to the given URL. It will first try to use each of the drivers specified in the sql.drivers list, in the order given. It will then proceed to try to use each loaded driver in the order in which the drivers were loaded. It will skip any drivers which are untrusted code, unless they have been loaded from the same source as the code that is trying to open the connection

Connection arguments

When opening a connection, you can pass in a java.util.Properties object. This object is a property set that maps between tag strings and value strings. Two conventional properties are "user" and "password". Particular drivers may specify and use other properties.

In order to allow applets to access databases in a generic way, we recommend that as much connection information as possible be encoded as part of the URL and that driver writers minimize their use of property sets.

Multiple connections

A single application can maintain multiple database connections to one or more databases, using one or more drivers.

Registering drivers

The JDBC management layer needs to know which database drivers are available. We provide two ways of doing this.

First, when the JDBC java.sql.DriverManager class initializes it will look for a "sql.drivers" property in the system properties. If the property exists it should consist of a colon-separated list of driver class names. Each of the named classes should implement the java.sql.Driver interface. The DriverManager class will attempt to load each named Driver class.

Second, a programmer can explicitly load a driver class using the standard Class.forName method. For example, to load the acme.db.Driver class you might do:

    Class.forName("acme.db.Driver");

In both cases it is the responsibility of each newly loaded Driver class to register itself with the DriverManager, using the DriverManager.registerDriver method. This will allow the DriverManager to use the driver when it is attempting to make database connections.

For security reasons the JDBC management layer will keep track of which class loader provided which driver and when opening connections it will only use drivers that come from the local filesystem or from the same classloader as the code issuing the getConnection request.