org.objectweb.cjdbc.driver
Class Driver

java.lang.Object
  org.objectweb.cjdbc.driver.Driver

All Implemented Interfaces:

java.sql.Driver

public class Driver

extends java.lang.Object

implements java.sql.Driver

C-JDBC Driver for client side. This driver is a generic driver that is designed to replace any specific JDBC driver that could be used by a client. The client only has to know the node where the C-JDBC controller is running and the database he wants to access (the RDBMS could be PostgreSQL, Oracle, DB2, Sybase, MySQL or whatever, we only need the name of the database and the C-JDBC controller will be responsible for finding the RDBMs hosting this database).

The C-JDBC driver can be loaded from the client with: Class.forName("org.objectweb.cjdbc.driver.Driver");

The URL expected for the use with C-JDBC is: jdbc:cjdbc://host1:port1,host2:port2/database.

At least one host must be specified. If several hosts are given, one is picked up randomly from the list. If the currently selected controller fails, another one is automatically picked up from the list.

Default port number is 25322 if omitted.

Those 2 examples are equivalent:

 DriverManager.getConnection("jdbc:cjdbc://localhost:/tpcw");
 DriverManager.getConnection("jdbc:cjdbc://localhost:25322/tpcw");
 

Examples using 2 controllers for fault tolerance:

 DriverManager
     .getConnection("jdbc:cjdbc://cluster1.objectweb.org:25322,cluster2.objectweb.org:25322/tpcw");
 DriverManager
     .getConnection("jdbc:cjdbc://localhost:25322,remote.objectweb.org:25322/tpcw");
 DriverManager
     .getConnection("jdbc:cjdbc://smpnode.com:25322,smpnode.com:1098/tpcw");
 

The driver accepts a number of options that starts after a ? sign and are separated by an & sign. Each option is a name=value pair. Example: jdbc:cjdbc://host/db?option1=value1;option2=value2.

