org.objectweb.cjdbc.driver
Class Driver

java.lang.Object
  extended byorg.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");
 

This 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

Nested Class Summary
 class Driver.ControllerInfo
          Controller related information, namely the host name and the port on which the controller is running.
 
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
           
private static java.lang.String CJDBC_URL_HEADER
          C-JDBC URL header.
private static int CJDBC_URL_HEADER_LENGTH
          C-JDBC URL header length.
protected  boolean connectionClosingThreadisAlive
           
private  int connectionRequestSinceControllerFailure
           
private static java.lang.String CONTROLLER_PROPERTY
           
private  java.util.HashMap controllerCache
          Cache of parsed URL (ControllerInfo objects defined at the end of this class) used to connect to the controller.
private  java.util.ArrayList controllerConfig
           
private  int controllerConfigArraySize
           
private  Driver.ControllerInfo currentControllerConfig
           
private  java.lang.String currentControllerURL
          Controller.
private  java.lang.String currentDatabase
           
protected static java.lang.String DATABASE_PROPERTY
           
private static java.lang.String DATABASE_PROPERTY_DESCRIPTION
           
private  java.util.HashMap dbNameCache
          Cache of database names and matching URLs.
protected static java.lang.String DRIVER_PROCESSED_PROPERTY
           
private static java.lang.String DRIVER_PROCESSED_PROPERTY_DESCRIPTION
           
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
           
private static java.lang.String HOST_PROPERTY
          C-JDBC driver property name.
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.
protected static java.lang.String PARAMETER_PROPERTY
           
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.
private static java.lang.String PORT_PROPERTY
           
private static java.lang.String PORT_PROPERTY_DESCRIPTION
           
private  java.util.Random random
           
private static int RETRY_CONTROLLER_AFTER_FAILURE
           
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.sql.Connection connect(java.lang.String url, java.util.Properties info)
          Asks the C-JDBC controller if the requested database can be accessed with the provided user name and password.
protected  java.util.ArrayList getControllerConfig()
          Returns the controllerConfig value.
 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.
protected  java.lang.String getUrlFromProperties(java.util.Hashtable props)
          Feed in a set of properties and get the url as a String
 boolean jdbcCompliant()
          Reports whether the driver is a genuine JDBC compliant driver.
private  Driver.ControllerInfo parseController(java.lang.String controller)
          Checks the validity of the hostname, port number and controller name given in the URL and build the full URL used to lookup a controller.
(package private)  java.util.Hashtable parseURL(java.lang.String url)
          Checks for URL correctness and adds controllers list and database name to the cache.
private  java.util.Hashtable parseUrlParams(java.lang.String url)
           
private  java.util.Hashtable parseUrlParams(java.lang.String url, char mark, java.lang.String link, java.lang.String equal)
           
private  java.sql.Connection setParametersOnConnection(java.util.Properties props, Connection connection)
          Set the different parameters on the connection.
private static java.lang.Character validDatabaseName(java.lang.String databaseName)
          Checks that the given name contains acceptable characters for a database name ([0-9][A-Z][a-z]).
private static java.lang.Character validHostname(java.lang.String hostname)
          Checks that the given name contains acceptable characters for a hostname name ([0-9][A-Z][a-z][.]).
 
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.


HOST_PROPERTY

private static final java.lang.String HOST_PROPERTY
C-JDBC driver property name.

See Also:
Constant Field Values

PORT_PROPERTY

private static final java.lang.String PORT_PROPERTY
See Also:
Constant Field Values

CONTROLLER_PROPERTY

private static final java.lang.String CONTROLLER_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

PARAMETER_PROPERTY

protected static final java.lang.String PARAMETER_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

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

CJDBC_URL_HEADER

private static final java.lang.String CJDBC_URL_HEADER
C-JDBC URL header.

See Also:
Constant Field Values

CJDBC_URL_HEADER_LENGTH

private static final int CJDBC_URL_HEADER_LENGTH
C-JDBC URL header length.


controllerCache

private java.util.HashMap controllerCache
Cache of parsed URL (ControllerInfo objects defined at the end of this class) used to connect to the controller.


dbNameCache

private java.util.HashMap dbNameCache
Cache of database names and matching URLs.


pendingConnectionClosing

protected java.util.ArrayList pendingConnectionClosing
List of connections that are ready to be closed.


connectionClosingThreadisAlive

protected boolean connectionClosingThreadisAlive

currentControllerURL

private java.lang.String currentControllerURL
Controller.


controllerConfig

private java.util.ArrayList controllerConfig

currentControllerConfig

private Driver.ControllerInfo currentControllerConfig

currentDatabase

private java.lang.String currentDatabase

random

private java.util.Random random

controllerConfigArraySize

private int controllerConfigArraySize

connectionRequestSinceControllerFailure

private int connectionRequestSinceControllerFailure

RETRY_CONTROLLER_AFTER_FAILURE

private static final int RETRY_CONTROLLER_AFTER_FAILURE
See Also:
Constant Field Values
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 info)
                            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.
info - 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.

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.

parseURL

java.util.Hashtable parseURL(java.lang.String url)
                       throws java.sql.SQLException
Checks for URL correctness and adds controllers list and database name to the cache.

Parameters:
url - the URL of the C-JDBC controller to which to connect.
Throws:
java.sql.SQLException - if an error occurs.

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

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

getUrlFromProperties

protected java.lang.String getUrlFromProperties(java.util.Hashtable props)
Feed in a set of properties and get the url as a String

Parameters:
props - as defined statically at the top of the class
Returns:
String describing the url

parseUrlParams

private java.util.Hashtable parseUrlParams(java.lang.String url)
                                    throws java.sql.SQLException
Throws:
java.sql.SQLException

parseUrlParams

private java.util.Hashtable parseUrlParams(java.lang.String url,
                                           char mark,
                                           java.lang.String link,
                                           java.lang.String equal)
                                    throws java.sql.SQLException
Throws:
java.sql.SQLException

parseController

private Driver.ControllerInfo parseController(java.lang.String controller)
                                       throws java.sql.SQLException
Checks the validity of the hostname, port number and controller name given in the URL and build the full URL used to lookup a controller.

Parameters:
controller - information regarding a controller.
Returns:
a ControllerInfo object
Throws:
java.sql.SQLException - if an error occurs.

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:


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

validHostname

private static java.lang.Character validHostname(java.lang.String hostname)
Checks that the given name contains acceptable characters for a hostname name ([0-9][A-Z][a-z][.]).

Parameters:
hostname - name to check (caller must check that it is not null).
Returns:
null if the hostname is acceptable, else the character that causes the fault.

validDatabaseName

private static java.lang.Character validDatabaseName(java.lang.String databaseName)
Checks that the given name contains acceptable characters for a database name ([0-9][A-Z][a-z]).

Parameters:
databaseName - name to check (caller must check that it is not null).
Returns:
null if the name is acceptable, else the character that causes the fault.

getControllerConfig

protected java.util.ArrayList getControllerConfig()
Returns the controllerConfig value.

Returns:
Returns the controllerConfig.


Copyright © 2002, 2005 - ObjectWeb Consortium - All Rights Reserved.