diff options
5 files changed, 968 insertions, 35 deletions
diff --git a/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/AMQPDtxCoordination.java b/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/AMQPDtxCoordination.java new file mode 100644 index 0000000000..7cef9f1edd --- /dev/null +++ b/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/AMQPDtxCoordination.java @@ -0,0 +1,52 @@ +/* + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * + */ +package org.apache.qpid.nclient.amqp; + +import org.apache.qpid.framing.DtxCoordinationCommitBody; +import org.apache.qpid.framing.DtxCoordinationCommitOkBody; +import org.apache.qpid.framing.DtxCoordinationForgetBody; +import org.apache.qpid.framing.DtxCoordinationForgetOkBody; +import org.apache.qpid.framing.DtxCoordinationGetTimeoutBody; +import org.apache.qpid.framing.DtxCoordinationGetTimeoutOkBody; +import org.apache.qpid.framing.DtxCoordinationPrepareBody; +import org.apache.qpid.framing.DtxCoordinationPrepareOkBody; +import org.apache.qpid.framing.DtxCoordinationRecoverBody; +import org.apache.qpid.framing.DtxCoordinationRecoverOkBody; +import org.apache.qpid.framing.DtxCoordinationRollbackBody; +import org.apache.qpid.framing.DtxCoordinationRollbackOkBody; +import org.apache.qpid.nclient.core.AMQPException; + +public interface AMQPDtxCoordination +{ + public DtxCoordinationCommitOkBody commit(DtxCoordinationCommitBody dtxCoordinationCommitBody) throws AMQPException; + + public DtxCoordinationForgetOkBody forget(DtxCoordinationForgetBody dtxCoordinationForgetBody) throws AMQPException; + + public DtxCoordinationGetTimeoutOkBody getTimeOut(DtxCoordinationGetTimeoutBody dtxCoordinationGetTimeoutBody) throws AMQPException; + + public DtxCoordinationPrepareOkBody prepare(DtxCoordinationPrepareBody dtxCoordinationPrepareBody) throws AMQPException; + + public DtxCoordinationRecoverOkBody recover(DtxCoordinationRecoverBody dtxCoordinationRecoverBody) throws AMQPException; + + public DtxCoordinationRollbackOkBody getTimeOut(DtxCoordinationRollbackBody dtxCoordinationRollbackBody) throws AMQPException; + + //public DtxCoordinationSetTimeoutOkBody getTimeOut(DtxCoordinationSetTimeoutBody dtxCoordinationSetTimeoutBody) throws AMQPException; +} diff --git a/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/AMQPDtxDemarcation.java b/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/AMQPDtxDemarcation.java new file mode 100644 index 0000000000..41f1414205 --- /dev/null +++ b/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/AMQPDtxDemarcation.java @@ -0,0 +1,38 @@ +/* + * + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + * + */ +package org.apache.qpid.nclient.amqp; + +import org.apache.qpid.framing.DtxDemarcationEndBody; +import org.apache.qpid.framing.DtxDemarcationEndOkBody; +import org.apache.qpid.framing.DtxDemarcationSelectBody; +import org.apache.qpid.framing.DtxDemarcationSelectOkBody; +import org.apache.qpid.framing.DtxDemarcationStartBody; +import org.apache.qpid.framing.DtxDemarcationStartOkBody; +import org.apache.qpid.nclient.core.AMQPException; + +public interface AMQPDtxDemarcation +{ + public DtxDemarcationSelectOkBody select(DtxDemarcationSelectBody dtxDemarcationSelectBody) throws AMQPException; + + public DtxDemarcationStartOkBody start(DtxDemarcationStartBody dtxDemarcationStartBody) throws AMQPException; + + public DtxDemarcationEndOkBody end(DtxDemarcationEndBody dtxDemarcationEndBody) throws AMQPException; +} diff --git a/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/qpid/QpidAMQPChannel.java b/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/qpid/QpidAMQPChannel.java index b73aa8e6fa..928780353d 100644 --- a/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/qpid/QpidAMQPChannel.java +++ b/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/qpid/QpidAMQPChannel.java @@ -21,7 +21,6 @@ package org.apache.qpid.nclient.amqp.qpid; -import java.util.concurrent.TimeUnit; import java.util.concurrent.locks.Condition; import java.util.concurrent.locks.Lock; import java.util.concurrent.locks.ReentrantLock; @@ -36,7 +35,6 @@ import org.apache.qpid.framing.ChannelOkBody; import org.apache.qpid.framing.ChannelOpenBody; import org.apache.qpid.framing.ChannelOpenOkBody; import org.apache.qpid.framing.ChannelResumeBody; -import org.apache.qpid.framing.ConnectionCloseBody; import org.apache.qpid.nclient.amqp.AMQPChannel; import org.apache.qpid.nclient.amqp.event.AMQPMethodEvent; import org.apache.qpid.nclient.amqp.event.AMQPMethodListener; diff --git a/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/qpid/QpidAMQPDtxDemarcation.java b/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/qpid/QpidAMQPDtxDemarcation.java new file mode 100644 index 0000000000..a418de7ff6 --- /dev/null +++ b/java/newclient/src/main/java/org/apache/qpid/nclient/amqp/qpid/QpidAMQPDtxDemarcation.java @@ -0,0 +1,62 @@ +package org.apache.qpid.nclient.amqp.qpid; + +import java.util.concurrent.locks.Lock; +import java.util.concurrent.locks.ReentrantLock; + +import org.apache.log4j.Logger; +import org.apache.qpid.framing.DtxDemarcationEndBody; +import org.apache.qpid.framing.DtxDemarcationEndOkBody; +import org.apache.qpid.framing.DtxDemarcationSelectBody; +import org.apache.qpid.framing.DtxDemarcationSelectOkBody; +import org.apache.qpid.framing.DtxDemarcationStartBody; +import org.apache.qpid.framing.DtxDemarcationStartOkBody; +import org.apache.qpid.nclient.amqp.AMQPDtxDemarcation; +import org.apache.qpid.nclient.amqp.state.AMQPState; +import org.apache.qpid.nclient.amqp.state.AMQPStateManager; +import org.apache.qpid.nclient.core.AMQPException; +import org.apache.qpid.nclient.core.Phase; + +public class QpidAMQPDtxDemarcation implements AMQPDtxDemarcation +{ + private static final Logger _logger = Logger.getLogger(QpidAMQPDtxDemarcation.class); + + // the channelId assigned for this channel + private int _channelId; + + private Phase _phase; + + private AMQPState _currentState; + + private AMQPStateManager _stateManager; + + private final AMQPState[] _validCloseStates = new AMQPState[] + { AMQPState.CHANNEL_OPENED, AMQPState.CHANNEL_SUSPEND }; + + private final AMQPState[] _validResumeStates = new AMQPState[] + { AMQPState.CHANNEL_CLOSED, AMQPState.CHANNEL_NOT_OPENED }; + + // The wait period until a server sends a respond + private long _serverTimeOut = 1000; + + private final Lock _lock = new ReentrantLock(); + + + public DtxDemarcationEndOkBody end(DtxDemarcationEndBody dtxDemarcationEndBody) throws AMQPException + { + // TODO Auto-generated method stub + return null; + } + + public DtxDemarcationSelectOkBody select(DtxDemarcationSelectBody dtxDemarcationSelectBody) throws AMQPException + { + // TODO Auto-generated method stub + return null; + } + + public DtxDemarcationStartOkBody start(DtxDemarcationStartBody dtxDemarcationStartBody) throws AMQPException + { + // TODO Auto-generated method stub + return null; + } + +} diff --git a/specs/amqp.0-9.xml b/specs/amqp.0-9.xml index 9d1b488c03..9042185070 100644 --- a/specs/amqp.0-9.xml +++ b/specs/amqp.0-9.xml @@ -4311,72 +4311,855 @@ </method> </class> - <!-- == DTX ============================================================== --> - <class name = "dtx" handler = "channel" index = "100" label = "work with distributed transactions"> +<!-- + ====================================================== + == CONSTANTS + ====================================================== + --> + + <!-- XA constants --> + + <constant name = "xa-rbrollback" value = "1"> <doc> - Distributed transactions provide so-called "2-phase commit". The AMQP distributed - transaction model supports the X-Open XA architecture and other distributed transaction - implementations. The Dtx class assumes that the server has a private communications - channel (not AMQP) to a distributed transaction coordinator. + The rollback was caused by an unspecified reason. + </doc> + </constant> + <constant name = "xa-rbtimeout" value = "2"> + <doc> + A transaction branch took too long. + </doc> + </constant> + <constant name = "xa-heurhaz" value = "3"> + <doc> + The transaction branch may have been heuristically completed. + </doc> + </constant> + <constant name = "xa-heurcom" value = "4"> + <doc> + The transaction branch has been heuristically committed. + </doc> + </constant> + <constant name = "xa-heurrb" value = "5"> + <doc> + The transaction branch has been heuristically rolled back. + </doc> + </constant> + <constant name = "xa-heurmix" value = "6"> + <doc> + The transaction branch has been heuristically committed and rolled back. + </doc> + </constant> + <constant name = "xa-rdonly" value = "7"> + <doc> + The transaction branch was read-only and has been committed. + </doc> + </constant> + <constant name = "xa-ok" value = "8"> + <doc> + Normal execution. + </doc> + </constant> + + +<!-- + ====================================================== + == DOMAIN TYPES + ====================================================== + --> + + <domain name = "Xid" type = "longstr" label = "Transaction branch identifier"> + <doc> + An Xid uniquely identifies a transaction branch. + </doc> + <rule name = "implementation"> + <doc> + Xid contains a format identifier, two length fields and a data field: + format_id long + gtrid_length octet + bqual_length octet + data + + format_id is an implementation specific format identifier + the data field is a sequence of octets of at most 128 bytes containing the txn id and the branch id + gtrid_length field indicates how many bytes of this form the transaction id + bqual_length field indicates how many bytes of this form the branch id + The sum of the two lengths must equal the length of the data field + </doc> + </rule> + </domain> + + <!-- == dtx-demarcation ========================================================== --> + + + <class name = "dtx-demarcation" handler = "channel" index = "100" label = "demarcates distributed transaction branches"> + <doc> + This class is part of the X-Open XA distributed transaction protocol support. It allows a channel to be + selected for use with distributed transactions and the transactional boundaries for work on that channel + to be demarcated. </doc> - <doc type = "grammar"> - dtx = C:SELECT S:SELECT-OK - C:START S:START-OK + dtx-demarcation = C:SELECT S:SELECT-OK *demarcation + + demarcation = C:START S:START-OK C:END S:END-OK </doc> + <chassis name = "server" implement = "MAY" /> <chassis name = "client" implement = "MAY" /> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <rule name = "access-control"> + <doc> + Access-tickets are propagated with XA association methods with the aim of + restricting which users are allowed to control which transactions. + The server MAY restrict transaction association to a particular identity. + </doc> + </rule> - <method name = "select" synchronous = "1" index = "10" label = "select standard transaction mode"> + <rule name = "transactionality"> <doc> - This method sets the channel to use distributed transactions. The client must use - this method at least once on a channel before using the Start method. + Enabling XA transaction support on a channel implies that the server MUST manage transactions demarcated by start-end blocks. That is to say that on this XA-enabled channel, work undergone within transactional blocks is performed on behalf a transaction branch whereas work performed outside of transactional blocks is NOT transactional. </doc> - <chassis name = "server" implement = "MUST" /> + </rule> + + + <!-- - - - SELECT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "select" synchronous = "1" index = "10" label = "select distributed transaction mode"> + <doc> + This method sets the channel to use distributed transactions. The client must use this method at least once on a channel before using XA demarcation operations. + </doc> + <chassis name = "server" implement = "MAY" /> <response name = "select-ok" /> </method> - <method name = "select-ok" synchronous = "1" index = "11" label = "confirm transaction mode"> + <!-- - - - SELECT-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "select-ok" synchronous = "1" index = "11" label = "confirm distributed transaction mode"> <doc> - This method confirms to the client that the channel was successfully set to use - distributed transactions. + This method confirms to the client that the channel was successfully set to use distributed transactions. </doc> - <chassis name = "client" implement = "MUST" /> + <chassis name = "client" implement = "MAY" /> </method> - <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + <!-- - - START - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> - <method name = "start" synchronous = "1" index = "20" - label = "start a new distributed transaction"> + <method name = "start" synchronous = "1" index = "20" label = "Start a transaction branch"> <doc> - This method starts a new distributed transaction. This must be the first method on a - new channel that uses the distributed transaction mode, before any methods that - publish or consume messages. + This method is called when messages should be produced and consumed on behalf a transaction branch identified by xid. </doc> <chassis name = "server" implement = "MAY" /> <response name = "start-ok" /> - <field name = "dtx-identifier" domain = "shortstr" label = "transaction identifier"> + <!-- rules --> + <rule name = "commandInvalid "> + <doc> + If the method is invoked in an improper context (see class grammar) then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + <rule name = "alreadyAssociated"> + <doc> + If neither join nor resume is specified is specified and the transaction branch specified by xid has previously been seen then the server MUST raise a channel exception with reply code 530 (not allowed). + </doc> + </rule> + <rule name = "joinAndresume"> + <doc> + If join and resume are specified then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + + <field name = "ticket" domain = "access-ticket" label = "Access-ticket granted by the server for a specific realm"> + <doc> + Access-ticket granted by the server for a specific realm. + </doc> + <assert check = "notnull" /> + </field> + + <field name = "xid" domain = "Xid" label = "Start any work associated with transaction branch with Xid xid"> <doc> - The distributed transaction key. This identifies the transaction so that the - AMQP server can coordinate with the distributed transaction coordinator. + Specifies the xid of the transaction branch to be started. </doc> <assert check = "notnull" /> + <!-- rules --> + <rule name = "unknownXid"> + <doc> + If Xid is already known by the broker then the server MUST raise a channel exception with reply code 530 (not allowed). + </doc> + </rule> + </field> + + <field name = "join" domain = "bit" label = "Indicate whether this is joining an already associated Xid"> + <doc> + Indicate that the start applies to joining a transaction previously seen. + </doc> + <!-- rules --> + <rule name = "unsupported"> + <doc> + If the broker does not support join the server MUST raise a channel exception with reply code 540 (not implemented). + </doc> + </rule> + <assert check = "notnull" /> + </field> + + <field name = "resume" domain = "bit" label = "Indicate whether this is resuming a suspended transaction branch"> + <doc> + Indicate that the start applies to resuming a suspended transaction branch specified. + </doc> + <assert check = "notnull" /> </field> </method> - <method name = "start-ok" synchronous = "1" index = "21" - label = "confirm the start of a new distributed transaction"> + <!-- - - - START-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "start-ok" synchronous = "1" index = "21" label = "confirm distributed transaction start"> <doc> - This method confirms to the client that the transaction started. Note that if a - start fails, the server raises a channel exception. + This method confirms to the client that the transaction branch is started or specify the error condition. </doc> - <chassis name = "client" implement = "MUST" /> + <chassis name = "client" implement = "MAY" /> + + <field name = "flags" domain = "short" label = "xa-ok or xa-rbrollback"> + <doc> + xa-ok: Normal execution. + xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified reason. + </doc> + <assert check = "notnull" /> + </field> </method> - </class> + + + <!-- - - END - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "end" synchronous = "1" index = "30" label = "End a transaction branch"> + <doc> + This method is called when the work done on behalf a transaction branch finishes or needs to be suspended. + </doc> + <chassis name = "server" implement = "MAY" /> + <response name = "end-ok" /> + + <rule name = "commandInvalid "> + <doc> + If the method is invoked in an improper context (see class grammar) then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + + <rule name = "suspendAndfail"> + <doc> + If suspend and fail are specified then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + + <rule name = "internalError "> + <doc> + If an error occurs in ending the transaction branch then the server MUST raise a channel exception with reply code 541 (internal error) + </doc> + </rule> + + <rule name = "success "> + <doc> + If neither fail nor suspend are specified then the portion of work has completed successfully + </doc> + </rule> + + <field name = "ticket" domain = "access-ticket" label = "Access-ticket granted by the server for a specific realm"> + <doc> + Access-ticket granted by the server for a specific realm. + </doc> + <assert check = "notnull" /> + </field> + + <field name = "xid" domain = "Xid" label = "End any work associated with transaction branch with Xid xid"> + <doc> + Specifies the xid of the transaction branch to be ended. + </doc> + <assert check = "notnull" /> + <!-- rules --> + <rule name = "unknownXid"> + <doc> + If Xid is unknown (the transaction branch has not been started or has already been ended) then the server MUST raise a channel exception with reply code 404 (not found). + </doc> + </rule> + </field> + + <field name = "fail" domain = "bit" label = "Indicate whether the portion of work has failed"> + <doc> + Indicates that the portion of work has failed otherwise the portion of work has completed successfully. + </doc> + <rule name = "failure"> + <doc> + If fail is specified then the transaction should be marked as rollback-only. + </doc> + </rule> + <assert check = "notnull" /> + </field> + + <field name = "suspend" domain = "bit" label = "Indicate that the transaction branch is temporarily suspended in an incomplete state"> + <doc> + Indicates that the transaction branch is temporarily suspended in an incomplete state. + </doc> + <rule name = "resume"> + <doc> + The transaction context is in a suspended state and must be resumed via the start method with resume specified. + </doc> + </rule> + <assert check = "notnull" /> + </field> + + </method> + + <!-- - - - END-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "end-ok" synchronous = "1" index = "31" label = "confirm distributed transaction end"> + <doc> + This method confirms to the client that the transaction branch is ended or specify the error condition. + </doc> + <chassis name = "client" implement = "MAY" /> + + <field name = "flags" domain = "short" label = "xa-ok, xa-rbrollback, xa-rbtimeout"> + <doc> + xa-ok: Normal execution. + xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified reason. + xa-rbtimeout: The work represented by this transaction branch took too long. + </doc> + <assert check = "notnull" /> + </field> + </method> + </class> + + +<!-- == dtx-coordination ========================================================== --> + + + <class name = "dtx-coordination" handler = "channel" index = "105" label = "coordinate transaction outcomes"> + <doc> + This class is part of the X-Open XA distributed transaction protocol support. + It allows the transaction manager to coordinate transaction outcomes. + </doc> + + <doc type = "grammar"> + + dtx-coordination = *coordination + + coordination = command + / outcome + / recovery + + command = C:SET-TIMEOUT S:SET-TIMEOUT-OK + / C:GET-TIMEOUT S:GET-TIMEOUT-OK + + outcome = one-phase-commit + / one-phase-rollback + / two-phase-commit + / two-phase-rollback + + one-phase-commit = C:COMMIT S:COMMIT-OK + + one-phase-rollback = C:ROLLBACK S:ROLLBACK-OK + + two-phase-commit = C:PREPARE S:PREPARE-OK C:COMMIT S:COMMIT-OK + + two-phase-rollback = C:PREPARE S:PREPARE-OK C:ROLLBACK S:ROLLBACK-OK + + recovery = C:RECOVER S:RECOVER-OK *recovery-outcome + + recovery-outcome = one-phase-commit + / one-phase-rollback + / C:FORGET S:FORGET-OK + </doc> + + <chassis name = "server" implement = "MAY" /> + <chassis name = "client" implement = "MAY" /> + + <rule name = "security"> + <doc> + Access-tickets are propagated with XA demarcation methods with the aim of + restricting which users are allowed to control which transactions. + The server MAY restrict transaction coordination to a particular identity. + </doc> + <doc type = "scenario"> + </doc> + </rule> + + + <!-- - - COMMIT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "commit" synchronous = "1" index = "10" label = "Commit the work done on behalf a transaction branch "> + <doc> + This method commits the work associated with xid. Any produced messages are made available and any consumed messages are discarded. + </doc> + <chassis name = "server" implement = "MAY" /> + <response name = "commit-ok" /> + + <rule name = "internalError"> + <doc> + If an error occurs in committing the transaction branch then the server MUST raise a channel exception with reply code 541 (internal error) + </doc> + </rule> + + <rule name = "commandInvalid"> + <doc> + If the method is invoked in an improper context (see class grammar) then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + + <field name = "ticket" domain = "access-ticket" label = "Access-ticket granted by the server for a specific realm"> + <doc> + Access-ticket granted by the server for a specific realm. + </doc> + <assert check = "notnull" /> + </field> + + <field name = "xid" domain = "Xid" label = "Commit the work associated with Xid xid"> + <doc> + Specifies the Xid of the transaction branch to be committed. + </doc> + <assert check = "notnull" /> + <!-- rules --> + <rule name = "unknownXid"> + <doc> + If Xid is unknown (the transaction branch has not been started or has already been ended) then the server MUST raise a channel exception with reply code 404 (not found). + </doc> + </rule> + <rule name = "notdisassociated"> + <doc> + If this method is called when Xid is still associated with a channel then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + </field> + + <field name = "one-phase" domain = "bit" label = "Indicate that one-phase optimization must be used"> + <doc> + When set then one-phase commit optimization is used. + </doc> + <assert check = "notnull" /> + </field> + </method> + + <!-- - - - COMMIT-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "commit-ok" synchronous = "1" index = "11" label = "confirm distributed transaction commit"> + <doc> + This method confirms to the client that the transaction branch is committed or specify the error condition. + </doc> + <chassis name = "client" implement = "MAY" /> + + <field name = "flags" domain = "short" label = "xa-ok, xa-heurhaz, xa-heurcom, xa-heurrb, xa-heurmix, xa-rbrollback"> + <doc> + xa-ok: Normal execution, + xa-heurhaz: Due to some failure, the work done on behalf of the specified transaction branch may have been heuristically completed. + xa-heurcom: Due to a heuristic decision, the work done on behalf of the specified transaction + branch was committed. + xa-heurrb: Due to a heuristic decision, the work done on behalf of the specified transaction + branch was rolled back. + xa-heurmix: Due to a heuristic decision, the work done on behalf of the specified transaction + branch was partially committed and partially rolled back. + xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified reason. + xa-rbtimeout: The work represented by this transaction branch took too long. + </doc> + <assert check = "notnull" /> + </field> + </method> + + + <!-- - - FORGET - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "forget" synchronous = "1" index = "20" label = "Discard knowledge of a heuristically-completed transaction branch"> + <doc> + This method is called to forget about a heuristically completed transaction branch. + </doc> + <chassis name = "server" implement = "MAY" /> + <response name = "forget-ok" /> + + <rule name = "internalError "> + <doc> + If an error occurs in forgetting the transaction branch then the server MUST raise a channel exception with reply code 541 (internal error) + </doc> + </rule> + + <rule name = "commandInvalid "> + <doc> + If the method is invoked in an improper context (see class grammar) then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + + <field name = "ticket" domain = "access-ticket" label = "Access-ticket granted by the server for a specific realm"> + <doc> + Access-ticket granted by the server for a specific realm. + </doc> + <assert check = "notnull" /> + </field> + + <field name = "xid" domain = "Xid" label = "Erase RM its knowledge of Xid xid"> + <doc> + Specifies the xid of the transaction branch to be forgotten. + </doc> + <assert check = "notnull" /> + <!-- rules --> + <rule name = "unknownXid"> + <doc> + If Xid is unknown (the transaction branch has not been started or has already been ended) then the server MUST raise a channel exception with reply code 404 (not found). + </doc> + </rule> + <rule name = "notdisassociated"> + <doc> + If this method is called when Xid is still associated with a channel then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + </field> + </method> + + <!-- - - - FORGET-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "forget-ok" synchronous = "1" index = "21" label = "Confirm distributed transaction forget"> + <doc> + This method confirms to the client that the transaction branch is forgotten or specify the error condition. + </doc> + <chassis name = "client" implement = "MAY" /> + </method> + + <!-- - - - get-Timeout - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "get-timeout" synchronous = "1" index = "30" label = "Obtain the transaction timeout value in seconds"> + <doc> + This method obtains the current transaction timeout value in seconds. + If setTimeout was not used prior to invoking this method, the return value is the default timeout; otherwise, the value used in the previous setTimeout call is returned. + </doc> + <chassis name = "server" implement = "MAY" /> + <response name = "get-timeout-ok" /> + + + <field name = "xid" domain = "Xid" label = "Xid of the branch to get the timeout value"> + <doc> + Specifies the Xid of the transaction branch for getting the timeout. + </doc> + <assert check = "notnull" /> + <!-- rules --> + <rule name = "unknownXid"> + <doc> + If Xid is unknown (the transaction branch has not been started or has already been ended) then the server MUST raise a channel exception with reply code 404 (not found). + </doc> + </rule> + </field> + + <rule name = "internalError "> + <doc> + If an error occurs in setting the transaction timeout then the server MUST raise a channel exception with reply code 541 (internal error) + </doc> + </rule> + </method> + + <!-- - - - get-Timeout-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "get-timeout-ok" synchronous = "1" index = "31" label = "Return transaction timeout"> + <doc> + This method returns the current transaction timeout value in seconds. + </doc> + <chassis name = "client" implement = "MAY" /> + + <field name = "timeout" domain = "long" label = "The current transaction timeout value"> + <doc> + The current transaction timeout value in seconds. + </doc> + <assert check = "notnull" /> + </field> + </method> + + <!-- - - PREPARE - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "prepare" synchronous = "1" index = "40" label = "Ask to prepare a transaction branch"> + <doc> + This method prepares for commitment any message produced or consumed on behalf of xid. + </doc> + + <rule name = "internalError"> + <doc> + If an error occurs in preparing the transaction branch then the server MUST raise a channel exception with reply code 541 (internal error). The specified Xid may or may not have been prepared. + </doc> + </rule> + + <rule name = "commandInvalid"> + <doc> + If the method is invoked in an improper context (see class grammar) then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + + <rule name = "obligation1"> + <doc> + Once this method successfully returns it is guaranteed that the transaction branch may be either + committed or rolled back regardless of failures. + </doc> + </rule> + + <rule name = "obligation2"> + <doc> + The knowledge of xid cannot be erased before commit or rollback complete the branch. + </doc> + </rule> + + <chassis name = "server" implement = "MAY" /> + <response name = "prepare-ok" /> + + <field name = "ticket" domain = "access-ticket" label = "Access-ticket granted by the server for a specific realm"> + <doc> + Access-ticket granted by the server for a specific realm. + </doc> + <assert check = "notnull" /> + </field> + + <field name = "xid" domain = "Xid" label = "Prepare for commitment any work associated with Xid xid"> + <doc> + Specifies the Xid of the transaction branch that can be prepared. + </doc> + <assert check = "notnull" /> + <!-- rules --> + <rule name = "unknownXid"> + <doc> + If Xid is unknown (the transaction branch has not been started or has already been ended) then the server MUST raise a channel exception with reply code 404 (not found). + </doc> + </rule> + <rule name = "notdisassociated"> + <doc> + If this method is called when Xid is still associated with a channel then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + </field> + </method> + + + <!-- - - - PREPARE-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "prepare-ok" synchronous = "1" index = "41" label = "confirm distributed transaction prepare"> + <doc> + This method confirms to the client that the transaction branch is prepared or specify the error condition. + </doc> + <chassis name = "client" implement = "MAY" /> + + <field name = "flags" domain = "short" label = "xa-ok, xa-rdonly, xa-rbrollback, xa-rbtimeout"> + <doc> + xa-ok: Normal execution. + xa-rdonly: The transaction branch was read-only and has been committed. + xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified reason. + xa-rbtimeout: The work represented by this transaction branch took too long. + </doc> + <assert check = "notnull" /> + </field> + </method> + + + <!-- - - RECOVER - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "recover" synchronous = "1" index = "50" label = "Get a list of Xids the RM has prepared or heuristically completed"> + <doc> + This method is called to obtain a list of transaction branches that are in a + prepared or heuristically completed state. + </doc> + + <rule name = "internalError "> + <doc> + If an error occurs in recovering then the server MUST raise a channel exception with reply code 541 (internal error) + </doc> + </rule> + + <rule name = "startEnd"> + <doc> + If this endscan is used in conjunction with startscan then a single call starts and then ends a scan. + </doc> + </rule> + + <rule name = "mustBeStarted"> + <doc> + If none of endscan and startscan are set then a recovery scan must already be started otherwise the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + + <chassis name = "server" implement = "MAY" /> + <response name = "recover-ok" /> + + <field name = "ticket" domain = "access-ticket" label = "Access-ticket granted by the server for a specific realm"> + <doc> + Access-ticket granted by the server for a specific realm. + </doc> + <assert check = "notnull" /> + </field> + + <field name = "startscan" domain = "bit" label = "Indicates that recovery scan should start"> + <doc> + Indicates that recovery scan should start. + </doc> + <rule name = "recoveryAlreadyOpen"> + <doc> + If a recovery scan is already open, the effect is as if the recovery scan were ended and then restarted. + </doc> + </rule> + <assert check = "notnull" /> + </field> + + <field name = "endscan" domain = "long" label = "indicates that the recovery scan should end after returning the Xids"> + <doc> + Indicates that the recovery scan should end after returning the Xids. + </doc> + <assert check = "notnull" /> + </field> + </method> + + <!-- - - RECOVER-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "recover-ok" synchronous = "1" index = "51" label = "list of Xids to be recovered"> + <doc> + Returns to the client a table of transaction Xids that are in a prepared or heuristically completed state. + </doc> + + <chassis name = "server" implement = "MAY" /> + + <field name = "xids" domain = "table" label = "Table of xids to be recovered"> + <doc> + table containing transaction Xids that are in a prepared or heuristically completed state. + </doc> + <assert check = "notnull" /> + </field> + </method> + + <!-- - - ROLLBACK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "rollback" synchronous = "1" index = "60" label = "Rollback a transaction branch"> + <doc> + This method rolls back the work associated with xid. Any produced messages are discarded + and any consumed messages are re-enqueued. + </doc> + + <rule name = "internalError"> + <doc> + If an error occurs in rolling back the transaction branch then the server MUST raise a channel exception with reply code 541 (internal error) + </doc> + </rule> + + <rule name = "commandInvalid"> + <doc> + If the method is invoked in an improper context (see class grammar) then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + + <chassis name = "server" implement = "MAY" /> + <response name = "rollback-ok" /> + + <field name = "ticket" domain = "access-ticket" label = "Access-ticket granted by the server for a specific realm"> + <doc> + Access-ticket granted by the server for a specific realm. + </doc> + <assert check = "notnull" /> + </field> + + <field name = "xid" domain = "Xid" label = "Rollback any work associated with Xid xid"> + <doc> + Specifies the Xid of the transaction branch that can be rolled back. + </doc> + <assert check = "notnull" /> + <!-- rules --> + <rule name = "unknownXid"> + <doc> + If Xid is unknown (the transaction branch has not been started or has already been ended) then the server MUST raise a channel exception with reply code 404 (not found). + </doc> + </rule> + <rule name = "notdisassociated"> + <doc> + If this method is called when Xid is still associated with a channel then the server MUST raise a channel exception with reply code 503 (command invalid) + </doc> + </rule> + </field> + </method> + + <!-- - - - ROLLBACK-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "rollback-ok" synchronous = "1" index = "61" label = "confirm distributed transaction rollback"> + <doc> + This method confirms to the client that the transaction branch is rolled back or specify the error condition. + </doc> + <chassis name = "client" implement = "MAY" /> + + <field name = "flags" domain = "short" label = "xa-ok, xa-heurhaz, xa-heurcom, xa-heurrb, xa-heurmix, xa-rbrollback"> + <doc> + xa-ok: Normal execution, + xa-heurhaz: Due to some failure, the work done on behalf of the specified transaction branch may have been heuristically completed. + xa-heurcom: Due to a heuristic decision, the work done on behalf of the specified transaction + branch was committed. + xa-heurrb: Due to a heuristic decision, the work done on behalf of the specified transaction + branch was rolled back. + xa-heurmix: Due to a heuristic decision, the work done on behalf of the specified transaction + branch was partially committed and partially rolled back. + xa-rbrollback: The broker marked the transaction branch rollback-only for an unspecified reason. + xa-rbtimeout: The work represented by this transaction branch took too long. + </doc> + <assert check = "notnull" /> + </field> + </method> + + + + <!-- - - SETTIMEOUT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "set-timeout" synchronous = "1" index = "70" label = "Set the transaction timeout value"> + <doc> + Sets the specified transaction branch timeout value in seconds. + </doc> + + <rule name = "internalError "> + <doc> + If an error occurs in setting the transaction timeout then the server MUST raise a channel exception with reply code 541 (internal error) + </doc> + </rule> + + <rule name = "effective"> + <doc> + Once set, this timeout value is effective until this method is reinvoked with a different value. + </doc> + </rule> + + <rule name = "reset"> + <doc> + A value of zero resets the timeout value to the default value. + </doc> + </rule> + + <chassis name = "server" implement = "MAY" /> + <response name = "set-timeout-ok" /> + + <field name = "ticket" domain = "access-ticket" label = "Access-ticket granted by the server for a specific realm"> + <doc> + Access-ticket granted by the server for a specific realm. + </doc> + <assert check = "notnull" /> + </field> + + <field name = "xid" domain = "Xid" label = "Xid of the branch to set the timeout value"> + <doc> + Specifies the Xid of the transaction branch for setting the timeout. + </doc> + <assert check = "notnull" /> + <!-- rules --> + <rule name = "unknownXid"> + <doc> + If Xid is unknown (the transaction branch has not been started or has already been ended) then the server MUST raise a channel exception with reply code 404 (not found). + </doc> + </rule> + </field> + + <field name = "timeout" domain = "long" label = "The transaction timeout value in seconds"> + <doc> + The transaction timeout value in seconds. + </doc> + <assert check = "notnull" /> + </field> + </method> + + <!-- - - - SETTIMEOUT-OK - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <method name = "select-ok" synchronous = "1" index = "71" label = "confirm timeout set"> + <doc> + This method confirms that the timeout has been set. + </doc> + <chassis name = "client" implement = "MAY" /> + </method> + </class> + + <!-- == TUNNEL =========================================================== --> |