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  ;
27  import javax.resource.NotSupportedException  ;
28  import javax.resource.spi.ActivationSpec  ;
29  import javax.resource.spi.endpoint.MessageEndpointFactory  ;
30  
31  import javax.transaction.xa.XAResource  ;
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   ctx) throws ResourceAdapterInternalException  ; 
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   endpointFactory, 
104             ActivationSpec   spec) throws ResourceException  ;
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   endpointFactory, 
121             ActivationSpec   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  [] getXAResources(ActivationSpec  [] specs) 
150     throws ResourceException  ;
151 }
152
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags