Driver.java

/**
 * C-JDBC: Clustered JDBC.
 * Copyright (C) 2002-2005 French National Institute For Research In Computer
 * Science And Control (INRIA).
 * Contact: c-jdbc@objectweb.org
 * 
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by the
 * Free Software Foundation; either version 2.1 of the License, or any later
 * version.
 * 
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
 *
 * Initial developer(s): Emmanuel Cecchet.
 * Contributor(s): Julie Marguerite, Mathieu Peltier, Marek Prochazka, Sara
 * Bouchenak, Jaco Swart.
 */

package org.objectweb.cjdbc.driver;

import java.io.IOException;
import java.net.Socket;
import java.sql.DriverPropertyInfo;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Hashtable;
import java.util.Properties;
import java.util.Random;
import java.util.StringTokenizer;

import javax.net.SocketFactory;

import org.objectweb.cjdbc.common.net.SSLConfiguration;
import org.objectweb.cjdbc.common.net.SocketFactoryFactory;
import org.objectweb.cjdbc.common.sql.filters.AbstractBlobFilter;
import org.objectweb.cjdbc.common.stream.CJDBCInputStream;
import org.objectweb.cjdbc.common.stream.CJDBCOutputStream;
import org.objectweb.cjdbc.common.util.Constants;
import org.objectweb.cjdbc.controller.core.ControllerConstants;
import org.objectweb.cjdbc.driver.protocol.Commands;

/**
 * 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).
 * <p>
 * The C-JDBC driver can be loaded from the client with:
 * <code>Class.forName("org.objectweb.cjdbc.driver.Driver");</code>
 * <p>
 * The URL expected for the use with C-JDBC is:
 * <code>jdbc:cjdbc://host1:port1,host2:port2/database</code>.
 * <p>
 * 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.
 * <p>
 * Default port number is 25322 if omitted.
 * <p>
 * Those 2 examples are equivalent:
 * 
 * <pre>
 * DriverManager.getConnection(&quot;jdbc:cjdbc://localhost:/tpcw&quot;);
 * DriverManager.getConnection(&quot;jdbc:cjdbc://localhost:25322/tpcw&quot;);
 * </pre>
 * 
 * <p>
 * Examples using 2 controllers for fault tolerance:
 * 
 * <pre>
 * DriverManager
 *     .getConnection(&quot;jdbc:cjdbc://cluster1.objectweb.org:25322,cluster2.objectweb.org:25322/tpcw&quot;);
 * DriverManager
 *     .getConnection(&quot;jdbc:cjdbc://localhost:25322,remote.objectweb.org:25322/tpcw&quot;);
 * DriverManager
 *     .getConnection(&quot;jdbc:cjdbc://smpnode.com:25322,smpnode.com:1098/tpcw&quot;);
 * </pre>
 * 
 * <p>
 * This code has been inspired from the PostgreSQL JDBC driver by Peter T. Mount
 * <peter@retep.org.uk>and the MM MySQL JDBC Drivers from Mark Matthews
 * <mmatthew@worldserver.com>.
 * 
 * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
 * @author <a href="mailto:Julie.Marguerite@inria.fr">Julie Marguerite </a>
 * @author <a href="mailto:Mathieu.Peltier@inrialpes.fr">Mathieu Peltier </a>
 * @author <a href="mailto:Marek.Prochazka@inrialpes.fr">Marek Prochazka </a>
 * @author <a href="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
 * @author <a href="mailto:jaco.swart@iblocks.co.uk">Jaco Swart </a>
 * @version 1.0
 */

public class Driver implements java.sql.Driver
{
  /** Driver major version. */
  public static final int       MAJOR_VERSION                            = Constants
                                                                             .getMajorVersion();

  /** Driver minor version. */
  public static final int       MINOR_VERSION                            = Constants
                                                                             .getMinorVersion();

