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