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.
24 * <p>
25 * 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 * <p>
31 * A driver needs to be registered with a {@link DriverManager}. It is
32 * registered and instantiated by calling {@code Class.forName("DriverURL")}
33 * with the URL string as argument.
34 *
35 * @see DriverManager
36 */
37public interface Driver {
38
39    /**
40     * Returns whether the driver thinks that it can open a connection to the
41     * given URL.
42     *
43     * @param url
44     *            the URL to connect to.
45     * @return {@code true} if the driver thinks that is can open a connection
46     *         to the supplied URL, {@code false} otherwise. Typically, the
47     *         driver will respond {@code true} if it thinks that it can handle
48     *         the subprotocol specified by the driver.
49     * @throws SQLException
50     *          if a database error occurs.
51     */
52    public boolean acceptsURL(String url) throws SQLException;
53
54    /**
55     * Attempts to make a database connection to a data source specified by a
56     * supplied URL.
57     *
58     * @param url
59     *            the URL to connect.
60     * @param info
61     *            some properties that should be used in establishing the
62     *            connection. The properties consist of name/value pairs of
63     *            strings. Normally, a connection to a database requires at
64     *            least two properties - for {@code "user"} and {@code
65     *            "password"} in order to pass authentication to the database.
66     * @return the connection to the database.
67     * @throws SQLException
68     *             if a database error occurs.
69     */
70    public Connection connect(String url, Properties info) throws SQLException;
71
72    /**
73     * Gets the driver's major version number.
74     *
75     * @return the major version number of the driver - typically starts at 1.
76     */
77    public int getMajorVersion();
78
79    /**
80     * Gets the driver's minor version number.
81     *
82     * @return the minor version number of the driver - typically starts at 0.
83     */
84    public int getMinorVersion();
85
86    /**
87     * Gets information about possible properties for this driver.
88     * <p>
89     * This method is intended to provide a listing of possible properties that
90     * the client of the driver must supply in order to establish a connection
91     * to a database. Note that the returned array of properties may change
92     * depending on the supplied list of property values.
93     *
94     * @param url
95     *            the URL of the database. An application may call this method
96     *            iteratively as the property list is built up - for example,
97     *            when displaying a dialog to an end-user as part of the
98     *            database login process.
99     * @param info
100     *            a set of tag/value pairs giving data that a user may be
101     *            prompted to provide in order to connect to the database.
102     * @return an array of {@code DriverPropertyInfo} records which provide
103     *         details on which additional properties are required (in addition
104     *         to those supplied in the {@code info} parameter) in order to
105     *         connect to the database.
106     * @throws SQLException
107     *             if a database error occurs.
108     */
109    public DriverPropertyInfo[] getPropertyInfo(String url, Properties info)
110            throws SQLException;
111
112    /**
113     * Reports whether this driver is a genuine JDBC CompliantTM driver. The
114     * driver may only return {@code true} if it passes all the JDBC compliance
115     * tests.
116     * <p>
117     * A driver may not be fully compliant if the underlying database has
118     * limited functionality.
119     *
120     * @return {@code true} if the driver is fully JDBC compliant, {@code false}
121     *         otherwise.
122     */
123    public boolean jdbcCompliant();
124
125}
126