001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.sql;
019:
020: import java.util.Properties;
021:
022: /**
023: * An Interface to a JDBC Driver.
024: * <p>
025: * The JDBC Driver uses URLs to specify the location of specific data. URL
026: * format typically takes the form "xxxx:yyyy:SpecificData", where "xxxx:yyyy"
027: * is termed the subprotocol and is normally the same for all uses of a
028: * particular driver. "SpecificData" is a string which identifies the particular
029: * data source that the driver should use.
030: *
031: */
032: public interface Driver {
033:
034: /**
035: * Returns whether the driver thinks that it can open a connection to the
036: * given URL.
037: *
038: * @param url
039: * the URL to connect to.
040: * @return true if the driver thinks that is can open a connection to the
041: * supplied URL, false otherwise. Typically, the driver will respond
042: * true if it thinks that it can handle the subprotocol specified by
043: * the driver.
044: * @throws SQLException
045: */
046: public boolean acceptsURL(String url) throws SQLException;
047:
048: /**
049: * Attempts to make a database connection to a datasource specified by a
050: * supplied URL.
051: *
052: * @param url
053: * the url to connect.
054: * @param info
055: * some properties that should be used in establishing the
056: * connection. The properties consist of name/value pairs of
057: * Strings. Normally, a connection to a database requires at
058: * least two properties - for "user" and "password" in order to
059: * pass authentication to the database.
060: * @return a Connection object representing the connection to the database.
061: * @throws SQLException
062: * if a database error occurs
063: */
064: public Connection connect(String url, Properties info)
065: throws SQLException;
066:
067: /**
068: * Gets the driver's major version number.
069: *
070: * @return the major version number of the Driver - typically starts at 1.
071: */
072: public int getMajorVersion();
073:
074: /**
075: * Gets the driver's minor version number.
076: *
077: * @return the minor version number of the Driver - typically starts at 0.
078: */
079: public int getMinorVersion();
080:
081: /**
082: * Gets information about possible properties for this driver.
083: * <p>
084: * This method is intended to provide a listing of possible properties that
085: * the user of the driver may need to supply in order to correct connect to
086: * a database. Note that the returned array of Properties may change
087: * depending on the supplied list of property values.
088: *
089: * @param url
090: * the url of the database. A using program may call this method
091: * iteratively as the property list is built up - for example,
092: * when displaying a dialog to an end-user as part of the
093: * database login process.
094: * @param info
095: * @return an array of DriverPropertyInfo records which provide detail on
096: * each property that the driver will accept.
097: * @throws SQLException
098: */
099: public DriverPropertyInfo[] getPropertyInfo(String url,
100: Properties info) throws SQLException;
101:
102: /**
103: * Reports whether this driver is a genuine JDBC CompliantTM driver. The
104: * driver may only return true from this method if it passes all the JDBC
105: * Compliance tests.
106: * <p>
107: * A driver may not be fully compliant if the underlying database has
108: * limited functionality.
109: *
110: * @return true if the driver is fully JDBC compliant, false otherwise.
111: */
112: public boolean jdbcCompliant();
113:
114: }
|