TransactionSynchronizationRegistry


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.transaction;
25  
26  /**
27   * This interface is intended for use by system level application server
28   * components such as persistence managers, resource adapters, as well as
29   * EJB and Web application components. This provides the ability to
30   * register synchronization objects with special ordering semantics,
31   * associate resource objects with the current transaction, get the
32   * transaction context of the current transaction, get current transaction
33   * status, and mark the current transaction for rollback.
34   *
35   * This interface is implemented by the application server by a
36   * stateless service object. The same object can be used by any number of
37   * components with thread safety.
38   *
39   * <P>In standard application server environments, an instance
40   * implementing this interface can be looked up by a standard name via JNDI.
41   * The standard name is java:comp/TransactionSynchronizationRegistry.
42   *
43   * @since JTA 1.1
44   */
45  public interface TransactionSynchronizationRegistry {
46  
47      /**
48       * Return an opaque object to represent the transaction bound to the
49       * current thread at the time this method is called. This object
50       * overrides hashCode and equals to allow its use as the key in a
51       * hashMap for use by the caller. If there is no transaction currently
52       * active, return null.
53       * 
54       * <P>This object will return the same hashCode and compare equal to
55       * all other objects returned by calling this method
56       * from any component executing in the same transaction context in the
57       * same application server.
58       * 
59       * <P>The toString method returns a String that might be usable by a
60       * human reader to usefully understand the transaction context. The
61       * toString result is otherwise not defined. Specifically, there is no
62       * forward or backward compatibility guarantee of the results of
63       * toString.
64       * 
65       * <P>The object is not necessarily serializable, and has no defined
66       * behavior outside the virtual machine whence it was obtained.
67       *
68       * @return an opaque object representing the transaction bound to the 
69       * current thread at the time this method is called.
70       *
71       * @since JTA 1.1
72       */
73      Object   getTransactionKey();
74      
75      /**
76       * Add or replace an object in the Map of resources being managed for
77       * the transaction bound to the current thread at the time this 
78       * method is called. The supplied key should be of an caller-
79       * defined class so as not to conflict with other users. The class
80       * of the key must guarantee that the hashCode and equals methods are
81       * suitable for use as keys in a map. The key and value are not examined
82       * or used by the implementation. The general contract of this method
83       * is that of {@link java.util.Map#put(Object, Object)} for a Map that
84       * supports non-null keys and null values. For example, 
85       * if there is already an value associated with the key, it is replaced 
86       * by the value parameter. 
87       *
88       * @param key the key for the Map entry.
89       * @param value the value for the Map entry.
90       * @exception IllegalStateException if no transaction is active.
91       * @exception NullPointerException if the parameter key is null.
92       *
93       * @since JTA 1.1
94       */
95      void putResource(Object   key, Object   value);
96      
97      /**
98       * Get an object from the Map of resources being managed for
99       * the transaction bound to the current thread at the time this 
100      * method is called. The key should have been supplied earlier
101      * by a call to putResouce in the same transaction. If the key 
102      * cannot be found in the current resource Map, null is returned.
103      * The general contract of this method
104      * is that of {@link java.util.Map#get(Object)} for a Map that
105      * supports non-null keys and null values. For example, 
106      * the returned value is null if there is no entry for the parameter
107      * key or if the value associated with the key is actually null.
108      *
109      * @param key the key for the Map entry.
110      * @return the value associated with the key.
111      * @exception IllegalStateException if no transaction is active.
112      * @exception NullPointerException if the parameter key is null.
113      *
114      * @since JTA 1.1
115      */
116     Object   getResource(Object   key);
117 
118     /**
119      * Register a Synchronization instance with special ordering
120      * semantics. Its beforeCompletion will be called after all 
121      * SessionSynchronization beforeCompletion callbacks and callbacks 
122      * registered directly with the Transaction, but before the 2-phase
123      * commit process starts. Similarly, the afterCompletion
124      * callback will be called after 2-phase commit completes but before
125      * any SessionSynchronization and Transaction afterCompletion callbacks.
126      * 
127      * <P>The beforeCompletion callback will be invoked in the transaction
128      * context of the transaction bound to the current thread at the time 
129      * this method is called. 
130      * Allowable methods include access to resources,
131      * e.g. Connectors. No access is allowed to "user components" (e.g. timer
132      * services or bean methods), as these might change the state of data
133      * being managed by the caller, and might change the state of data that
134      * has already been flushed by another caller of 
135      * registerInterposedSynchronization. 
136      * The general context is the component
137      * context of the caller of registerInterposedSynchronization.
138      * 
139      * <P>The afterCompletion callback will be invoked in an undefined 
140      * context. No access is permitted to "user components"
141      * as defined above. Resources can be closed but no transactional
142      * work can be performed with them.
143      * 
144      * <P>If this method is invoked without an active transaction context, an
145      * IllegalStateException is thrown.
146      * 
147      * <P>Other than the transaction context, no component J2EE context is
148      * active during either of the callbacks.
149      *
150      * @param sync the Synchronization instance.
151      * @exception IllegalStateException if no transaction is active.
152      *
153      * @since JTA 1.1
154      */
155     void registerInterposedSynchronization(Synchronization   sync);
156 
157     /**
158      * Return the status of the transaction bound to the
159      * current thread at the time this method is called.
160      * This is the result of executing TransactionManager.getStatus() in
161      * the context of the transaction bound to the current thread at the time
162      * this method is called.
163      *
164      * @return the status of the transaction bound to the current thread 
165      * at the time this method is called.
166      *
167      * @since JTA 1.1
168      */
169     int getTransactionStatus();
170 
171     /**
172      * Set the rollbackOnly status of the transaction bound to the
173      * current thread at the time this method is called.
174      *
175      * @exception IllegalStateException if no transaction is active.
176      *
177      * @since JTA 1.1
178      */
179     void setRollbackOnly();
180 
181     /**
182      * Get the rollbackOnly status of the transaction bound to the
183      * current thread at the time this method is called.
184      *
185      * @return the rollbackOnly status.
186      * @exception IllegalStateException if no transaction is active.
187      *
188      * @since JTA 1.1
189      */
190     boolean getRollbackOnly();
191 }
192
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags