libjava/java/sql/Driver.java

   1 /* Driver.java -- A JDBC driver
   2    Copyright (C) 1999, 2000 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 As a special exception, if you link this library with other files to
  22 produce an executable, this library does not by itself cause the
  23 resulting executable to be covered by the GNU General Public License.
  24 This exception does not however invalidate any other reasons why the
  25 executable file might be covered by the GNU General Public License. */
  26
  27
  28 package java.sql;
  29
  30 import java.util.Properties;
  31
  32 /**
  33   * This interface specifies a mechanism for accessing a JDBC database
  34   * driver.  When the class implementing this method is loaded, it should
  35   * register an instance of itself with the <code>DriverManager</code> in
  36   * a static initializer.
  37   * <p>
  38   * Because the <code>DriverManager</code> might attempt to use several
  39   * drivers to find one that can connect to the requested database,
  40   * this driver should not cause large numbers of classes and code to
  41   * be loaded.  If another driver is the one that ends up performing the
  42   * request, any loading done by this driver would be wasted.
  43   *
  44   * @author Aaron M. Renn (arenn@urbanophile.com)
  45   */
  46 public interface Driver
  47 {
  48
  49 /**
  50   * This method returns the major version number of the driver.
  51   *
  52   * @return The major version number of the driver.
  53   */
  54 public abstract int
  55 getMajorVersion();
  56
  57 /*************************************************************************/
  58
  59 /**
  60   * This method returns the minor version number of the driver.
  61   *
  62   * @return The minor version number of the driver.
  63   */
  64 public abstract int
  65 getMinorVersion();
  66
  67 /*************************************************************************/
  68
  69 /**
  70   * This method tests whether or not the driver is JDBC compliant.  This
  71   * method should only return <code>true</code> if the driver has been
  72   * certified as JDBC compliant.
  73   *
  74   * @return <code>true</code> if the driver has been certified JDBC compliant,
  75   * <code>false</code> otherwise.
  76   */
  77 public abstract boolean
  78 jdbcCompliant();
  79
  80 /*************************************************************************/
  81
  82 /**
  83   * This method returns an array of possible properties that could be
  84   * used to connect to the specified database.
  85   *
  86   * @param url The URL string of the database to connect to.
  87   * @param properties The list of properties the caller is planning to use
  88   * to connect to the database.
  89   *
  90   * @return A list of possible additional properties for a connection to this
  91   * database.  This list may be empty.
  92   *
  93   * @exception SQLException If an error occurs.
  94   */
  95 public abstract DriverPropertyInfo[]
  96 getPropertyInfo(String url, Properties properties) throws SQLException;
  97
  98 /*************************************************************************/
  99
 100 /**
 101   * This method tests whether or not the driver believes it can connect to
 102   * the specified database.  The driver should only test whether it
 103   * understands and accepts the URL. It should not necessarily attempt to
 104   * probe the database for a connection.
 105   *
 106   * @param The database URL string.
 107   *
 108   * @return <code>true</code> if the drivers can connect to the database,
 109   * <code>false</code> otherwise.
 110   *
 111   * @exception SQLException If an error occurs.
 112   */
 113 public abstract boolean
 114 acceptsURL(String url) throws SQLException;
 115
 116 /*************************************************************************/
 117
 118 /**
 119   * This method connects to the specified database using the connection
 120   * properties supplied.  If the driver does not understand the database
 121   * URL, it should return <code>null</code> instead of throwing an
 122   * exception since the <code>DriverManager</code> will probe a driver
 123   * in this manner.
 124   *
 125   * @param url The URL string for this connection.
 126   * @param properties The list of database connection properties.
 127   *
 128   * @return A <code>Connection</code> object for the newly established
 129   * connection, or <code>null</code> if the URL is not understood.
 130   *
 131   * @exception SQLException If an error occurs.
 132   */
 133 public abstract Connection
 134 connect(String url, Properties properties) throws SQLException;
 135
 136 } // interface Driver
 137