001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.XATransactionController
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;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: import org.apache.derby.iapi.store.access.TransactionController;
027:
028: /**
029:
030: This interface allows access to commit,prepare,abort global transactions
031: as part of a two phase commit protocol, during runtime.
032: These interfaces have been chosen to be exact implementations required to
033: implement the XAResource interfaces as part of the JTA standard extension.
034: <P>
035: It is expected that the following interfaces are only used during the
036: runtime portion of a 2 phase commit connection.
037: <P>
038: If a runtime exception causes a transaction abort (of a transaction that
039: has not been successfully prepared), then the transaction will act as if
040: xa_rollback() had been called. The transaction will be aborted and any
041: other call other than destroy will throw exceptions.
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: NOTE - all calls to this interface assume that the caller has insured that
049: there is no active work being done on the local instance of the transaction
050: in question. RESOLVE - not sure whether this means that the connection
051: associated with the transaction must be closed, or if it just means that
052: synchronization has been provided to provide correct MT behavior from above.
053:
054: **/
055:
056: public interface XATransactionController extends TransactionController {
057: /**************************************************************************
058: * Public Methods of This class:
059: **************************************************************************
060: */
061: public static final int XA_RDONLY = 1;
062: public static final int XA_OK = 2;
063:
064: /**
065: * This method is called to commit the current XA global transaction.
066: * <p>
067: * Once this call has been made all other calls on this controller other
068: * than destroy will throw exceptions.
069: * <p>
070: *
071: * @param onePhase If true, the resource manager should use a one-phase
072: * commit protocol to commit the work done on behalf of
073: * current xid.
074: *
075: * @exception StandardException Standard exception policy.
076: **/
077: public void xa_commit(boolean onePhase) throws StandardException;
078:
079: /**
080: * This method is called to ask the resource manager to prepare for
081: * a transaction commit of the transaction specified in xid.
082: * <p>
083: * If XA_OK is returned then any call other than xa_commit() or xa_abort()
084: * will throw exceptions. If XA_RDONLY is returned then any call other
085: * than destroy() will throw exceptions.
086: *
087: * @return A value indicating the resource manager's vote on the
088: * the outcome of the transaction. The possible values
089: * are: XA_RDONLY or XA_OK. If the resource manager wants
090: * to roll back the transaction, it should do so by
091: * throwing an appropriate XAException in the prepare
092: * method.
093: *
094: * @exception StandardException Standard exception policy.
095: **/
096: public int xa_prepare() throws StandardException;
097:
098: /**
099: * rollback the current global transaction.
100: * <p>
101: * The given transaction is roll'ed back and it's history is not
102: * maintained in the transaction table or long term log.
103: * <p>
104: * Once this call has been made all other calls on this controller other
105: * than destroy will throw exceptions.
106: * <p>
107: *
108: * @exception StandardException Standard exception policy.
109: **/
110: public void xa_rollback() throws StandardException;
111: }
|