--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.access.xa.XAResourceManager\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.store.access.xa;\r
+\r
+import org.apache.derby.iapi.services.context.ContextManager;\r
+\r
+import org.apache.derby.iapi.error.StandardException; \r
+\r
+import javax.transaction.xa.Xid;\r
+\r
+/**\r
+\r
+This interface allows access to commit,prepare,abort global transactions\r
+as part of a two phase commit protocol. These interfaces have been chosen\r
+to be exact implementations required to implement the XAResource interfaces\r
+as part of the JTA standard extension.\r
+<P>\r
+It is expected that the following interfaces are only used during the \r
+recovery portion of 2 phase commit, when the transaction manager is\r
+cleaning up after a runtime crash - it is expected that no current context\r
+managers exist for the Xid's being operated on. The "online" two phase commit\r
+protocol will be implemented by calls directly on a TransactionController.\r
+<P>\r
+The XAResource interface is a Java mapping of the industry standard XA resource\r
+manager interface. Please refer to: X/Open CAE Specification - Distributed \r
+Transaction Processing: The XA Specification, X/Open Document No. XO/CAE/91/300\r
+or ISBN 1 872630 24 3.\r
+<P>\r
+\r
+**/\r
+\r
+public interface XAResourceManager\r
+{\r
+ /**************************************************************************\r
+ * Public Methods of This class:\r
+ **************************************************************************\r
+ */\r
+\r
+ /**\r
+ * This method is called to commit the global transaction specified by xid.\r
+ * <p>\r
+ * RESOLVE - how do we map to the "right" XAExceptions.\r
+ * <p>\r
+ *\r
+ * @param cm The ContextManager returned from the find() call.\r
+ * @param xid A global transaction identifier.\r
+ * @param onePhase If true, the resource manager should use a one-phase\r
+ * commit protocol to commit the work done on behalf of \r
+ * xid.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public void commit(\r
+ ContextManager cm,\r
+ Xid xid,\r
+ boolean onePhase)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Find the given Xid in the transaction table.\r
+ * <p>\r
+ * This routine is used to find a in-doubt transaction from the list\r
+ * of Xid's returned from the recover() routine. \r
+ * <p>\r
+ * In the current implementation it is up to the calling routine\r
+ * to make the returned ContextManager the "current" ContextManager\r
+ * before calls to commit,abort, or forget. The caller is responsible\r
+ * for error handling, ie. calling cleanupOnError() on the correct\r
+ * ContextManager.\r
+ * <p>\r
+ * If the Xid is not in the system, "null" is returned.\r
+ * RESOLVE - find out from sku if she wants a exception instead?\r
+ * <p>\r
+ *\r
+ * @param xid A global transaction identifier.\r
+ **/\r
+ public ContextManager find(\r
+ Xid xid);\r
+\r
+ /**\r
+ * This method is called to remove the given transaction \r
+ * from the transaction table/log.\r
+ * <p>\r
+ * Used to let the store remove all record from log and transaction\r
+ * table of the given transaction. This should only be used to \r
+ * clean up heuristically completed transactions, otherwise commit or\r
+ * abort should be used to act on other transactions.\r
+ * <p>\r
+ * If forget() is called on a transaction which has not be heuristically\r
+ * completed then it will throw an exception:\r
+ * SQLState.STORE_XA_PROTOCOL_VIOLATION.\r
+ *\r
+ * @param cm The ContextManager returned from the find() call.\r
+ * @param xid A global transaction identifier.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ *\r
+ **/\r
+ public void forget(\r
+ ContextManager cm,\r
+ Xid xid)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * This method is called to obtain a list of prepared transactions.\r
+ * <p>\r
+ * This call returns a complete list of global transactions which are \r
+ * either prepared or heuristically complete.\r
+ * <p>\r
+ * The XAResource interface expects a scan type interface, but our\r
+ * implementation only returns a complete list of transactions. So to\r
+ * simulate the scan the following state is maintained. If TMSTARTSCAN\r
+ * is specified the complete list is returned. If recover is called with\r
+ * TMNOFLAGS is ever called a 0 length array is returned. \r
+ *\r
+ * @return Return a array with 0 or more Xid's which are currently in\r
+ * prepared or heuristically completed state. If an error occurs\r
+ * during the operation, an appropriate error is thrown.\r
+ *\r
+ * @param flags combination of the following flags \r
+ * XAResource.{TMSTARTRSCAN,TMENDRSCAN,TMNOFLAGS}. \r
+ * TMNOFLAGS must be used when no other flags are used.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public Xid[] recover(int flags)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * rollback the transaction identified by Xid.\r
+ * <p>\r
+ * The given transaction is roll'ed back and it's history is not\r
+ * maintained in the transaction table or long term log.\r
+ * <p>\r
+ *\r
+ * @param cm The ContextManager returned from the find() call.\r
+ * @param xid A global transaction identifier.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ public void rollback(\r
+ ContextManager cm,\r
+ Xid xid)\r
+ throws StandardException;\r
+}\r