001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.xa.XAResourceManager
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.access.xa;
023:
024: import org.apache.derby.iapi.services.context.ContextManager;
025:
026: import org.apache.derby.iapi.error.StandardException;
027:
028: import javax.transaction.xa.Xid;
029:
030: /**
031:
032: This interface allows access to commit,prepare,abort global transactions
033: as part of a two phase commit protocol. These interfaces have been chosen
034: to be exact implementations required to implement the XAResource interfaces
035: as part of the JTA standard extension.
036: <P>
037: It is expected that the following interfaces are only used during the
038: recovery portion of 2 phase commit, when the transaction manager is
039: cleaning up after a runtime crash - it is expected that no current context
040: managers exist for the Xid's being operated on. The "online" two phase commit
041: protocol will be implemented by calls directly on a TransactionController.
042: <P>
043: The XAResource interface is a Java mapping of the industry standard XA resource
044: manager interface. Please refer to: X/Open CAE Specification - Distributed
045: Transaction Processing: The XA Specification, X/Open Document No. XO/CAE/91/300
046: or ISBN 1 872630 24 3.
047: <P>
048:
049: **/
050:
051: public interface XAResourceManager {
052: /**************************************************************************
053: * Public Methods of This class:
054: **************************************************************************
055: */
056:
057: /**
058: * This method is called to commit the global transaction specified by xid.
059: * <p>
060: * RESOLVE - how do we map to the "right" XAExceptions.
061: * <p>
062: *
063: * @param cm The ContextManager returned from the find() call.
064: * @param xid A global transaction identifier.
065: * @param onePhase If true, the resource manager should use a one-phase
066: * commit protocol to commit the work done on behalf of
067: * xid.
068: *
069: * @exception StandardException Standard exception policy.
070: **/
071: public void commit(ContextManager cm, Xid xid, boolean onePhase)
072: throws StandardException;
073:
074: /**
075: * Find the given Xid in the transaction table.
076: * <p>
077: * This routine is used to find a in-doubt transaction from the list
078: * of Xid's returned from the recover() routine.
079: * <p>
080: * In the current implementation it is up to the calling routine
081: * to make the returned ContextManager the "current" ContextManager
082: * before calls to commit,abort, or forget. The caller is responsible
083: * for error handling, ie. calling cleanupOnError() on the correct
084: * ContextManager.
085: * <p>
086: * If the Xid is not in the system, "null" is returned.
087: * RESOLVE - find out from sku if she wants a exception instead?
088: * <p>
089: *
090: * @param xid A global transaction identifier.
091: **/
092: public ContextManager find(Xid xid);
093:
094: /**
095: * This method is called to remove the given transaction
096: * from the transaction table/log.
097: * <p>
098: * Used to let the store remove all record from log and transaction
099: * table of the given transaction. This should only be used to
100: * clean up heuristically completed transactions, otherwise commit or
101: * abort should be used to act on other transactions.
102: * <p>
103: * If forget() is called on a transaction which has not be heuristically
104: * completed then it will throw an exception:
105: * SQLState.STORE_XA_PROTOCOL_VIOLATION.
106: *
107: * @param cm The ContextManager returned from the find() call.
108: * @param xid A global transaction identifier.
109: *
110: * @exception StandardException Standard exception policy.
111: *
112: **/
113: public void forget(ContextManager cm, Xid xid)
114: throws StandardException;
115:
116: /**
117: * This method is called to obtain a list of prepared transactions.
118: * <p>
119: * This call returns a complete list of global transactions which are
120: * either prepared or heuristically complete.
121: * <p>
122: * The XAResource interface expects a scan type interface, but our
123: * implementation only returns a complete list of transactions. So to
124: * simulate the scan the following state is maintained. If TMSTARTSCAN
125: * is specified the complete list is returned. If recover is called with
126: * TMNOFLAGS is ever called a 0 length array is returned.
127: *
128: * @return Return a array with 0 or more Xid's which are currently in
129: * prepared or heuristically completed state. If an error occurs
130: * during the operation, an appropriate error is thrown.
131: *
132: * @param flags combination of the following flags
133: * XAResource.{TMSTARTRSCAN,TMENDRSCAN,TMNOFLAGS}.
134: * TMNOFLAGS must be used when no other flags are used.
135: *
136: * @exception StandardException Standard exception policy.
137: **/
138: public Xid[] recover(int flags) throws StandardException;
139:
140: /**
141: * rollback the transaction identified by Xid.
142: * <p>
143: * The given transaction is roll'ed back and it's history is not
144: * maintained in the transaction table or long term log.
145: * <p>
146: *
147: * @param cm The ContextManager returned from the find() call.
148: * @param xid A global transaction identifier.
149: *
150: * @exception StandardException Standard exception policy.
151: **/
152: public void rollback(ContextManager cm, Xid xid)
153: throws StandardException;
154: }
|