  /** C-JDBC driver property name. */
  private static final String   HOST_PROPERTY                            = "HOST";
  private static final String   PORT_PROPERTY                            = "PORT";
  private static final String   CONTROLLER_PROPERTY                      = "CONTROLLER";
  protected static final String DATABASE_PROPERTY                        = "DATABASE";
  protected static final String USER_PROPERTY                            = "user";
  protected static final String PASSWORD_PROPERTY                        = "password";
  protected static final String PARAMETER_PROPERTY                       = "parameter";
  protected static final String BOOLEAN_TRUE_PROPERTY                    = "booleanTrue";
  protected static final String BOOLEAN_FALSE_PROPERTY                   = "booleanFalse";
  protected static final String ESCAPE_BACKSLASH_PROPERTY                = "escapeBackslash";
  protected static final String ESCAPE_SINGLE_QUOTE_PROPERTY             = "escapeSingleQuote";
  protected static final String ESCAPE_CHARACTER_PROPERTY                = "escapeCharacter";
  protected static final String DRIVER_PROCESSED_PROPERTY                = "driverProcessed";

  /** C-JDBC driver property description. */
  private static final String   HOST_PROPERTY_DESCRIPTION                = "Hostname of C-JDBC controller";
  private static final String   PORT_PROPERTY_DESCRIPTION                = "Port number of C-JDBC controller";
  private static final String   DATABASE_PROPERTY_DESCRIPTION            = "Database name";
  private static final String   USER_PROPERTY_DESCRIPTION                = "Username to authenticate as";
  private static final String   PASSWORD_PROPERTY_DESCRIPTION            = "Password to use for authentication";
  private static final String   BOOLEAN_TRUE_PROPERTY_DESCRIPTION        = "Use this value for the 'true' value when using PreparedStatement.setBoolean method";
  private static final String   BOOLEAN_FALSE_PROPERTY_DESCRIPTION       = "Use this value for the 'false' value when using PreparedStatement.setBoolean method";
  private static final String   ESCAPE_BACKSLASH_PROPERTY_DESCRIPTION    = "Set this to true to escape backslashes when performing escape processing of PreparedStatements";
  private static final String   ESCAPE_SINGLE_QUOTE_PROPERTY_DESCRIPTION = "Set this to true to escape single quotes (') when performing escape processing of PreparedStatements";
  private static final String   ESCAPE_CHARACTER_PROPERTY_DESCRIPTION    = "Use this character to prepend and append to the values when performing escape processing of PreparedStatements";
  private static final String   DRIVER_PROCESSED_PROPERTY_DESCRIPTION    = "Set this to false to let queries be passed and prepared for each individual backend";

  /** C-JDBC URL header. */
  private static final String   CJDBC_URL_HEADER                         = "jdbc:cjdbc://";

  /** C-JDBC URL header length. */
  private static final int      CJDBC_URL_HEADER_LENGTH                  = CJDBC_URL_HEADER
                                                                             .length();

  /**
   * Cache of parsed URL (<code>ControllerInfo</code> objects defined at the
   * end of this class) used to connect to the controller.
   */
  private HashMap               controllerCache                          = new HashMap();

  /** Cache of database names and matching URLs. */
  private HashMap               dbNameCache                              = new HashMap();

  /** List of connections that are ready to be closed. */
  protected ArrayList           pendingConnectionClosing                 = new ArrayList();
  protected boolean             connectionClosingThreadisAlive           = false;

  /** Controller. */
  private String                currentControllerURL                     = null;
  private ArrayList             controllerConfig                         = null;
  private ControllerInfo        currentControllerConfig                  = null;
  private String                currentDatabase                          = null;
  private Random                random;
  private int                   controllerConfigArraySize;
  private int                   connectionRequestSinceControllerFailure  = 0;
  // Retry to reconnect to a controller after RETRY_CONTROLLER_AFTER_FAILURE
  // connection requests have been treated since the failure.
  private static final int      RETRY_CONTROLLER_AFTER_FAILURE           = 10;

  // The static initializer registers ourselves with the DriverManager
  // and try to bind the C-JDBC Controller
  static
  {
    // Register with the DriverManager (see JDBC API Tutorial and Reference,
    // Second Edition p. 941)
    try
    {
      java.sql.DriverManager.registerDriver(new Driver());
    }
    catch (SQLException e)
    {
      throw new RuntimeException("Unable to register C-JDBC driver");
    }
  }

  /**
   * Creates a new <code>Driver</code> and register it with
   * <code>DriverManager</code>.
   */
  public Driver()
  {
    // Required for Class.forName().newInstance()
    random = new Random(System.currentTimeMillis());
  }

