StatementEventListener


1   /*
2    * Created on Apr 28, 2005
3    */
4   package javax.sql;
5   
6   /**
7    * An object that registers to be notified of events that occur on PreparedStatements
8    * that are in the Statement pool.
9    * <p>
10   * The JDBC 3.0 specification added the maxStatements 
11   * <code>ConnectionPooledDataSource</code> property to provide a standard mechanism for 
12   * enabling the pooling of <code>PreparedStatements</code>
13   * and to specify the size of the statement 
14   * pool.  However, there was no way for a driver to notify an external 
15   * statement pool when a <code>PreparedStatement</code> becomes invalid.  For some databases, a 
16   * statement becomes invalid if a DDL operation is performed that affects the 
17   * table.  For example an application may create a temporary table to do some work 
18   * on the table and then destroy it.  It may later recreate the same table when 
19   * it is needed again.  Some databases will invalidate any prepared statements 
20   * that reference the temporary table when the table is dropped.
21   * <p>
22   * Similar to the methods defined in the <code>ConnectionEventListener</code> interface,
23   * the driver will call the <code>StatementEventListener.statementErrorOccurred</code> 
24   * method prior to throwing any exceptions when it detects a statement is invalid.
25   * The driver will also call the <code>StatementEventListener.statementClosed</code> 
26   * method when a <code>PreparedStatement</code> is closed.
27   * <p>
28   * Methods which allow a component to register a StatementEventListener with a 
29   * <code>PooledConnection</code> have been added to the <code>PooledConnection</code> interface.
30   * <p>
31   * @since 1.6   
32   */
33  public interface StatementEventListener  extends java.util.EventListener  {
34    /**
35     * The driver calls this method on all <code>StatementEventListener</code>s registered on the connection when it detects that a 
36     * <code>PreparedStatement</code> is closed.
37     *
38     * @param event an event object describing the source of 
39     * the event and that the <code>PreparedStatement</code> was closed. 
40     * @since 1.6
41     */
42    void statementClosed(StatementEvent   event);
43      
44      /**
45       * The driver calls this method on all <code>StatementEventListener</code>s
46           * registered on the connection when it detects that a 
47           * <code>PreparedStatement</code> is invalid. The driver calls this method 
48           * just before it throws the <code>SQLException</code>, 
49       * contained in the given event, to the application.
50       * <p>
51       * @param event     an event object describing the source of the event, 
52       *                  the statement that is invalid and the exception the 
53       *                  driver is about to throw.  The source of the event is 
54       *                  the <code>PooledConnection</code> which the invalid <code>PreparedStatement</code>
55           * is associated with.
56       * <p>
57       * @since 1.6
58       */
59      void statementErrorOccurred(StatementEvent   event);
60          
61  }
62
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags