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