  /**
   * 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 <code>SQLException</code> is thrown, else a
   * "fake" <code>Connection</code> is returned to the user so that he or she
   * can create <code>Statements</code>.
   * 
   * @param url the URL of the C-JDBC controller to which to connect.
   * @param info a list of arbitrary string tag/value pairs as connection
   *          arguments (usually at least a "user" and "password").
   * @return a <code>Connection</code> object that represents a connection to
   *         the database through the C-JDBC Controller.
   * @exception SQLException if an error occurs.
   */
  public java.sql.Connection connect(String url, Properties info)
      throws SQLException
  {
    if (url == null)
      throw new SQLException("Invalid null URL in connect");

    /**
     * We cannot raise a SQLException as the driver manager tries to connect to
     * all registered drivers. So if the CJDBC_URL_HEADER is not found we should
     * probably pass... and return <code>null</code>
     */
    if (!url.toLowerCase().startsWith(CJDBC_URL_HEADER))
      return null;

    String user = null;
    if (info != null)
      user = info.getProperty(USER_PROPERTY);
    else
    {
      info = new Properties();
    }

    // Parse url to get parameters
    Hashtable props = this.parseUrlParams(url);
    if (props != null)
      info.putAll(props);

    if (user == null || user.equals(""))
    {
      if ((user = info.getProperty(USER_PROPERTY)) == null)
        throw new SQLException("Invalid null user name in connect");
    }

    String password = info.getProperty(PASSWORD_PROPERTY);
    if (password == null)
    {
      password = "";
    }

    // SSL enabled ?
    SSLConfiguration ssl = null;
    if ("true".equals(System.getProperty("cjdbc.ssl.enabled")))
    {
      ssl = SSLConfiguration.getDefaultConfig();
    }

    // Check if there is a connection that is about to be closed that could
    // be reused. We take the bet that if a connection has been released by
    // a client, in the general case, it will reuse the same connection.
    // As we need to keep the work in the synchronized block as minimal as
    // possible, we have to extract the string comparison (url,name,password)
    // from the sync block. This way, we cannot just read/compare/take the
    // connection without synchronizing the whole thing. A solution is to
    // systematically extract the first available connection in the sync block,
    // and do the checkings outside the block. If we fail, we re-sync to put
    // the connection back but in practice it is almost always a success and
    // we don't really care to pay this extra cost once in a while.
    try
    {
      Connection c;
      synchronized (pendingConnectionClosing)
      {
        // Take the last one to prevent shifting all elements
        c = (Connection) pendingConnectionClosing
            .remove(pendingConnectionClosing.size() - 1);
      }
      if (url.equals(c.getURL()) && user.equals(c.getUserName())
          && password.equals(c.getPassword()))
      { // Great! Take this one.
        c.isClosed = false;
        return setParametersOnConnection(info, c);
      }
      else
        // Put this connection back, it is not good for us
        synchronized (pendingConnectionClosing)
        {
          pendingConnectionClosing.add(c);
        }
    }
    catch (IndexOutOfBoundsException ignore)
    {
      // No connection available
    }

    int retry = 2;
    int picked;
    while (retry > 0)
    {
      // Check if the last url used was the same, if yes we re-use the
      // same controller and connection point.
      synchronized (this)
      {
        if (!url.equals(currentControllerURL)
            || (connectionRequestSinceControllerFailure >= RETRY_CONTROLLER_AFTER_FAILURE)
            || ((controllerConfig != null) && (controllerConfig.size() == 0)))
        { // Too bad, all caches missed
          ControllerInfo[] controllerConfigArray = (ControllerInfo[]) controllerCache
              .get(url);
          if (controllerConfigArray == null) // Not in the cache
          {
            parseURL(url);
            controllerConfigArray = (ControllerInfo[]) controllerCache.get(url);
          }
          controllerConfig = new ArrayList();
          controllerConfigArraySize = controllerConfigArray.length;
          for (int i = 0; i < controllerConfigArraySize; i++)
            controllerConfig.add(controllerConfigArray[i]);

          currentControllerURL = url;
          currentDatabase = (String) dbNameCache.get(url);
          if (currentDatabase == null)
            throw new SQLException("Database name cache failure");

          // Give all controllers a chance
          retry = controllerConfig.size();
          connectionRequestSinceControllerFailure = 0;
        }
      }

      int size = controllerConfig.size();
      if (size < controllerConfigArraySize)
        connectionRequestSinceControllerFailure++;

      // Pick one controller randomly among the controllers that have not been
      // tried yet.
      picked = random.nextInt(size);
      currentControllerConfig = (ControllerInfo) controllerConfig.get(picked);

      boolean sentVdbName = false;
      boolean sentUserInfo = false;
      try
      {
        // Connect to the controller
        Socket socket = null;
        if (ssl == null)
        {
          // no ssl - we use ordinary socket
          socket = new Socket(currentControllerConfig.getHostname(),
              currentControllerConfig.getPort());
        }
        else
        {
          SocketFactory sslFact = SocketFactoryFactory.createFactory(ssl);
          socket = sslFact.createSocket(currentControllerConfig.getHostname(),
              currentControllerConfig.getPort());
        }

        // Disable Nagle algorithm else small messages are not sent
        // (at least under Linux) even if we flush the output stream.
        socket.setTcpNoDelay(true);

        CJDBCOutputStream out = new CJDBCOutputStream(socket);
        // Send protocol version and database name
        out.writeInt(Commands.ProtocolVersion);
        out.writeUTF(currentDatabase);
        out.flush();
        sentVdbName = true;

        // Send user information
        out.writeUTF(user);
        out.writeUTF(password);
        out.flush();
        sentUserInfo = true;

        CJDBCInputStream in;
        boolean needSkeleton;
        AbstractBlobFilter filter = null;
        try
        {
          // Create input stream only here else it will block
          in = new CJDBCInputStream(socket);

          Object response = in.readObject();
          if (response instanceof Boolean)
          {
            needSkeleton = ((Boolean) response).booleanValue();
            String sfilter = in.readUTF();
            filter = AbstractBlobFilter.getBlobFilterInstance(sfilter);
          }
          else if (response instanceof SQLException)
            throw (SQLException) response;
          else
            throw new SQLException("Error during connection (received "
                + response + ")");
        }
        catch (IOException e)
        {
          currentControllerURL = null;
          throw new SQLException("Authentication failed");
        }
        return setParametersOnConnection(info, new Connection(this, socket, in,
            out, url, user, password, needSkeleton, filter));
      }
      catch (Exception re)
      {
        controllerConfig.remove(picked);
        retry--;
        if (retry == 0)
        {
          if (!sentVdbName)
            throw new SQLException("Unable to connect to controller on "
                + currentControllerConfig.getHostname() + ":"
                + currentControllerConfig.getPort() + " (" + re + ")");
          else if (!sentUserInfo)
            throw new SQLException(
                "Unable to connect to the virtual database (virtual database name is probably not correct)");
          else
            throw new SQLException(
                "Unable to connect to the virtual database (" + re + ")");
        }
        else
        { // Reset if no more controllers in the list
          if (controllerConfig.isEmpty())
            currentControllerURL = null;
        }
      }
    }
    throw new SQLException(
        "Unable to connect to the virtual database - Unexpected error.");
  }

