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
26package javax.sql;
27
28import java.sql.Connection;
29import java.sql.ConnectionBuilder;
30import java.sql.SQLException;
31import java.sql.SQLFeatureNotSupportedException;
32import 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&trade; 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 through 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
79public 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  /**
113   * {@inheritDoc}
114   * @since 1.4
115   */
116  @Override
117  java.io.PrintWriter getLogWriter() throws SQLException;
118
119  /**
120   * {@inheritDoc}
121   * @since 1.4
122   */
123  @Override
124  void setLogWriter(java.io.PrintWriter out) throws SQLException;
125
126  /**
127   * {@inheritDoc}
128   * @since 1.4
129   */
130  @Override
131  void setLoginTimeout(int seconds) throws SQLException;
132
133  /**
134   * {@inheritDoc}
135   * @since 1.4
136   */
137  @Override
138  int getLoginTimeout() throws SQLException;
139
140  // JDBC 4.3
141
142  /**
143   * Create a new {@code ConnectionBuilder} instance
144   * @implSpec
145   * The default implementation will throw a {@code SQLFeatureNotSupportedException}
146   * @return The ConnectionBuilder instance that was created
147   * @throws SQLException if an error occurs creating the builder
148   * @throws SQLFeatureNotSupportedException if the driver does not support sharding
149   * @since 9
150   * @see ConnectionBuilder
151   */
152  default ConnectionBuilder createConnectionBuilder() throws SQLException {
153        throw new SQLFeatureNotSupportedException("createConnectionBuilder not implemented");
154  };
155
156}
157