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  ;
11  import java.sql.SQLException  ;
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   getConnection() throws SQLException  ;
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   getConnection(String   username, String   password) 
77      throws SQLException  ;
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   getLogWriter() throws SQLException  ;
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   out) throws SQLException  ;
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  ;
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  ;
149 } 
150 
151 
152 
153 
154 
155
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags