Home » db-derby-10.5.3.0 » org.apache.derby.iapi.store.access.xa » [javadoc | source]

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

Home » db-derby-10.5.3.0 » org.apache.derby.iapi.store.access.xa » [javadoc | source]