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 18 package java.sql; 19 20 import 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 */ 33 public 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