  /**
   * Tests if the URL is understood by the driver. Calls the
   * <code>parseURL()</code> method.
   * 
   * @param url the JDBC URL.
   * @return <code>true</code> if the URL is correct, otherwise an exception
   *         with extensive error message is thrown.
   * @exception SQLException if the URL is incorrect an explicit error message
   *              is given.
   */
  public synchronized boolean acceptsURL(String url) throws SQLException
  {
    try
    {
      parseURL(url);
      return true;
    }
    catch (SQLException e)
    {
      return false;
    }
  }

  /**
   * Checks for URL correctness and adds controllers list and database name to
   * the cache.
   * 
   * @param url the URL of the C-JDBC controller to which to connect.
   * @exception SQLException if an error occurs.
   */
  synchronized Hashtable parseURL(String url) throws SQLException
  {
    // Find the hostname and check for URL correctness
    if (url == null)
    {
      throw new IllegalArgumentException(
          "Illegal null URL in parseURL(String) method");
    }

    if (!url.toLowerCase().startsWith(CJDBC_URL_HEADER))
      throw new SQLException("Malformed header from URL '" + url
          + "' (expected '" + CJDBC_URL_HEADER + "')");
    else
    {
      // Initialize return
      Hashtable result = new Hashtable();

      // Get the controllers list
      int nextSlash = url.indexOf('/', CJDBC_URL_HEADER_LENGTH);
      if (nextSlash == -1)
        // Missing '/' between hostname and database name.
        throw new SQLException("Malformed URL '" + url + "' (expected '"
            + CJDBC_URL_HEADER + "<hostname>/<database>')");

      // Found end of database name
      int questionMark = url.indexOf('?', nextSlash);
      questionMark = (questionMark == -1)
          ? url.indexOf(';', nextSlash)
          : questionMark;

      String controllerURLs = url.substring(CJDBC_URL_HEADER_LENGTH, nextSlash);
      // Check the validity of each controller in the list
      StringTokenizer controllers = new StringTokenizer(controllerURLs, ",",
          true);
      int tokenNumber = controllers.countTokens();
      ArrayList list = new ArrayList();

      int i = 0;
      String s;
      boolean lastTokenWasComma = false;
      while (controllers.hasMoreTokens())
      {
        s = controllers.nextToken().trim();
        if (s.equals(","))
        {
          if (lastTokenWasComma || (i == 0) || (i == tokenNumber - 1))
            // ',' cannot be the first or the last token
            // another ',' cannot follow a ','
            throw new SQLException("Syntax error in controller list '"
                + controllerURLs + "' from URL '" + url + "'");
          else
          {
            lastTokenWasComma = true;
            continue;
          }
        }
        lastTokenWasComma = false;
        list.add(parseController(s));
        i++;
      }

      ControllerInfo[] controllerList = new ControllerInfo[i];
      for (int j = 0; j < i; j++)
      {
        controllerList[j] = (ControllerInfo) (list.get(j));
      }
      // Add controller list to the result
      result.put(CONTROLLER_PROPERTY, controllerList);

      // Check database name validity
      String databaseName = (questionMark == -1) ? url.substring(nextSlash + 1,
          url.length()) : url.substring(nextSlash + 1, questionMark);
      Character c = validDatabaseName(databaseName);
      if (c != null)
        throw new SQLException(
            "Unable to validate database name (unacceptable character '" + c
                + "' in database '" + databaseName + "' from URL '" + url
                + "')");

      // Add database name to result
      result.put(DATABASE_PROPERTY, databaseName);

      // Finally, add the controllers list and database name to the caches
      controllerCache.put(url, controllerList);
      dbNameCache.put(url, databaseName);

      // Get the parameters from the url
      Hashtable params = parseUrlParams(url);
      if (params != null)
        result.put(PARAMETER_PROPERTY, params);
      return result;
    }
  }

