1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
12 * language governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
16 * Sun designates this particular file as subject to the "Classpath" exception
17 * as provided by Sun in the GPL Version 2 section of the License file that
18 * accompanied this code. If applicable, add the following below the License
19 * Header, with the fields enclosed by brackets [] replaced by your own
20 * identifying information: "Portions Copyrighted [year]
21 * [name of copyright owner]"
22 *
23 * Contributor(s):
24 *
25 * If you wish your version of this file to be governed by only the CDDL or
26 * only the GPL Version 2, indicate your decision by adding "[Contributor]
27 * elects to include this software in this distribution under the [CDDL or GPL
28 * Version 2] license." If you don't indicate a single choice of license, a
29 * recipient has the option to distribute your version of this file under
30 * either the CDDL, the GPL Version 2 or to extend the choice of license to
31 * its licensees as provided above. However, if you add GPL Version 2 code
32 * and therefore, elected the GPL Version 2 license, then the option applies
33 * only if the new code is made subject to such option by the copyright
34 * holder.
35 */
36
37 package javax.resource.spi;
38
39 import java.util.EventListener;
40 import javax.resource.ResourceException;
41
42 /** The <code>ConnectionEventListener</code> interface provides an event
43 * callback mechanism to enable an application server to receive
44 * notifications from a <code>ManagedConnection</code> instance.
45 *
46 * <p>An application server uses these event notifications to manage
47 * its connection pool, to clean up any invalid or terminated connections
48 * and to manage local transactions.
49 *
50 * <p>An application server implements the
51 * <code>ConnectionEventListener</code> interface. It registers a connection
52 * listener with a <code>ManagedConnection</code> instance by using
53 * <code>ManagedConnection.addConnectionEventListener</code> method.
54 *
55 * @version 0.5
56 * @author Rahul Sharma
57 *
58 * @see javax.resource.spi.ConnectionEvent
59 **/
60
61 public interface ConnectionEventListener
62 extends java.util.EventListener {
63
64 /** Notifies that an application component has closed the connection.
65 *
66 * <p>A ManagedConnection instance notifies its registered set of
67 * listeners by calling ConnectionEventListener.connectionClosed method
68 * when an application component closes a connection handle. The
69 * application server uses this connection close event to put the
70 * ManagedConnection instance back in to the connection pool.
71 *
72 * @param event event object describing the source of
73 * the event
74 */
75 public
76 void connectionClosed(ConnectionEvent event);
77
78 /** Notifies that a Resource Manager Local Transaction was started on
79 * the ManagedConnection instance.
80 *
81 * @param event event object describing the source of
82 * the event
83 */
84 public
85 void localTransactionStarted(ConnectionEvent event);
86
87 /** Notifies that a Resource Manager Local Transaction was committed
88 * on the ManagedConnection instance.
89 *
90 * @param event event object describing the source of
91 * the event
92 */
93 public
94 void localTransactionCommitted(ConnectionEvent event);
95
96 /** Notifies that a Resource Manager Local Transaction was rolled back
97 * on the ManagedConnection instance.
98 *
99 * @param event event object describing the source of
100 * the event
101 */
102 public
103 void localTransactionRolledback(ConnectionEvent event);
104
105 /** Notifies a connection related error.
106
107 * The ManagedConnection instance calls the method
108 * ConnectionEventListener.connectionErrorOccurred to notify
109 * its registered listeners of the occurrence of a physical
110 * connection-related error. The event notification happens
111 * just before a resource adapter throws an exception to the
112 * application component using the connection handle.
113 *
114 * The connectionErrorOccurred method indicates that the
115 * associated ManagedConnection instance is now invalid and
116 * unusable. The application server handles the connection
117 * error event notification by initiating application
118 * server-specific cleanup (for example, removing ManagedConnection
119 * instance from the connection pool) and then calling
120 * ManagedConnection.destroy method to destroy the physical
121 * connection.
122 *
123 * @param event event object describing the source of
124 * the event
125 */
126 public
127 void connectionErrorOccurred(ConnectionEvent event);
128
129 }
Save This Page