Currently supported options are:

 user: user login
 password: user password
 booleanTrue: value for the 'true' value when using PreparedStatement.setBoolean method
 booleanFalse: value for the 'false' value when using PreparedStatement.setBoolean method
 escapeBackslash: set this to true to escape backslashes when performing escape processing of PreparedStatements
 escapeSingleQuote: set this to true to escape single quotes (') when performing escape processing of PreparedStatements
 escapeCharacter: use this character to prepend and append to the values when performing escape processing of PreparedStatements
 driverProcessed: set this to false to let queries be passed and prepared for each individual backend
 connectionPooling: set this to false if you do not want the driver to perform transparent connection pooling
 preferredController: defines the strategy to use to choose a preferred controller to connect to
  - jdbc:cjdbc://node1,node2,node3/myDB?preferredController=ordered 
      Always connect to node1, and if not available then try to node2 and
      finally if none are available try node3.
  - jdbc:cjdbc://node1,node2,node3/myDB?preferredController=random
      Pickup a controller node randomly (default strategy)
  - jdbc:cjdbc://node1,node2:25343,node3/myDB?preferredController=node2:25343,node3 
      Round-robin between node2 and node3, fallback to node1 if none of node2
      and node3 is available.
  - jdbc:cjdbc://node1,node2,node3/myDB?preferredController=roundRobin
      Round robin starting with first node in URL.
 retryIntervalInMs: once a controller has died, the driver will try to 
   reconnect to this controller every retryIntervalInMs to see if the backend
   is back online. The default is 5000 (5 seconds).
 

This original code has been inspired from the PostgreSQL JDBC driver by Peter T. Mount and the MM MySQL JDBC Drivers from Mark Matthews .

Version:

1.0

Author:

Emmanuel Cecchet , Julie Marguerite , Mathieu Peltier , Marek Prochazka , Nicolas Modrzyk , Jaco Swart

Field Summary

protected static java.lang.String	BOOLEAN_FALSE_PROPERTY
private static java.lang.String	BOOLEAN_FALSE_PROPERTY_DESCRIPTION
protected static java.lang.String	BOOLEAN_TRUE_PROPERTY
private static java.lang.String	BOOLEAN_TRUE_PROPERTY_DESCRIPTION
static java.lang.String	CJDBC_URL_HEADER C-JDBC URL header.
static int	CJDBC_URL_HEADER_LENGTH C-JDBC URL header length.
protected static java.lang.String	CONNECTION_POOLING_PROPERTY
protected static java.lang.String	CONNECTION_POOLING_PROPERTY_DESCRIPTION
protected boolean	connectionClosingThreadisAlive
protected static java.lang.String	DATABASE_PROPERTY
private static java.lang.String	DATABASE_PROPERTY_DESCRIPTION
protected static java.lang.String	DEBUG_PROPERTY
protected static java.lang.String	DEBUG_PROPERTY_DESCRIPTION
static long	DEFAULT_RETRY_INTERVAL_IN_MS Default interval in milliseconds before retrying to re-connect to a controller that has failed (default is 5 seconds or 5000 milliseconds)
protected static java.lang.String	DRIVER_PROCESSED_PROPERTY
private static java.lang.String	DRIVER_PROCESSED_PROPERTY_DESCRIPTION
protected static java.util.ArrayList	driverProperties List of driver properties initialized in the static class initializer !!!
protected static java.lang.String	ESCAPE_BACKSLASH_PROPERTY
private static java.lang.String	ESCAPE_BACKSLASH_PROPERTY_DESCRIPTION
protected static java.lang.String	ESCAPE_CHARACTER_PROPERTY
private static java.lang.String	ESCAPE_CHARACTER_PROPERTY_DESCRIPTION
protected static java.lang.String	ESCAPE_SINGLE_QUOTE_PROPERTY
private static java.lang.String	ESCAPE_SINGLE_QUOTE_PROPERTY_DESCRIPTION
protected static java.lang.String	HOST_PROPERTY C-JDBC driver property name (if you add one, read driverProperties above).
private static java.lang.String	HOST_PROPERTY_DESCRIPTION C-JDBC driver property description.
static int	MAJOR_VERSION Driver major version.
static int	MINOR_VERSION Driver minor version.
private java.util.HashMap	parsedUrlsCache Cache of parsed URLs used to connect to the controller.
protected static java.lang.String	PASSWORD_PROPERTY
private static java.lang.String	PASSWORD_PROPERTY_DESCRIPTION
protected java.util.ArrayList	pendingConnectionClosing List of connections that are ready to be closed.
protected static java.lang.String	PORT_PROPERTY
private static java.lang.String	PORT_PROPERTY_DESCRIPTION
protected static java.lang.String	PREFERRED_CONTROLLER_PROPERTY
protected static java.lang.String	PREFERRED_CONTROLLER_PROPERTY_DESCRIPTION
protected static java.lang.String	RETRY_INTERVAL_IN_MS_PROPERTY
protected static java.lang.String	RETRY_INTERVAL_IN_MS_PROPERTY_DESCRIPTION
protected static boolean	SSL_ENABLED_PROPERTY Get the cjdbc.ssl.enabled system property to check if SSL is enabled
protected static java.lang.String	USER_PROPERTY
private static java.lang.String	USER_PROPERTY_DESCRIPTION

Constructor Summary

Driver()
Creates a new Driver and register it with DriverManager.

Method Summary

boolean	acceptsURL(java.lang.String url) Tests if the URL is understood by the driver.
java.lang.String	changeDatabaseName(java.lang.String url, java.lang.String newDbName) Change the database name in the provided URL.
java.sql.Connection	connect(java.lang.String url, java.util.Properties properties) Asks the C-JDBC controller if the requested database can be accessed with the provided user name and password.
protected java.sql.Connection	connectToController(java.util.Properties properties, CjdbcUrl cjdbcUrl, ControllerInfo controller) Connect to the given controller with the specified parameters.
int	getMajorVersion() Gets the river's major version number
int	getMinorVersion() Gets the driver's minor version number
java.sql.DriverPropertyInfo[]	getPropertyInfo(java.lang.String url, java.util.Properties info) This method is intended to allow a generic GUI tool to discover what properties it should prompt a human for in order to get enough information to connect to a database.
boolean	jdbcCompliant() Reports whether the driver is a genuine JDBC compliant driver.
private java.sql.Connection	retrievePendingClosingConnection(java.util.Properties connectionInfo, java.lang.String url, ControllerInfo controllerInfo, java.lang.String user, java.lang.String password) This method is used to implement the transparent connection pooling and try to retrieve a connection that was recently closed to the given controller with the provided login/password information.
private java.sql.Connection	setParametersOnConnection(java.util.Properties props, Connection connection) Set the different parameters on the connection.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAJOR_VERSION

public static final int MAJOR_VERSION

Driver major version.

MINOR_VERSION

public static final int MINOR_VERSION

Driver minor version.

SSL_ENABLED_PROPERTY

protected static final boolean SSL_ENABLED_PROPERTY

Get the cjdbc.ssl.enabled system property to check if SSL is enabled

DEFAULT_RETRY_INTERVAL_IN_MS

public static final long DEFAULT_RETRY_INTERVAL_IN_MS

Default interval in milliseconds before retrying to re-connect to a controller that has failed (default is 5 seconds or 5000 milliseconds)

See Also:

Constant Field Values

driverProperties

protected static java.util.ArrayList driverProperties

List of driver properties initialized in the static class initializer

!!! Static intializer needs to be udpated when new properties are added !!!

HOST_PROPERTY

protected static final java.lang.String HOST_PROPERTY

C-JDBC driver property name (if you add one, read driverProperties above).

See Also:

Constant Field Values

PORT_PROPERTY

protected static final java.lang.String PORT_PROPERTY

See Also:

Constant Field Values

DATABASE_PROPERTY

protected static final java.lang.String DATABASE_PROPERTY

See Also:

Constant Field Values

USER_PROPERTY

protected static final java.lang.String USER_PROPERTY

See Also:

Constant Field Values

PASSWORD_PROPERTY

protected static final java.lang.String PASSWORD_PROPERTY

See Also:

Constant Field Values

BOOLEAN_TRUE_PROPERTY

protected static final java.lang.String BOOLEAN_TRUE_PROPERTY

See Also:

Constant Field Values

BOOLEAN_FALSE_PROPERTY

protected static final java.lang.String BOOLEAN_FALSE_PROPERTY

See Also:

Constant Field Values

ESCAPE_BACKSLASH_PROPERTY

protected static final java.lang.String ESCAPE_BACKSLASH_PROPERTY

See Also:

Constant Field Values

ESCAPE_SINGLE_QUOTE_PROPERTY

protected static final java.lang.String ESCAPE_SINGLE_QUOTE_PROPERTY

See Also:

Constant Field Values

ESCAPE_CHARACTER_PROPERTY

protected static final java.lang.String ESCAPE_CHARACTER_PROPERTY

See Also:

Constant Field Values

DRIVER_PROCESSED_PROPERTY

protected static final java.lang.String DRIVER_PROCESSED_PROPERTY

See Also:

Constant Field Values

CONNECTION_POOLING_PROPERTY

protected static final java.lang.String CONNECTION_POOLING_PROPERTY

See Also:

Constant Field Values

PREFERRED_CONTROLLER_PROPERTY

protected static final java.lang.String PREFERRED_CONTROLLER_PROPERTY

See Also:

Constant Field Values

RETRY_INTERVAL_IN_MS_PROPERTY

protected static final java.lang.String RETRY_INTERVAL_IN_MS_PROPERTY

See Also:

Constant Field Values

DEBUG_PROPERTY

protected static final java.lang.String DEBUG_PROPERTY

See Also:

Constant Field Values

HOST_PROPERTY_DESCRIPTION

private static final java.lang.String HOST_PROPERTY_DESCRIPTION

C-JDBC driver property description.

See Also:

Constant Field Values

PORT_PROPERTY_DESCRIPTION

private static final java.lang.String PORT_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

DATABASE_PROPERTY_DESCRIPTION

private static final java.lang.String DATABASE_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

USER_PROPERTY_DESCRIPTION

private static final java.lang.String USER_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

PASSWORD_PROPERTY_DESCRIPTION

private static final java.lang.String PASSWORD_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

BOOLEAN_TRUE_PROPERTY_DESCRIPTION

private static final java.lang.String BOOLEAN_TRUE_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

BOOLEAN_FALSE_PROPERTY_DESCRIPTION

private static final java.lang.String BOOLEAN_FALSE_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

ESCAPE_BACKSLASH_PROPERTY_DESCRIPTION

private static final java.lang.String ESCAPE_BACKSLASH_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

ESCAPE_SINGLE_QUOTE_PROPERTY_DESCRIPTION

private static final java.lang.String ESCAPE_SINGLE_QUOTE_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

ESCAPE_CHARACTER_PROPERTY_DESCRIPTION

private static final java.lang.String ESCAPE_CHARACTER_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

DRIVER_PROCESSED_PROPERTY_DESCRIPTION

private static final java.lang.String DRIVER_PROCESSED_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

CONNECTION_POOLING_PROPERTY_DESCRIPTION

protected static final java.lang.String CONNECTION_POOLING_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

PREFERRED_CONTROLLER_PROPERTY_DESCRIPTION

protected static final java.lang.String PREFERRED_CONTROLLER_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

RETRY_INTERVAL_IN_MS_PROPERTY_DESCRIPTION

protected static final java.lang.String RETRY_INTERVAL_IN_MS_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

DEBUG_PROPERTY_DESCRIPTION

protected static final java.lang.String DEBUG_PROPERTY_DESCRIPTION

See Also:

Constant Field Values

CJDBC_URL_HEADER

public static final java.lang.String CJDBC_URL_HEADER

C-JDBC URL header.

See Also:

Constant Field Values

CJDBC_URL_HEADER_LENGTH

public static final int CJDBC_URL_HEADER_LENGTH

C-JDBC URL header length.

parsedUrlsCache

private java.util.HashMap parsedUrlsCache

Cache of parsed URLs used to connect to the controller. It always grows and is never purged: we don't yet handle the unlikely case of a long-lived driver using zillions of different URLs.

Hashmap is URL=> CjdbcUrl

pendingConnectionClosing

protected java.util.ArrayList pendingConnectionClosing

List of connections that are ready to be closed.

connectionClosingThreadisAlive

protected boolean connectionClosingThreadisAlive

Constructor Detail

Driver

public Driver()

Creates a new Driver and register it with DriverManager.

Method Detail

connect

public java.sql.Connection connect(java.lang.String url,
                                   java.util.Properties properties)
                            throws java.sql.SQLException

Asks the C-JDBC controller if the requested database can be accessed with the provided user name and password. If the C-JDBC controller can't access the requested database, an SQLException is thrown, else a "fake" Connection is returned to the user so that he or she can create Statements.

Specified by:

connect in interface java.sql.Driver

Parameters:

url - the URL of the C-JDBC controller to which to connect.

properties - a list of arbitrary string tag/value pairs as connection arguments (usually at least a "user" and "password").

Returns:

a Connection object that represents a connection to the database through the C-JDBC Controller.

Throws:

java.sql.SQLException - if an error occurs.

connectToController

protected java.sql.Connection connectToController(java.util.Properties properties,
                                                  CjdbcUrl cjdbcUrl,
                                                  ControllerInfo controller)
                                           throws AuthenticationException,
                                                  DriverSQLException

Connect to the given controller with the specified parameters.

Parameters:

properties - properties given in connect call

cjdbcUrl - C-JDBC URL object including parameters

controller - the controller to connect to

Returns:

the connection to the controller

Throws:

AuthenticationException - if the authentication has failed or the database name is wrong

DriverSQLException - if the connection cannot be established with the controller

retrievePendingClosingConnection

private java.sql.Connection retrievePendingClosingConnection(java.util.Properties connectionInfo,
                                                             java.lang.String url,
                                                             ControllerInfo controllerInfo,
                                                             java.lang.String user,
                                                             java.lang.String password)

This method is used to implement the transparent connection pooling and try to retrieve a connection that was recently closed to the given controller with the provided login/password information.

Parameters:

connectionInfo - the connectino information

url -

Returns:

a connection that could be reuse or null if none

acceptsURL

public boolean acceptsURL(java.lang.String url)
                   throws java.sql.SQLException

Tests if the URL is understood by the driver. Calls the parseURL() method.

Specified by:

acceptsURL in interface java.sql.Driver

Parameters:

url - the JDBC URL.

Returns:

true if the URL is correct, otherwise an exception with extensive error message is thrown.

Throws:

java.sql.SQLException - if the URL is incorrect an explicit error message is given.

setParametersOnConnection

private java.sql.Connection setParametersOnConnection(java.util.Properties props,
                                                      Connection connection)

Set the different parameters on the connection. Possible values are: BOOLEAN_TRUE_PROPERTY
BOOLEAN_FALSE_PROPERTY
ESCAPE_BACKSLASH_PROPERTY
ESCAPE_SINGLE_QUOTE_PROPERTY
ESCAPE_CHARACTER_PROPERTY
DRIVER_PROCESSED_PROPERTY
CONNECTION_POOLING_PROPERTY

Parameters:

props - the properties used to connect to the controller. These properties should be collected from both the url and the Properties object passed in to the connect method

connection - the connection to set the parameters on. Previous parameters will be overriden

Returns:

the same connection with the parameters set

changeDatabaseName

public java.lang.String changeDatabaseName(java.lang.String url,
                                           java.lang.String newDbName)
                                    throws java.sql.SQLException

Change the database name in the provided URL.

Parameters:

url - URL to parse

newDbName - new database name to insert

Returns:

the updated URL

Throws:

java.sql.SQLException - if an error occurs while parsing the url

getPropertyInfo

public java.sql.DriverPropertyInfo[] getPropertyInfo(java.lang.String url,
                                                     java.util.Properties info)
                                              throws java.sql.SQLException

This method is intended to allow a generic GUI tool to discover what properties it should prompt a human for in order to get enough information to connect to a database.

The only properties supported by C-JDBC are:

• HOST_PROPERTY
• PORT_PROPERTY
• DATABASE_PROPERTY
• USER_PROPERTY
• PASSWORD_PROPERTY
• ESCAPE_BACKSLASH_PROPERTY
• ESCAPE_CHARACTER_PROPERTY
• ESCAPE_SINGLE_QUOTE
• BOOLEAN_FALSE_PROPERTY
• BOOLEAN_TRUE_PROPERTY
• DRIVER_PROCESSED_PROPERTY
• CONNECTION_POOLING_PROPERTY
• PREFERRED_CONTROLLER_PROPERTY

Specified by:

getPropertyInfo in interface java.sql.Driver

Parameters:

url - the URL of the database to connect to

info - a proposed list of tag/value pairs that will be sent on connect open.

Returns:

an array of DriverPropertyInfo objects describing possible properties. This array may be an empty array if no properties are required (note that this override any setting that might be set in the URL).

Throws:

java.sql.SQLException - if the url is not valid

See Also:

Driver.getPropertyInfo(java.lang.String, java.util.Properties)

getMajorVersion

public int getMajorVersion()

Gets the river's major version number

Specified by:

getMajorVersion in interface java.sql.Driver

Returns:

the driver's major version number

getMinorVersion

public int getMinorVersion()

Gets the driver's minor version number

Specified by:

getMinorVersion in interface java.sql.Driver

Returns:

the driver's minor version number

jdbcCompliant

public boolean jdbcCompliant()

Reports whether the driver is a genuine JDBC compliant driver. A driver may only report true here if it passes the JDBC compliance tests, otherwise it is required to return false. JDBC compliance requires full support for the JDBC API and full support for SQL 92 Entry Level. We cannot ensure that the underlying JDBC drivers will be JDBC compliant, so it is safer to return false.

Specified by:

jdbcCompliant in interface java.sql.Driver

Returns:

always false