  /**
   * Set the different parameters on the connection. Possible values are:
   * <code>BOOLEAN_TRUE_PROPERTY</code><br>
   * <code>BOOLEAN_FALSE_PROPERTY</code><br>
   * <code>ESCAPE_BACKSLASH_PROPERTY</code><br>
   * <code>ESCAPE_SINGLE_QUOTE_PROPERTY</code><br>
   * 
   * @param props the properties used to connect to the controller. These
   *          properties should be collected from both the url and the
   *          <code>Properties</code> object passed in to the connect method
   * @param connection the connection to set the parameters on. Previous
   *          parameters will be overriden
   * @return the same connection with the parameters set
   */
  private java.sql.Connection setParametersOnConnection(Properties props,
      org.objectweb.cjdbc.driver.Connection connection)
  {
    String booleanTrue = props.getProperty(BOOLEAN_TRUE_PROPERTY);
    if (booleanTrue != null)
      connection.setPreparedStatementBooleanTrue(booleanTrue);
    String booleanFalse = props.getProperty(BOOLEAN_FALSE_PROPERTY);
    if (booleanFalse != null)
      connection.setPreparedStatementBooleanFalse(booleanFalse);
    String escapeBaskslash = props.getProperty(ESCAPE_BACKSLASH_PROPERTY);
    if (escapeBaskslash != null)
      connection
          .setEscapeBackslash(new Boolean(escapeBaskslash).booleanValue());
    String escapeQuote = props.getProperty(ESCAPE_SINGLE_QUOTE_PROPERTY);
    if (escapeQuote != null)
      connection.setEscapeSingleQuote(new Boolean(escapeQuote).booleanValue());

    String escapeChar = props.getProperty(ESCAPE_CHARACTER_PROPERTY);
    if (escapeChar != null)
      connection.setEscapeChar(escapeChar);

    String driverProcessed = props.getProperty(DRIVER_PROCESSED_PROPERTY);
    if (driverProcessed != null)
      connection.setDriverProcessed(Boolean.valueOf(driverProcessed)
          .booleanValue());

    return connection;
  }

