KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > resource > spi > ConnectionEventListener


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the License). You may not use this file except in
5  * compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9  * glassfish/bootstrap/legal/CDDLv1.0.txt.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * Header Notice in each file and include the License file
15  * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16  * If applicable, add the following below the CDDL Header,
17  * with the fields enclosed by brackets [] replaced by
18  * you own identifying information:
19  * "Portions Copyrighted [year] [name of copyright owner]"
20  *
21  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22  */

23
24 package javax.resource.spi;
25
26 import java.util.EventListener JavaDoc;
27 import javax.resource.ResourceException JavaDoc;
28
29 /** The <code>ConnectionEventListener</code> interface provides an event
30  * callback mechanism to enable an application server to receive
31  * notifications from a <code>ManagedConnection</code> instance.
32  *
33  * <p>An application server uses these event notifications to manage
34  * its connection pool, to clean up any invalid or terminated connections
35  * and to manage local transactions.
36  *
37  * <p>An application server implements the
38  * <code>ConnectionEventListener</code> interface. It registers a connection
39  * listener with a <code>ManagedConnection</code> instance by using
40  * <code>ManagedConnection.addConnectionEventListener</code> method.
41  *
42  * @version 0.5
43  * @author Rahul Sharma
44  *
45  * @see javax.resource.spi.ConnectionEvent
46  **/

47
48 public interface ConnectionEventListener
49                  extends java.util.EventListener JavaDoc {
50
51   /** Notifies that an application component has closed the connection.
52    *
53    * <p>A ManagedConnection instance notifies its registered set of
54    * listeners by calling ConnectionEventListener.connectionClosed method
55    * when an application component closes a connection handle. The
56    * application server uses this connection close event to put the
57    * ManagedConnection instance back in to the connection pool.
58    *
59    * @param event event object describing the source of
60    * the event
61    */

62   public
63   void connectionClosed(ConnectionEvent JavaDoc event);
64
65   /** Notifies that a Resource Manager Local Transaction was started on
66    * the ManagedConnection instance.
67    *
68    * @param event event object describing the source of
69    * the event
70    */

71   public
72   void localTransactionStarted(ConnectionEvent JavaDoc event);
73
74   /** Notifies that a Resource Manager Local Transaction was committed
75    * on the ManagedConnection instance.
76    *
77    * @param event event object describing the source of
78    * the event
79    */

80   public
81   void localTransactionCommitted(ConnectionEvent JavaDoc event);
82
83   /** Notifies that a Resource Manager Local Transaction was rolled back
84    * on the ManagedConnection instance.
85    *
86    * @param event event object describing the source of
87    * the event
88    */

89   public
90   void localTransactionRolledback(ConnectionEvent JavaDoc event);
91        
92   /** Notifies a connection related error.
93
94    * The ManagedConnection instance calls the method
95    * ConnectionEventListener.connectionErrorOccurred to notify
96    * its registered listeners of the occurrence of a physical
97    * connection-related error. The event notification happens
98    * just before a resource adapter throws an exception to the
99    * application component using the connection handle.
100    *
101    * The connectionErrorOccurred method indicates that the
102    * associated ManagedConnection instance is now invalid and
103    * unusable. The application server handles the connection
104    * error event notification by initiating application
105    * server-specific cleanup (for example, removing ManagedConnection
106    * instance from the connection pool) and then calling
107    * ManagedConnection.destroy method to destroy the physical
108    * connection.
109    *
110    * @param event event object describing the source of
111    * the event
112    */

113   public
114   void connectionErrorOccurred(ConnectionEvent JavaDoc event);
115
116 }
117
Popular Tags