KickJava   Java API By Example, From Geeks To Geeks.

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


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 javax.resource.ResourceException JavaDoc;
27 import javax.resource.NotSupportedException JavaDoc;
28 import javax.resource.spi.ActivationSpec JavaDoc;
29 import javax.resource.spi.endpoint.MessageEndpointFactory JavaDoc;
30
31 import javax.transaction.xa.XAResource JavaDoc;
32
33 /**
34  * This represents a resource adapter instance and contains operations for
35  * lifecycle management and message endpoint setup. A concrete implementation
36  * of this interface is required to be a JavaBean.
37  *
38  * @version 1.0
39  * @author Ram Jeyaraman
40  */

41 public interface ResourceAdapter {
42
43     // lifecycle operations
44

45     /**
46      * This is called when a resource adapter instance is bootstrapped. This
47      * may be during resource adapter deployment or application server startup.
48      * This is a startup notification from the application server, and this
49      * method is called by an application server thread. The application server
50      * thread executes in an unspecified context.
51      *
52      * <p>During this method call a ResourceAdapter JavaBean is
53      * responsible for initializing the resource adapter
54      * instance. Any exception thrown during this method
55      * call causes the application server to abort the bootstrap procedure
56      * for this specific resource adapter instance.
57      *
58      * @param ctx a bootstrap context containing references to
59      * useful facilities that could be used by a resource adapter instance.
60      *
61      * @throws ResourceAdapterInternalException indicates bootstrap failure.
62      * The resource adapter instance is unusable and must be discarded.
63      */

64     void start(BootstrapContext JavaDoc ctx) throws ResourceAdapterInternalException JavaDoc;
65
66     /**
67      * This is called when a resource adapter instance is undeployed or
68      * during application server shutdown. This is a shutdown notification
69      * from the application server, and this method is called by an
70      * application server thread. The application server
71      * thread executes in an unspecified context.
72      *
73      * <p>During this method call, a ResourceAdapter
74      * JavaBean is responsible for performing an orderly shutdown of the
75      * resource adapter instance. Any exception thrown by this
76      * method call does not alter the
77      * processing of the application server shutdown or resource
78      * adapter undeployment that caused this method call. The application
79      * server may log the exception information for error reporting purposes.
80      */

81     void stop();
82
83     // message endpoint setup operations
84

85     /**
86      * This is called during the activation of a message endpoint. This causes
87      * the resource adapter instance to do the necessary setup (ie., setup
88      * message delivery for the message endpoint with a message provider).
89      * Note that message delivery to the message endpoint might start even
90      * before this method returns.
91      *
92      * <p>Endpoint activation is deemed successful only when this method
93      * completes successfully without throwing any exceptions.
94      *
95      * @param endpointFactory a message endpoint factory instance.
96      *
97      * @param spec an activation spec JavaBean instance.
98      *
99      * @throws NotSupportedException indicates message endpoint
100      * activation rejection due to incorrect activation
101      * setup information.
102      */

103     void endpointActivation(MessageEndpointFactory JavaDoc endpointFactory,
104             ActivationSpec JavaDoc spec) throws ResourceException JavaDoc;
105
106     /**
107      * This is called when a message endpoint is deactivated. The instances
108      * passed as arguments to this method call should be identical to those
109      * passed in for the corresponding </code>endpointActivation</code> call.
110      * This causes the resource adapter to stop delivering messages to the
111      * message endpoint.
112      *
113      * <p>Any exception thrown by this method is ignored. After
114      * this method call, the endpoint is deemed inactive.
115      *
116      * @param endpointFactory a message endpoint factory instance.
117      *
118      * @param spec an activation spec JavaBean instance.
119      */

120     void endpointDeactivation(MessageEndpointFactory JavaDoc endpointFactory,
121             ActivationSpec JavaDoc spec);
122
123     /**
124      * This method is called by the application server during crash recovery.
125      * This method takes in an array of <code>ActivationSpec</code> JavaBeans
126      * and returns an array of <code>XAResource</code> objects each of which
127      * represents a unique resource manager.
128      *
129      * The resource adapter may return null if it does not implement the
130      * <code>XAResource</code> interface. Otherwise, it must return an array
131      * of <code>XAResource</code> objects, each of which represents a unique
132      * resource manager that was used by the endpoint applications.
133      *
134      * The application server uses the <code>XAResource</code> objects to
135      * query each resource manager for a list of in-doubt transactions.
136      * It then completes each pending transaction by sending the commit
137      * decision to the participating resource managers.
138      *
139      * @param specs an array of <code>ActivationSpec</code> JavaBeans each of
140      * which corresponds to an deployed endpoint application that was
141      * active prior to the system crash.
142      *
143      * @throws ResourceException generic exception if operation fails due to an
144      * error condition.
145      *
146      * @return an array of <code>XAResource</code> objects each of which
147      * represents a unique resource manager.
148      */

149     XAResource JavaDoc[] getXAResources(ActivationSpec JavaDoc[] specs)
150     throws ResourceException JavaDoc;
151 }
152
Popular Tags