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

Nested Class Summary
protected  class Driver.ControllerInfo
           
 
Field Summary
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 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  Driver.ControllerInfo currentControllerConfig
           
private  java.lang.String currentControllerURL
          Controller.
private  java.lang.String currentDatabase
           
private 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.
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 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
           
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.
 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  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)  void parseURL(java.lang.String url)
          Checks for URL correctness and adds controllers list and database name to the cache.
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

private 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

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

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.


currentControllerConfig

private Driver.ControllerInfo currentControllerConfig

currentDatabase

private java.lang.String currentDatabase
Constructor Detail

Driver

public Driver()
       throws java.sql.SQLException
Creates a new Driver and register it with DriverManager.

Throws:
java.sql.SQLException - if an error occurs
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

void 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.

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: HOST_PROPERTY, PORT_PROPERTY, CONTROLLER_PROPERTY, DATABASE_PROPERTY, USER_PROPERTY and PASSWORD_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.
Throws:
java.sql.SQLException - if a database-access error occurs.
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

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.


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