1 /*
2 * Copyright (c) 2000, 2016, 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.Wrapper;
33
34 /**
35 * <p>A factory for connections to the physical data source that this
36 * {@code DataSource} object represents. An alternative to the
37 * {@code DriverManager} facility, a {@code DataSource} object
38 * is the preferred means of getting a connection. An object that implements
39 * the {@code DataSource} interface will typically be
40 * registered with a naming service based on the
41 * Java™ Naming and Directory (JNDI) API.
42 * <P>
43 * The {@code DataSource} interface is implemented by a driver vendor.
44 * There are three types of implementations:
45 * <OL>
46 * <LI>Basic implementation -- produces a standard {@code Connection}
47 * object
48 * <LI>Connection pooling implementation -- produces a {@code Connection}
49 * object that will automatically participate in connection pooling. This
50 * implementation works with a middle-tier connection pooling manager.
51 * <LI>Distributed transaction implementation -- produces a
52 * {@code Connection} object that may be used for distributed
53 * transactions and almost always participates in connection pooling.
54 * This implementation works with a middle-tier
55 * transaction manager and almost always with a connection
56 * pooling manager.
57 * </OL>
58 * <P>
59 * A {@code DataSource} object has properties that can be modified
60 * when necessary. For example, if the data source is moved to a different
61 * server, the property for the server can be changed. The benefit is that
62 * because the data source's properties can be changed, any code accessing
63 * that data source does not need to be changed.
64 * <P>
65 * A driver that is accessed via a {@code DataSource} object does not
66 * register itself with the {@code DriverManager}. Rather, a
67 * {@code DataSource} object is retrieved though a lookup operation
68 * and then used to create a {@code Connection} object. With a basic
69 * implementation, the connection obtained through a {@code DataSource}
70 * object is identical to a connection obtained through the
71 * {@code DriverManager} facility.
72 * <p>
73 * An implementation of {@code DataSource} must include a public no-arg
74 * constructor.
75 *
76 * @since 1.4
77 */
78
79 public interface DataSource extends CommonDataSource, Wrapper {
80
81 /**
82 * <p>Attempts to establish a connection with the data source that
83 * this {@code DataSource} object represents.
84 *
85 * @return a connection to the data source
86 * @exception SQLException if a database access error occurs
87 * @throws java.sql.SQLTimeoutException when the driver has determined that the
88 * timeout value specified by the {@code setLoginTimeout} method
89 * has been exceeded and has at least tried to cancel the
90 * current database connection attempt
91 */
92 Connection getConnection() throws SQLException;
93
94 /**
95 * <p>Attempts to establish a connection with the data source that
96 * this {@code DataSource} object represents.
97 *
98 * @param username the database user on whose behalf the connection is
99 * being made
100 * @param password the user's password
101 * @return a connection to the data source
102 * @exception SQLException if a database access error occurs
103 * @throws java.sql.SQLTimeoutException when the driver has determined that the
104 * timeout value specified by the {@code setLoginTimeout} method
105 * has been exceeded and has at least tried to cancel the
106 * current database connection attempt
107 * @since 1.4
108 */
109 Connection getConnection(String username, String password)
110 throws SQLException;
111
112 // JDBC 4.3
113
114 /**
115 * Create a new {@code ConnectionBuilder} instance
116 * @implSpec
117 * The default implementation will throw a {@code SQLFeatureNotSupportedException}
118 * @return The ConnectionBuilder instance that was created
119 * @throws SQLException if an error occurs creating the builder
120 * @throws SQLFeatureNotSupportedException if the driver does not support sharding
121 * @since 9
122 * @see ConnectionBuilder
123 */
124 default ConnectionBuilder createConnectionBuilder() throws SQLException {
125 throw new SQLFeatureNotSupportedException("createConnectionBuilder not implemented");
126 };
127
128 }