  /**
   * Returns the controllerConfig value containing the list of available
   * controllers.
   * 
   * @return Returns the controllerConfig.
   */
  protected ArrayList getControllerConfig()
  {
    return controllerConfig;
  }

  /**
   * Feed in a set of properties and get the url as a <code>String</code>
   * 
   * @param props as defined statically at the top of the class
   * @return <code>String</code> describing the url
   */
  protected String getUrlFromProperties(Hashtable props)
  {
    StringBuffer sb = new StringBuffer();
    sb.append(CJDBC_URL_HEADER);
    ControllerInfo[] controllerList = (ControllerInfo[]) props
        .get(CONTROLLER_PROPERTY);
    for (int i = 0; i < controllerList.length; i++)
    {
      if (i == 0)
        sb.append(controllerList[i].toString());
      else
        sb.append("," + controllerList[i].toString());
    }
    sb.append("/" + props.get(DATABASE_PROPERTY));
    Hashtable params = (Hashtable) props.get(PARAMETER_PROPERTY);
    if (params != null)
    {
      Enumeration paramsKeys = params.keys();
      String element = null;
      while (paramsKeys.hasMoreElements())
      {
        if (element == null)
          sb.append("?");
        else
          sb.append("&");
        element = (String) paramsKeys.nextElement();
        sb.append(element + "=" + params.get(paramsKeys));
      }
    }
    return sb.toString();
  }

  private Hashtable parseUrlParams(String url) throws SQLException
  {
    Hashtable props;
    props = parseUrlParams(url, '?', "&", "=");
    if (props == null)
    {
      props = parseUrlParams(url, ';', ";", "=");
    }
    return props;
  }

  private Hashtable parseUrlParams(String url, char mark, String link,
      String equal) throws SQLException
  {
    int questionMark = url.indexOf(mark, url.lastIndexOf('/'));
    if (questionMark == -1)
      return null;
    else
    {
      Hashtable props = new Hashtable();
      String parameters = url.substring(questionMark + 1);
      StringTokenizer st1 = new StringTokenizer(parameters, link);
      while (st1.hasMoreTokens())
      {
        String param = st1.nextToken();
        StringTokenizer st2 = new StringTokenizer(param, equal);
        if (st2.hasMoreTokens())
        {
          try
          {
            String paramName = st2.nextToken();
            String paramValue = (st2.hasMoreTokens()) ? st2.nextToken() : "";
            props.put(paramName, paramValue);
          }
          catch (Exception e)
          {
            throw new SQLException("Invalid parameter in URL");
          }
        }
      }
      return props;
    }
  }

  /**
   * 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.
   * 
   * @param controller information regarding a controller.
   * @return a <code>ControllerInfo</code> object
   * @exception SQLException if an error occurs.
   */
  private ControllerInfo parseController(String controller) throws SQLException
  {
    ControllerInfo controllerInfo = new ControllerInfo();

    // Check controller syntax
    StringTokenizer controllerURL = new StringTokenizer(controller, ":", true);

    // Get hostname
    controllerInfo.setHostname(controllerURL.nextToken());
    Character c = validHostname(controllerInfo.getHostname());
    if (c != null)
      throw new SQLException(
          "Unable to validate hostname (unacceptable character '" + c
              + "' in hostname '" + controllerInfo.getHostname()
              + "' from the URL part '" + controller + "')");

    if (!controllerURL.hasMoreTokens())
      controllerInfo.setPort(ControllerConstants.DEFAULT_PORT);
    else
    {
      controllerURL.nextToken(); // should be ':'
      if (!controllerURL.hasMoreTokens())
        controllerInfo.setPort(ControllerConstants.DEFAULT_PORT);
      else
      { // Get the port number
        String port = controllerURL.nextToken();
        if (controllerURL.hasMoreTokens())
          throw new SQLException(
              "Invalid controller definition with more than one semicolon in URL part '"
                  + controller + "'");

        // Check the port number validity
        try
        {
          controllerInfo.setPort(Integer.parseInt(port));
        }
        catch (NumberFormatException ne)
        {
          throw new SQLException(
              "Unable to validate port number (unacceptable port number '"
                  + port + "' in this URL part '" + controller + "')");
        }
      }
    }
    return controllerInfo;
  }

