KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > sql > Driver


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