1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.sql;
19
20import java.util.Properties;
21
22/**
23 * An interface to a JDBC driver. Instances are returned by {@link DriverManager}.
24 *
25 * <p>The JDBC driver uses URLs to specify the location of specific data. URL
26 * format typically takes the form " {@code xxxx:yyyy:SpecificData}", where "
27 * {@code xxxx:yyyy}" is referred to as the <i>subprotocol</i> and is normally
28 * the same for all of a particular driver. " {@code SpecificData}" is a string
29 * which identifies the particular data source that the driver should use.
30 *
31 * @see DriverManager
32 */
33public interface Driver {
34
35    /**
36     * Returns whether the driver thinks that it can open a connection to the
37     * given URL.
38     *
39     * @param url
40     *            the URL to connect to.
41     * @return {@code true} if the driver thinks that is can open a connection
42     *         to the supplied URL, {@code false} otherwise. Typically, the
43     *         driver will respond {@code true} if it thinks that it can handle
44     *         the subprotocol specified by the driver.
45     * @throws SQLException
46     *          if a database error occurs.
47     */
48    public boolean acceptsURL(String url) throws SQLException;
49
50    /**
51     * Attempts to make a database connection to a data source specified by a
52     * supplied URL.
53     *
54     * @param url
55     *            the URL to connect.
56     * @param info
57     *            some properties that should be used in establishing the
58     *            connection. The properties consist of name/value pairs of
59     *            strings. Normally, a connection to a database requires at
60     *            least two properties - for {@code "user"} and {@code
61     *            "password"} in order to pass authentication to the database.
62     * @return the connection to the database.
63     * @throws SQLException
64     *             if a database error occurs.
65     */
66    public Connection connect(String url, Properties info) throws SQLException;
67
68    /**
69     * Gets the driver's major version number.
70     *
71     * @return the major version number of the driver - typically starts at 1.
72     */
73    public int getMajorVersion();
74
75    /**
76     * Gets the driver's minor version number.
77     *
78     * @return the minor version number of the driver - typically starts at 0.
79     */
80    public int getMinorVersion();
81
82    /**
83     * Gets information about possible properties for this driver.
84     * <p>
85     * This method is intended to provide a listing of possible properties that
86     * the client of the driver must supply in order to establish a connection
87     * to a database. Note that the returned array of properties may change
88     * depending on the supplied list of property values.
89     *
90     * @param url
91     *            the URL of the database. An application may call this method
92     *            iteratively as the property list is built up - for example,
93     *            when displaying a dialog to an end-user as part of the
94     *            database login process.
95     * @param info
96     *            a set of tag/value pairs giving data that a user may be
97     *            prompted to provide in order to connect to the database.
98     * @return an array of {@code DriverPropertyInfo} records which provide
99     *         details on which additional properties are required (in addition
100     *         to those supplied in the {@code info} parameter) in order to
101     *         connect to the database.
102     * @throws SQLException
103     *             if a database error occurs.
104     */
105    public DriverPropertyInfo[] getPropertyInfo(String url, Properties info)
106            throws SQLException;
107
108    /**
109     * Reports whether this driver is a genuine JDBC CompliantTM driver. The
110     * driver may only return {@code true} if it passes all the JDBC compliance
111     * tests.
112     * <p>
113     * A driver may not be fully compliant if the underlying database has
114     * limited functionality.
115     *
116     * @return {@code true} if the driver is fully JDBC compliant, {@code false}
117     *         otherwise.
118     */
119    public boolean jdbcCompliant();
120
121}
122