  /**
   * 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.
   * <p>
   * The only properties supported by C-JDBC are:
   * <ul>
   * <li>HOST_PROPERTY</li>
   * <li>PORT_PROPERTY</li>
   * <li>DATABASE_PROPERTY</li>
   * <li>USER_PROPERTY</li>
   * <li>PASSWORD_PROPERTY</li>
   * <li>ESCAPE_CHARACTER_PROPERTY</li>
   * <li>ESCAPE_BACKSLASH_PROPERTY</li>
   * <li>BOOLEAN_FALSE_PROPERTY</li>
   * <li>BOOLEAN_TRUE_PROPERTY</li>
   * <li>DRIVER_PROCESSED_PROPERTY</li>
   * 
   * @param url the URL of the database to connect to
   * @param info a proposed list of tag/value pairs that will be sent on connect
   *          open.
   * @return an array of <code>DriverPropertyInfo</code> objects describing
   *         possible properties. This array may be an empty array if no
   *         properties are required.
   * @exception SQLException if a database-access error occurs.
   * @see java.sql.Driver#getPropertyInfo
   */
  public DriverPropertyInfo[] getPropertyInfo(String url, Properties info)
      throws SQLException
  {
    DriverPropertyInfo hostProp = new DriverPropertyInfo(HOST_PROPERTY, info
        .getProperty(HOST_PROPERTY));
    hostProp.required = true;
    hostProp.description = HOST_PROPERTY_DESCRIPTION;

    DriverPropertyInfo portProp = new DriverPropertyInfo(PORT_PROPERTY, info
        .getProperty(PORT_PROPERTY, Integer
            .toString(ControllerConstants.DEFAULT_PORT)));
    portProp.required = false;
    portProp.description = PORT_PROPERTY_DESCRIPTION;

    DriverPropertyInfo databaseProp = new DriverPropertyInfo(DATABASE_PROPERTY,
        info.getProperty(DATABASE_PROPERTY));
    databaseProp.required = true;
    databaseProp.description = DATABASE_PROPERTY_DESCRIPTION;

    DriverPropertyInfo userProp = new DriverPropertyInfo(USER_PROPERTY, info
        .getProperty(USER_PROPERTY));
    userProp.required = true;
    userProp.description = USER_PROPERTY_DESCRIPTION;

    DriverPropertyInfo passwordProp = new DriverPropertyInfo(PASSWORD_PROPERTY,
        info.getProperty(PASSWORD_PROPERTY));
    passwordProp.required = true;
    passwordProp.description = PASSWORD_PROPERTY_DESCRIPTION;

    DriverPropertyInfo escapeCharProp = new DriverPropertyInfo(
        ESCAPE_CHARACTER_PROPERTY, info.getProperty(ESCAPE_CHARACTER_PROPERTY));
    escapeCharProp.required = false;
    escapeCharProp.description = ESCAPE_CHARACTER_PROPERTY_DESCRIPTION;

    DriverPropertyInfo escapeBackProp = new DriverPropertyInfo(
        ESCAPE_BACKSLASH_PROPERTY, info.getProperty(ESCAPE_BACKSLASH_PROPERTY));
    escapeBackProp.required = false;
    escapeBackProp.description = ESCAPE_BACKSLASH_PROPERTY_DESCRIPTION;

    DriverPropertyInfo escapeSingleProp = new DriverPropertyInfo(
        ESCAPE_SINGLE_QUOTE_PROPERTY, info
            .getProperty(ESCAPE_SINGLE_QUOTE_PROPERTY));
    escapeSingleProp.required = false;
    escapeSingleProp.description = ESCAPE_SINGLE_QUOTE_PROPERTY_DESCRIPTION;

    DriverPropertyInfo booleanFalseProp = new DriverPropertyInfo(
        BOOLEAN_FALSE_PROPERTY, info.getProperty(BOOLEAN_FALSE_PROPERTY));
    booleanFalseProp.required = false;
    booleanFalseProp.description = BOOLEAN_FALSE_PROPERTY_DESCRIPTION;

    DriverPropertyInfo booleanTrueProp = new DriverPropertyInfo(
        BOOLEAN_TRUE_PROPERTY, info.getProperty(BOOLEAN_TRUE_PROPERTY));
    booleanTrueProp.required = false;
    booleanTrueProp.description = BOOLEAN_TRUE_PROPERTY_DESCRIPTION;

    DriverPropertyInfo parseQueryProp = new DriverPropertyInfo(
        DRIVER_PROCESSED_PROPERTY, info.getProperty(DRIVER_PROCESSED_PROPERTY));
    escapeSingleProp.required = false;
    escapeSingleProp.description = DRIVER_PROCESSED_PROPERTY_DESCRIPTION;

    return new DriverPropertyInfo[]{hostProp, portProp, databaseProp, userProp,
        passwordProp, escapeCharProp, escapeBackProp, escapeSingleProp,
        booleanFalseProp, booleanTrueProp, parseQueryProp};
  }

