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