home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / sql / Driver.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  5.3 KB  |  138 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Driver.java    1.15 98/09/23
  3.  *
  4.  * Copyright 1996-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.sql;
  16.  
  17. /**
  18.  * The interface that every driver class must implement.
  19.  * <P>The Java SQL framework allows for multiple database drivers.
  20.  *
  21.  * <P>Each driver should supply a class that implements
  22.  * the Driver interface.
  23.  *
  24.  * <P>The DriverManager will try to load as many drivers as it can
  25.  * find and then for any given connection request, it will ask each
  26.  * driver in turn to try to connect to the target URL.
  27.  *
  28.  * <P>It is strongly recommended that each Driver class should be
  29.  * small and standalone so that the Driver class can be loaded and
  30.  * queried without bringing in vast quantities of supporting code.
  31.  *
  32.  * <P>When a Driver class is loaded, it should create an instance of
  33.  * itself and register it with the DriverManager. This means that a
  34.  * user can load and register a driver by calling
  35.  * <pre>
  36.  *   <code>Class.forName("foo.bah.Driver")</code>
  37.  * </pre>
  38.  *
  39.  * @see DriverManager
  40.  * @see Connection 
  41.  */
  42. public interface Driver {
  43.  
  44.     /**
  45.      * Attempts to make a database connection to the given URL.
  46.      * The driver should return "null" if it realizes it is the wrong kind
  47.      * of driver to connect to the given URL.  This will be common, as when
  48.      * the JDBC driver manager is asked to connect to a given URL it passes
  49.      * the URL to each loaded driver in turn.
  50.      *
  51.      * <P>The driver should raise a SQLException if it is the right 
  52.      * driver to connect to the given URL, but has trouble connecting to
  53.      * the database.
  54.      *
  55.      * <P>The java.util.Properties argument can be used to passed arbitrary
  56.      * string tag/value pairs as connection arguments.
  57.      * Normally at least "user" and "password" properties should be
  58.      * included in the Properties.
  59.      *
  60.      * @param url the URL of the database to which to connect
  61.      * @param info a list of arbitrary string tag/value pairs as
  62.      * connection arguments. Normally at least a "user" and
  63.      * "password" property should be included.
  64.      * @return a <code>Connection</code> object that represents a
  65.      *         connection to the URL
  66.      * @exception SQLException if a database access error occurs
  67.      */
  68.     Connection connect(String url, java.util.Properties info)
  69.         throws SQLException;
  70.  
  71.     /**
  72.      * Returns true if the driver thinks that it can open a connection
  73.      * to the given URL.  Typically drivers will return true if they
  74.      * understand the subprotocol specified in the URL and false if
  75.      * they don't.
  76.      *
  77.      * @param url the URL of the database
  78.      * @return true if this driver can connect to the given URL  
  79.      * @exception SQLException if a database access error occurs
  80.      */
  81.     boolean acceptsURL(String url) throws SQLException;
  82.  
  83.  
  84.     /**
  85.      * Gets information about the possible properties for this driver.
  86.      * <p>The getPropertyInfo method is intended to allow a generic GUI tool to 
  87.      * discover what properties it should prompt a human for in order to get 
  88.      * enough information to connect to a database.  Note that depending on
  89.      * the values the human has supplied so far, additional values may become
  90.      * necessary, so it may be necessary to iterate though several calls
  91.      * to getPropertyInfo.
  92.      *
  93.      * @param url the URL of the database to which to connect
  94.      * @param info a proposed list of tag/value pairs that will be sent on
  95.      *          connect open
  96.      * @return an array of DriverPropertyInfo objects describing possible
  97.      *          properties.  This array may be an empty array if no properties
  98.      *          are required.
  99.      * @exception SQLException if a database access error occurs
  100.      */
  101.     DriverPropertyInfo[] getPropertyInfo(String url, java.util.Properties info)
  102.              throws SQLException;
  103.  
  104.  
  105.     /**
  106.      * Gets the driver's major version number. Initially this should be 1.
  107.      * @return this driver's major version number
  108.      */
  109.     int getMajorVersion();
  110.  
  111.     /**
  112.      * Gets the driver's minor version number. Initially this should be 0.
  113.      * @return this driver's minor version number
  114.      */
  115.     int getMinorVersion();
  116.  
  117.  
  118.     /**
  119.      * Reports whether this driver is a genuine JDBC
  120.      * COMPLIANT<sup><font size=-2>TM</font></sup> driver.
  121.      * A driver may only report true here if it passes the JDBC compliance
  122.      * tests; otherwise it is required to return false.
  123.      *
  124.      * JDBC compliance requires full support for the JDBC API and full support
  125.      * for SQL 92 Entry Level.  It is expected that JDBC compliant drivers will
  126.      * be available for all the major commercial databases.
  127.      *
  128.      * This method is not intended to encourage the development of non-JDBC
  129.      * compliant drivers, but is a recognition of the fact that some vendors
  130.      * are interested in using the JDBC API and framework for lightweight
  131.      * databases that do not support full database functionality, or for
  132.      * special databases such as document information retrieval where a SQL
  133.      * implementation may not be feasible.
  134.      */
  135.     boolean jdbcCompliant();
  136. } 
  137.  
  138.