  /**
   * Gets the river's major version number
   * 
   * @return the driver's major version number
   */
  public int getMajorVersion()
  {
    return MAJOR_VERSION;
  }

  /**
   * Gets the driver's minor version number
   * 
   * @return the driver's minor version number
   */
  public int getMinorVersion()
  {
    return MINOR_VERSION;
  }

  /**
   * Reports whether the driver is a genuine JDBC compliant driver. A driver may
   * only report <code>true</code> here if it passes the JDBC compliance
   * tests, otherwise it is required to return <code>false</code>. 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 <code>false</code>.
   * 
   * @return always <code>false</code>
   */
  public boolean jdbcCompliant()
  {
    return false;
  }

  /**
   * Checks that the given name contains acceptable characters for a hostname
   * name ([0-9][A-Z][a-z][.]).
   * 
   * @param hostname name to check (caller must check that it is not
   *          <code>null</code>).
   * @return <code>null</code> if the hostname is acceptable, else the
   *         character that causes the fault.
   */
  private static Character validHostname(String hostname)
  {
    char[] name = hostname.toCharArray();
    int size = hostname.length();
    char c;
    //boolean lastCharWasPoint = false; // used to avoid '..' in hostname
    char lastChar = ' ';

    for (int i = 0; i < size; i++)
    {
      c = name[i];

      if (c == '.' || c == '-')
      {
        if (lastChar == '.' || lastChar == '-' || (i == size - 1) || (i == 0))
        {
          // . or - cannot be the first or the last char of hostname
          // hostname cannot contain '..' or '.-' or '-.' or '--'
          return new Character(c);
        }
      }
      else
      {
        if (((c < '0') || (c > 'z') || ((c > '9') && (c < 'A')) || ((c > 'Z') && (c < 'a'))))
        {
          return new Character(c);
        }
      }
      lastChar = c;
    }
    return null;
  }

  /**
   * Checks that the given name contains acceptable characters for a database
   * name ([0-9][A-Z][a-z]).
   * 
   * @param databaseName name to check (caller must check that it is not
   *          <code>null</code>).
   * @return <code>null</code> if the name is acceptable, else the character
   *         that causes the fault.
   */
  private static Character validDatabaseName(String databaseName)
  {
    char[] name = databaseName.toCharArray();
    int size = databaseName.length();
    char c;

    for (int i = 0; i < size; i++)
    {
      c = name[i];
      if ((c < '0') || (c > 'z') || ((c > '9') && (c < 'A'))
          || ((c > 'Z') && (c < 'a')))
        return new Character(c);
    }
    return null;
  }

  /**
   * Controller related information, namely the host name and the port on which
   * the controller is running.
   * 
   * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
   * @version 1.0
   */
  public class ControllerInfo
  {
    String hostname;
    int    port;

    /**
     * Creates a ControllerInfo object
     */
    public ControllerInfo()
    {
    }

    /**
     * Get the hostname where the controller is running
     * 
     * @return controller hostname
     */
    public String getHostname()
    {
      return hostname;
    }

    /**
     * Get the port number on which the controller is listening.
     * 
     * @return port number.
     */
    public int getPort()
    {
      return port;
    }

    /**
     * Set the controller hostname.
     * 
     * @param string hostname to set
     */
    public void setHostname(String string)
    {
      hostname = string;
    }

    /**
     * Set the port number.
     * 
     * @param port port number
     */
    public void setPort(int port)
    {
      this.port = port;
    }

    /**
     * @see java.lang.Object#toString()
     */
    public String toString()
    {
      return hostname + ":" + port;
    }
  } // ControllerInfo class

}

---