src/share/classes/javax/sql/PooledConnection.java

Print this page




  66  * <code>PooledConnection</code> object to the pool of connections so that
  67  * it can be used again.  Thus, when an application closes its connection,
  68  * the underlying physical connection is recycled rather than being closed.
  69  * <P>
  70  * The physical connection is not closed until the connection pool manager
  71  * calls the <code>PooledConnection</code> method <code>close</code>.
  72  * This method is generally called to have an orderly shutdown of the server or
  73  * if a fatal error has made the connection unusable.
  74  *
  75  * <p>
  76  * A connection pool manager is often also a statement pool manager, maintaining
  77  *  a pool of <code>PreparedStatement</code> objects.
  78  *  When an application closes a prepared statement, it calls the
  79  *  <code>PreparedStatement</code>
  80  * method <code>close</code>. When <code>Statement</code> pooling is being done,
  81  * the pool manager is notified because it has registered itself as
  82  * a <code>StatementEventListener</code> object using the
  83  * <code>ConnectionPool</code> method <code>addStatementEventListener</code>.
  84  *  Thus, when an application closes its  <code>PreparedStatement</code>,
  85  * the underlying prepared statement is recycled rather than being closed.
  86  * <P>
  87  *
  88  * @since 1.4
  89  */
  90 
  91 public interface PooledConnection {
  92 
  93   /**
  94    * Creates and returns a <code>Connection</code> object that is a handle
  95    * for the physical connection that
  96    * this <code>PooledConnection</code> object represents.
  97    * The connection pool manager calls this method when an application has
  98    * called the method <code>DataSource.getConnection</code> and there are
  99    * no <code>PooledConnection</code> objects available. See the
 100    * {@link PooledConnection interface description} for more information.
 101    *
 102    * @return  a <code>Connection</code> object that is a handle to
 103    *          this <code>PooledConnection</code> object
 104    * @exception SQLException if a database access error occurs
 105    * @exception java.sql.SQLFeatureNotSupportedException if the JDBC driver does not support
 106    * this method


 137 
 138   /**
 139    * Removes the given event listener from the list of components that
 140    * will be notified when an event occurs on this
 141    * <code>PooledConnection</code> object.
 142    *
 143    * @param listener a component, usually the connection pool manager,
 144    *        that has implemented the
 145    *        <code>ConnectionEventListener</code> interface and
 146    *        been registered with this <code>PooledConnection</code> object as
 147    *        a listener
 148    * @see #addConnectionEventListener
 149    */
 150   void removeConnectionEventListener(ConnectionEventListener listener);
 151 
 152         /**
 153          * Registers a <code>StatementEventListener</code> with this <code>PooledConnection</code> object.  Components that
 154          * wish to be notified when  <code>PreparedStatement</code>s created by the
 155          * connection are closed or are detected to be invalid may use this method
 156          * to register a <code>StatementEventListener</code> with this <code>PooledConnection</code> object.
 157          * <p>
 158          * @param listener      an component which implements the <code>StatementEventListener</code>
 159          *                                      interface that is to be registered with this <code>PooledConnection</code> object
 160          * <p>
 161          * @since 1.6
 162          */
 163         public void addStatementEventListener(StatementEventListener listener);
 164 
 165         /**
 166          * Removes the specified <code>StatementEventListener</code> from the list of
 167          * components that will be notified when the driver detects that a
 168          * <code>PreparedStatement</code> has been closed or is invalid.
 169          * <p>
 170          * @param listener      the component which implements the
 171          *                                      <code>StatementEventListener</code> interface that was previously
 172          *                                      registered with this <code>PooledConnection</code> object
 173          * <p>
 174          * @since 1.6
 175          */
 176         public void removeStatementEventListener(StatementEventListener listener);
 177 
 178  }


  66  * <code>PooledConnection</code> object to the pool of connections so that
  67  * it can be used again.  Thus, when an application closes its connection,
  68  * the underlying physical connection is recycled rather than being closed.
  69  * <P>
  70  * The physical connection is not closed until the connection pool manager
  71  * calls the <code>PooledConnection</code> method <code>close</code>.
  72  * This method is generally called to have an orderly shutdown of the server or
  73  * if a fatal error has made the connection unusable.
  74  *
  75  * <p>
  76  * A connection pool manager is often also a statement pool manager, maintaining
  77  *  a pool of <code>PreparedStatement</code> objects.
  78  *  When an application closes a prepared statement, it calls the
  79  *  <code>PreparedStatement</code>
  80  * method <code>close</code>. When <code>Statement</code> pooling is being done,
  81  * the pool manager is notified because it has registered itself as
  82  * a <code>StatementEventListener</code> object using the
  83  * <code>ConnectionPool</code> method <code>addStatementEventListener</code>.
  84  *  Thus, when an application closes its  <code>PreparedStatement</code>,
  85  * the underlying prepared statement is recycled rather than being closed.

  86  *
  87  * @since 1.4
  88  */
  89 
  90 public interface PooledConnection {
  91 
  92   /**
  93    * Creates and returns a <code>Connection</code> object that is a handle
  94    * for the physical connection that
  95    * this <code>PooledConnection</code> object represents.
  96    * The connection pool manager calls this method when an application has
  97    * called the method <code>DataSource.getConnection</code> and there are
  98    * no <code>PooledConnection</code> objects available. See the
  99    * {@link PooledConnection interface description} for more information.
 100    *
 101    * @return  a <code>Connection</code> object that is a handle to
 102    *          this <code>PooledConnection</code> object
 103    * @exception SQLException if a database access error occurs
 104    * @exception java.sql.SQLFeatureNotSupportedException if the JDBC driver does not support
 105    * this method


 136 
 137   /**
 138    * Removes the given event listener from the list of components that
 139    * will be notified when an event occurs on this
 140    * <code>PooledConnection</code> object.
 141    *
 142    * @param listener a component, usually the connection pool manager,
 143    *        that has implemented the
 144    *        <code>ConnectionEventListener</code> interface and
 145    *        been registered with this <code>PooledConnection</code> object as
 146    *        a listener
 147    * @see #addConnectionEventListener
 148    */
 149   void removeConnectionEventListener(ConnectionEventListener listener);
 150 
 151         /**
 152          * Registers a <code>StatementEventListener</code> with this <code>PooledConnection</code> object.  Components that
 153          * wish to be notified when  <code>PreparedStatement</code>s created by the
 154          * connection are closed or are detected to be invalid may use this method
 155          * to register a <code>StatementEventListener</code> with this <code>PooledConnection</code> object.
 156          *
 157          * @param listener      an component which implements the <code>StatementEventListener</code>
 158          *                                      interface that is to be registered with this <code>PooledConnection</code> object
 159          *
 160          * @since 1.6
 161          */
 162         public void addStatementEventListener(StatementEventListener listener);
 163 
 164         /**
 165          * Removes the specified <code>StatementEventListener</code> from the list of
 166          * components that will be notified when the driver detects that a
 167          * <code>PreparedStatement</code> has been closed or is invalid.
 168          *
 169          * @param listener      the component which implements the
 170          *                                      <code>StatementEventListener</code> interface that was previously
 171          *                                      registered with this <code>PooledConnection</code> object
 172          *
 173          * @since 1.6
 174          */
 175         public void removeStatementEventListener(StatementEventListener listener);
 176 
 177  }