KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > sql > DataSource


1 /*
2  * @(#)DataSource.java 1.9 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.sql;
9
10 import java.sql.Connection JavaDoc;
11 import java.sql.SQLException JavaDoc;
12
13 /**
14  * <p>A factory for connections to the physical data source that this
15  * <code>DataSource</code> object represents. An alternative to the
16  * <code>DriverManager</code> facility, a <code>DataSource</code> object
17  * is the preferred means of getting a connection. An object that implements
18  * the <code>DataSource</code> interface will typically be
19  * registered with a naming service based on the
20  * Java<sup><font size=-2>TM</font></sup> Naming and Directory (JNDI) API.
21  * <P>
22  * The <code>DataSource</code> interface is implemented by a driver vendor.
23  * There are three types of implementations:
24  * <OL>
25  * <LI>Basic implementation -- produces a standard <code>Connection</code>
26  * object
27  * <LI>Connection pooling implementation -- produces a <code>Connection</code>
28  * object that will automatically participate in connection pooling. This
29  * implementation works with a middle-tier connection pooling manager.
30  * <LI>Distributed transaction implementation -- produces a
31  * <code>Connection</code> object that may be used for distributed
32  * transactions and almost always participates in connection pooling.
33  * This implementation works with a middle-tier
34  * transaction manager and almost always with a connection
35  * pooling manager.
36  * </OL>
37  * <P>
38  * A <code>DataSource</code> object has properties that can be modified
39  * when necessary. For example, if the data source is moved to a different
40  * server, the property for the server can be changed. The benefit is that
41  * because the data source's properties can be changed, any code accessing
42  * that data source does not need to be changed.
43  * <P>
44  * A driver that is accessed via a <code>DataSource</code> object does not
45  * register itself with the <code>DriverManager</code>. Rather, a
46  * <code>DataSource</code> object is retrieved though a lookup operation
47  * and then used to create a <code>Connection</code> object. With a basic
48  * implementation, the connection obtained through a <code>DataSource</code>
49  * object is identical to a connection obtained through the
50  * <code>DriverManager</code> facility.
51  *
52  * @since 1.4
53  */

54
55 public interface DataSource {
56
57   /**
58    * <p>Attempts to establish a connection with the data source that
59    * this <code>DataSource</code> object represents.
60    *
61    * @return a connection to the data source
62    * @exception SQLException if a database access error occurs
63    */

64   Connection JavaDoc getConnection() throws SQLException JavaDoc;
65       
66   /**
67    * <p>Attempts to establish a connection with the data source that
68    * this <code>DataSource</code> object represents.
69    *
70    * @param username the database user on whose behalf the connection is
71    * being made
72    * @param password the user's password
73    * @return a connection to the data source
74    * @exception SQLException if a database access error occurs
75    */

76   Connection JavaDoc getConnection(String JavaDoc username, String JavaDoc password)
77     throws SQLException JavaDoc;
78       
79   /**
80    * <p>Retrieves the log writer for this <code>DataSource</code>
81    * object.
82    *
83    * <p>The log writer is a character output stream to which all logging
84    * and tracing messages for this data source will be
85    * printed. This includes messages printed by the methods of this
86    * object, messages printed by methods of other objects manufactured
87    * by this object, and so on. Messages printed to a data source
88    * specific log writer are not printed to the log writer associated
89    * with the <code>java.sql.Drivermanager</code> class. When a
90    * <code>DataSource</code> object is
91    * created, the log writer is initially null; in other words, the
92    * default is for logging to be disabled.
93    *
94    * @return the log writer for this data source or null if
95    * logging is disabled
96    * @exception SQLException if a database access error occurs
97    * @see #setLogWriter
98    */

99   java.io.PrintWriter JavaDoc getLogWriter() throws SQLException JavaDoc;
100
101   /**
102    * <p>Sets the log writer for this <code>DataSource</code>
103    * object to the given <code>java.io.PrintWriter</code> object.
104    *
105    * <p>The log writer is a character output stream to which all logging
106    * and tracing messages for this data source will be
107    * printed. This includes messages printed by the methods of this
108    * object, messages printed by methods of other objects manufactured
109    * by this object, and so on. Messages printed to a data source-
110    * specific log writer are not printed to the log writer associated
111    * with the <code>java.sql.Drivermanager</code> class. When a
112    * <code>DataSource</code> object is created the log writer is
113    * initially null; in other words, the default is for logging to be
114    * disabled.
115    *
116    * @param out the new log writer; to disable logging, set to null
117    * @exception SQLException if a database access error occurs
118    * @see #getLogWriter
119    */

120   void setLogWriter(java.io.PrintWriter JavaDoc out) throws SQLException JavaDoc;
121
122   /**
123    * <p>Sets the maximum time in seconds that this data source will wait
124    * while attempting to connect to a database. A value of zero
125    * specifies that the timeout is the default system timeout
126    * if there is one; otherwise, it specifies that there is no timeout.
127    * When a <code>DataSource</code> object is created, the login timeout is
128    * initially zero.
129    *
130    * @param seconds the data source login time limit
131    * @exception SQLException if a database access error occurs.
132    * @see #getLoginTimeout
133    */

134   void setLoginTimeout(int seconds) throws SQLException JavaDoc;
135      
136   /**
137    * Gets the maximum time in seconds that this data source can wait
138    * while attempting to connect to a database. A value of zero
139    * means that the timeout is the default system timeout
140    * if there is one; otherwise, it means that there is no timeout.
141    * When a <code>DataSource</code> object is created, the login timeout is
142    * initially zero.
143    *
144    * @return the data source login time limit
145    * @exception SQLException if a database access error occurs.
146    * @see #setLoginTimeout
147    */

148   int getLoginTimeout() throws SQLException JavaDoc;
149 }
150
151
152
153
154
155
Popular Tags