PooledConnection


1   /*
2    * @(#)PooledConnection.java    1.12 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   * An object that provides hooks for connection pool management.  
15   * A <code>PooledConnection</code> object
16   * represents a physical connection to a data source.  The connection
17   * can be recycled rather than being closed when an application is
18   * finished with it, thus reducing the number of connections that
19   * need to be made.
20   * <P>
21   * An application programmer does not use the <code>PooledConnection</code>
22   * interface directly; rather, it is used by a middle tier infrastructure
23   * that manages the pooling of connections.
24   * <P>
25   * When an application calls the method <code>DataSource.getConnection</code>,
26   * it gets back a <code>Connection</code> object.  If connection pooling is
27   * being done, that <code>Connection</code> object is actually a handle to
28   * a <code>PooledConnection</code> object, which is a physical connection.
29   * <P>
30   * The connection pool manager, typically the application server, maintains
31   * a pool of <code>PooledConnection</code> objects.  If there is a
32   * <code>PooledConnection</code> object available in the pool, the
33   * connection pool manager returns a <code>Connection</code> object that
34   * is a handle to that physical connection.
35   * If no <code>PooledConnection</code> object is available, the 
36   * connection pool manager calls the <code>PooledConnection</code>
37   * method <code>getConnection</code> to create a new physical connection and
38   * returns a handle to it.
39   * <P>
40   * When an application closes a connection, it calls the <code>Connection</code>
41   * method <code>close</code>. When connection pooling is being done,
42   * the connection pool manager is notified because it has registered itself as
43   * a <code>ConnectionEventListener</code> object using the 
44   * <code>ConnectionPool</code> method <code>addConnectionEventListener</code>.
45   * The connection pool manager deactivates the handle to
46   * the <code>PooledConnection</code> object and  returns the 
47   * <code>PooledConnection</code> object to the pool of connections so that
48   * it can be used again.  Thus, when an application closes its connection,
49   * the underlying physical connection is recycled rather than being closed.
50   * <P>
51   * The physical connection is not closed until the connection pool manager
52   * calls the <code>PooledConnection</code> method <code>close</code>.
53   * This method is generally called to have an orderly shutdown of the server or
54   * if a fatal error has made the connection unusable.
55   *
56   * @since 1.4 
57   */
58  
59  public interface PooledConnection {
60  
61    /**
62     * Creates and returns a <code>Connection</code> object that is a handle
63     * for the physical connection that
64     * this <code>PooledConnection</code> object represents.
65     * The connection pool manager calls this method when an application has
66     * called the method <code>DataSource.getConnection</code> and there are
67     * no <code>PooledConnection</code> objects available. See the
68     * {@link PooledConnection interface description} for more information.
69     *
70     * @return  a <code>Connection</code> object that is a handle to
71     *          this <code>PooledConnection</code> object
72     * @exception SQLException if a database access error occurs
73     */
74    Connection   getConnection() throws SQLException  ;
75  
76    /**
77     * Closes the physical connection that this <code>PooledConnection</code>
78     * object represents.  An application never calls this method directly;
79     * it is called by the connection pool module, or manager.
80     * <P>
81     * See the {@link PooledConnection interface description} for more 
82     * information.
83     *
84     * @exception SQLException if a database access error occurs
85     */
86    void close() throws SQLException  ;
87        
88    /**
89     * Registers the given event listener so that it will be notified
90     * when an event occurs on this <code>PooledConnection</code> object.
91     *
92     * @param listener a component, usually the connection pool manager,
93     *        that has implemented the
94     *        <code>ConnectionEventListener</code> interface and wants to be
95     *        notified when the connection is closed or has an error
96     * @see #removeConnectionEventListener
97     */
98    void addConnectionEventListener(ConnectionEventListener   listener);
99  
100   /**
101    * Removes the given event listener from the list of components that
102    * will be notified when an event occurs on this
103    * <code>PooledConnection</code> object.
104    *
105    * @param listener a component, usually the connection pool manager,
106    *        that has implemented the
107    *        <code>ConnectionEventListener</code> interface and 
108    *        been registered with this <code>PooledConnection</code> object as 
109    *        a listener
110    * @see #addConnectionEventListener
111    */
112   void removeConnectionEventListener(ConnectionEventListener   listener);
113 
114  } 
115
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags