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 javax.sql; 19 20 import java.sql.Connection; 21 import java.sql.SQLException; 22 import java.sql.Wrapper; 23 24 /** 25 * An interface for the creation of {@code Connection} objects which represent a 26 * connection to a database. This interface is an alternative to the {@code 27 * java.sql.DriverManager}. 28 * <p> 29 * A class which implements the {@code DataSource} interface is typically 30 * registered with a JNDI naming service directory and is retrieved from there 31 * by name. 32 * <p> 33 * The {@code DataSource} interface is typically implemented by the writer of a 34 * JDBC driver. There are three variants of the {@code DataSource} interface, 35 * which produce connections with different characteristics: 36 * <ol> 37 * <li><i>Standard {@code DataSource}</i>: produces standard {@code Connection} 38 * objects with no special features.</li> 39 * <li><i>Connection Pool {@code DataSource}</i>: produces {@code 40 * PooledConnection} objects which require a connection pool manager as an 41 * intermediary component.</li> 42 * <li><i>Distributed transaction {@code DataSource} ("XADataSource")</i>: 43 * produces {@code XAConnection} objects which can be used to handle distributed 44 * transactions which typically require an intermediary transaction manager 45 * component. {@code XAConnection} objects also provide connection pooling 46 * capabilities as well as distributed transaction capabilities.</li> 47 * </ol> 48 * <p> 49 * Note that a JDBC driver which is accessed via the {@code DataSource} 50 * interface is loaded via a JNDI lookup process. A driver loaded in this way 51 * does not register itself with the {@code DriverManager}. 52 */ 53 public interface DataSource extends CommonDataSource, Wrapper { 54 55 /** 56 * Creates a connection to the database represented by this {@code 57 * DataSource}. 58 * 59 * @return a {@code Connection} object which is a connection to the 60 * database. 61 * @throws SQLException 62 * if there is a problem accessing the database. 63 */ 64 public Connection getConnection() throws SQLException; 65 66 /** 67 * Creates a connection to the database represented by this {@code 68 * DataSource}, using the supplied user name and password. 69 * 70 * @param theUsername 71 * the a user name for the database login. 72 * @param thePassword 73 * the password associated with the user identified by {@code 74 * theUsername}. 75 * @return the {@code Connection} object which is the connection to the 76 * database. 77 * @throws SQLException 78 * if there is a problem accessing the database. 79 */ 80 public Connection getConnection(String theUsername, String thePassword) 81 throws SQLException; 82 } 83
