Source code: org/apache/derby/iapi/store/access/xa/XAResourceManager.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.store.access.xa.XAResourceManager
4
5 Copyright 1999, 2004 The Apache Software Foundation or its licensors, as applicable.
6
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
10
11 http://www.apache.org/licenses/LICENSE-2.0
12
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18
19 */
20
21 package org.apache.derby.iapi.store.access.xa;
22
23 import org.apache.derby.iapi.services.context.ContextManager;
24
25 import org.apache.derby.iapi.error.StandardException;
26
27 import javax.transaction.xa.Xid;
28
29 /**
30
31 This interface allows access to commit,prepare,abort global transactions
32 as part of a two phase commit protocol. These interfaces have been chosen
33 to be exact implementations required to implement the XAResource interfaces
34 as part of the JTA standard extension.
35 <P>
36 It is expected that the following interfaces are only used during the
37 recovery portion of 2 phase commit, when the transaction manager is
38 cleaning up after a runtime crash - it is expected that no current context
39 managers exist for the Xid's being operated on. The "online" two phase commit
40 protocol will be implemented by calls directly on a TransactionController.
41 <P>
42 The XAResource interface is a Java mapping of the industry standard XA resource
43 manager interface. Please refer to: X/Open CAE Specification - Distributed
44 Transaction Processing: The XA Specification, X/Open Document No. XO/CAE/91/300
45 or ISBN 1 872630 24 3.
46 <P>
47
48 **/
49
50 public interface XAResourceManager
51 {
52 /**************************************************************************
53 * Public Methods of This class:
54 **************************************************************************
55 */
56
57 /**
58 * This method is called to commit the global transaction specified by xid.
59 * <p>
60 * RESOLVE - how do we map to the "right" XAExceptions.
61 * <p>
62 *
63 * @return The identifier to be used to open the conglomerate later.
64 *
65 * @param cm The ContextManager returned from the find() call.
66 * @param xid A global transaction identifier.
67 * @param onePhase If true, the resource manager should use a one-phase
68 * commit protocol to commit the work done on behalf of
69 * xid.
70 *
71 * @exception StandardException Standard exception policy.
72 **/
73 public void commit(
74 ContextManager cm,
75 Xid xid,
76 boolean onePhase)
77 throws StandardException;
78
79 /**
80 * Find the given Xid in the transaction table.
81 * <p>
82 * This routine is used to find a in-doubt transaction from the list
83 * of Xid's returned from the recover() routine.
84 * <p>
85 * In the current implementation it is up to the calling routine
86 * to make the returned ContextManager the "current" ContextManager
87 * before calls to commit,abort, or forget. The caller is responsible
88 * for error handling, ie. calling cleanupOnError() on the correct
89 * ContextManager.
90 * <p>
91 * If the Xid is not in the system, "null" is returned.
92 * RESOLVE - find out from sku if she wants a exception instead?
93 * <p>
94 *
95 * @param xid A global transaction identifier.
96 **/
97 public ContextManager find(
98 Xid xid);
99
100 /**
101 * This method is called to remove the given transaction
102 * from the transaction table/log.
103 * <p>
104 * Used to let the store remove all record from log and transaction
105 * table of the given transaction. This should only be used to
106 * clean up heuristically completed transactions, otherwise commit or
107 * abort should be used to act on other transactions.
108 * <p>
109 * If forget() is called on a transaction which has not be heuristically
110 * completed then it will throw an exception:
111 * SQLState.STORE_XA_PROTOCOL_VIOLATION.
112 *
113 * @param cm The ContextManager returned from the find() call.
114 * @param xid A global transaction identifier.
115 *
116 * @exception StandardException Standard exception policy.
117 *
118 **/
119 public void forget(
120 ContextManager cm,
121 Xid xid)
122 throws StandardException;
123
124 /**
125 * This method is called to obtain a list of prepared transactions.
126 * <p>
127 * This call returns a complete list of global transactions which are
128 * either prepared or heuristically complete.
129 * <p>
130 * The XAResource interface expects a scan type interface, but our
131 * implementation only returns a complete list of transactions. So to
132 * simulate the scan the following state is maintained. If TMSTARTSCAN
133 * is specified the complete list is returned. If recover is called with
134 * TMNOFLAGS is ever called a 0 length array is returned.
135 *
136 * @return Return a array with 0 or more Xid's which are currently in
137 * prepared or heuristically completed state. If an error occurs
138 * during the operation, an appropriate error is thrown.
139 *
140 * @param flags combination of the following flags
141 * XAResource.{TMSTARTRSCAN,TMENDRSCAN,TMNOFLAGS}.
142 * TMNOFLAGS must be used when no other flags are used.
143 *
144 * @exception StandardException Standard exception policy.
145 **/
146 public Xid[] recover(int flags)
147 throws StandardException;
148
149 /**
150 * rollback the transaction identified by Xid.
151 * <p>
152 * The given transaction is roll'ed back and it's history is not
153 * maintained in the transaction table or long term log.
154 * <p>
155 *
156 * @param cm The ContextManager returned from the find() call.
157 * @param xid A global transaction identifier.
158 *
159 * @exception StandardException Standard exception policy.
160 **/
161 public void rollback(
162 ContextManager cm,
163 Xid xid)
164 throws StandardException;
165 }