1 /* 2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sql; 27 28 import java.sql.Connection; 29 import java.sql.ConnectionBuilder; 30 import java.sql.SQLException; 31 import java.sql.SQLFeatureNotSupportedException; 32 import java.sql.ShardingKeyBuilder; 33 import java.sql.Wrapper; 34 35 /** 36 * <p>A factory for connections to the physical data source that this 37 * {@code DataSource} object represents. An alternative to the 38 * {@code DriverManager} facility, a {@code DataSource} object 39 * is the preferred means of getting a connection. An object that implements 40 * the {@code DataSource} interface will typically be 41 * registered with a naming service based on the 42 * Java™ Naming and Directory (JNDI) API. 43 * <P> 44 * The {@code DataSource} interface is implemented by a driver vendor. 45 * There are three types of implementations: 46 * <OL> 47 * <LI>Basic implementation -- produces a standard {@code Connection} 48 * object 49 * <LI>Connection pooling implementation -- produces a {@code Connection} 50 * object that will automatically participate in connection pooling. This 51 * implementation works with a middle-tier connection pooling manager. 52 * <LI>Distributed transaction implementation -- produces a 53 * {@code Connection} object that may be used for distributed 54 * transactions and almost always participates in connection pooling. 55 * This implementation works with a middle-tier 56 * transaction manager and almost always with a connection 57 * pooling manager. 58 * </OL> 59 * <P> 60 * A {@code DataSource} object has properties that can be modified 61 * when necessary. For example, if the data source is moved to a different 62 * server, the property for the server can be changed. The benefit is that 63 * because the data source's properties can be changed, any code accessing 64 * that data source does not need to be changed. 65 * <P> 66 * A driver that is accessed via a {@code DataSource} object does not 67 * register itself with the {@code DriverManager}. Rather, a 68 * {@code DataSource} object is retrieved though a lookup operation 69 * and then used to create a {@code Connection} object. With a basic 70 * implementation, the connection obtained through a {@code DataSource} 71 * object is identical to a connection obtained through the 72 * {@code DriverManager} facility. 73 * <p> 74 * An implementation of {@code DataSource} must include a public no-arg 75 * constructor. 76 * 77 * @since 1.4 78 */ 79 80 public interface DataSource extends CommonDataSource, Wrapper { 81 82 /** 83 * <p>Attempts to establish a connection with the data source that 84 * this {@code DataSource} object represents. 85 * 86 * @return a connection to the data source 87 * @exception SQLException if a database access error occurs 88 * @throws java.sql.SQLTimeoutException when the driver has determined that the 89 * timeout value specified by the {@code setLoginTimeout} method 90 * has been exceeded and has at least tried to cancel the 91 * current database connection attempt 92 */ 93 Connection getConnection() throws SQLException; 94 95 /** 96 * <p>Attempts to establish a connection with the data source that 97 * this {@code DataSource} object represents. 98 * 99 * @param username the database user on whose behalf the connection is 100 * being made 101 * @param password the user's password 102 * @return a connection to the data source 103 * @exception SQLException if a database access error occurs 104 * @throws java.sql.SQLTimeoutException when the driver has determined that the 105 * timeout value specified by the {@code setLoginTimeout} method 106 * has been exceeded and has at least tried to cancel the 107 * current database connection attempt 108 * @since 1.4 109 */ 110 Connection getConnection(String username, String password) 111 throws SQLException; 112 113 // JDBC 4.3 114 115 /** 116 * Create a new {@code ConnectionBuilder} instance 117 * @implSpec 118 * The default implementation will throw a {@code SQLFeatureNotSupportedException} 119 * @return The ConnectionBuilder instance that was created 120 * @throws SQLException if an error occurs creating the builder 121 * @throws SQLFeatureNotSupportedException if the driver does not support sharding 122 * @since 1.9 123 * @see createConnectionBuilder 124 */ 125 default ConnectionBuilder createConnectionBuilder() throws SQLException { 126 throw new SQLFeatureNotSupportedException("createConnectionBuilder not implemented"); 127 }; 128 129 /** 130 * Create a new {@code ShardingKeyBuilder} instance 131 * @implSpec 132 * The default implementation will throw a {@code SQLFeatureNotSupportedException} 133 * @return The ShardingKeyBuilder instance that was created 134 * @throws SQLException if an error occurs creating the builder 135 * @throws SQLFeatureNotSupportedException if the driver does not support this method 136 * @since 1.9 137 * @see ShardingKeyBuilder 138 */ 139 default ShardingKeyBuilder createShardingKeyBuilder() 140 throws SQLException { 141 throw new SQLFeatureNotSupportedException("createShardingKeyBuilder not implemented"); 142 }; 143 }