/*
 * 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.
 */

#ifndef _CMS_XARESOURCE_H_
#define _CMS_XARESOURCE_H_

#include <cms/Config.h>

#include <cms/Xid.h>
#include <cms/XAException.h>

namespace cms {

    /**
     * The XAResource interface is a CMS mapping of the industry standard XA interface based
     * on the X/Open CAE Specification (Distributed Transaction Processing: The XA Specification).
     *
     * The XA interface defines the contract between a Resource Manager and a Transaction Manager
     * in a distributed transaction processing (DTP) environment. A CMS provider implements this
     * interface to support the association between a global transaction and a message broker
     * connection.
     *
     * The XAResource is exposed to CMS client so that they can proxy calls from the Transaction
     * Manager API of their choosing to the CMS provider.  The CMS provider should behave and a
     * standard XA Resource Manager its up to the client however to transmit the Transaction
     * Manager's calls to the CMS provider through this interface.
     *
     * @since 2.3
     */
    class CMS_API XAResource {
    public:

        /**
         * Flag to end a recovery scan
         */
        static const int TMENDRSCAN;

        /**
         * Flag to indicate that the caller is dissociation from a transaction
         * branch and that it should be marked rollback only
         */
        static const int TMFAIL;

        /**
         * Flag to indicate that the caller is joining sn existing transaction
         * branch.
         */
        static const int TMJOIN;

        /**
         * Flag that indicates that no flags options are selected. (ie a null flag)
         */
        static const int TMNOFLAGS;

        /**
         * Flag that indicates the caller is using one-phase commit optimization
         */
        static const int TMONEPHASE;

        /**
         * Flag that indicates the caller is resuming association with a suspended
         * transaction branch
         */
        static const int TMRESUME;

        /**
         * Flag that indicates the start of a recovery scan
         */
        static const int TMSTARTRSCAN;

        /**
         * Flag that indicates the caller is dissociating from a transaction branch
         */
        static const int TMSUCCESS;

        /**
         * Flag that indicates that the caller is suspending (not terminating) its
         * association with a transaction branch.
         */
        static const int TMSUSPEND;

        /**
         * Flag that indicates that transaction work has been read only and has been
         * committed normally
         */
        static const int XA_RDONLY;

        /**
         * Flag that indicates that transaction work has been Prepared normally
         */
        static const int XA_OK;

    public:

        virtual ~XAResource();

        /**
         * Commits a global transaction.
         *
         * @param xid
         *       the XID which identifies the global transaction.
         * @param onePhase
         *       true if the resource manager should use a one-phase commit
         *       protocol to commit the transaction.
         *
         * @throws XAException
         *       if an error occurred.
         *       <p>
         *       Possible errors are identified by the errorcode in the
         *       XAException and include: XA_HEURHAZ, XA_HEURCOM, XA_HEURRB,
         *       XA_HEURMIX, XAER_RMERR, XAER_RMFAIL, XAER_NOTA, XAER_INVAL,
         *       or XAER_PROTO. In addition, one of the XA_RB* errors can
         *       occur if the transaction was not committed and onePhase
         *       was set to true. On completion of this method, the Resource
         *       Manager has rolled back the transaction and released
         *       resources held by the transaction.
         */
        virtual void commit(const Xid* xid, bool onePhase) = 0;

        /**
         * Ends the work done for a transaction branch. The Resource Manager
         * disconnects the XA resource from the transaction branch and allows the
         * transaction to complete.
         *
         * @param xid
         *      the XID which identifies the global transaction. Should have
         *      previously been used as the parameter to a start.
         *      method.
         * @param flags
         *      a flags integer - one of: XAResource::TMSUCCESS,
         *      XAResource::TMFAIL, or XAResource::TMSUSPEND.
         *      <p>
         *      TMSUCCESS means that this section of work completed
         *      successfully.
         *      <p>
         *      TMFAIL means that this section of work failed. The Resource
         *      Manager can mark the transaction for rollback only.
         *      <p>
         *      TMSUSPEND means that this section of work is suspended and not
         *      yet complete. The associated transaction context is also
         *      suspended and must be restarted with a call to
         *      {@link #start(Xid, int)} with the TMRESUME
         *      flag.
         *
         * @throws XAException
         *      if an error occurs. Possible error identified in the
         *      errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_NOTA,
         *      XAER_INVAL, XAER_PROTO, or XA_RB*.
         */
        virtual void end(const Xid* xid, int flags) = 0;

        /**
         * Informs the Resource Manager that it can forget about a specified
         * transaction branch.
         *
         * @param xid
         *      the XID which identifies the global transaction.
         *
         * @throws XAException
         *      if an error occurs. Possible error identified in the
         *      errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_NOTA,
         *      XAER_INVAL, or XAER_PROTO.
         */
        virtual void forget(const Xid* xid) = 0;

        /**
         * Gets the transaction timeout value for this XAResource. The default
         * timeout value is the default timeout value set for the Resource Manager.
         *
         * @return the transaction timeout value for this XAResource in seconds.
         *
         * @throws XAException
         *      if an error occurs. Possible error identified in the
         *      errorcode include: XAER_RMERR and XAER_RMFAIL.
         */
        virtual int getTransactionTimeout() const = 0;

        /**
         * Returns true if the ResourceManager for this XAResource is the same as
         * the Resource Manager for a supplied XAResource.
         *
         * @param theXAResource
         *      an XAResource object
         * @return true if the Resource Manager for this XAResource is the same as
         *         the Resource Manager for <code>theXAResource</code>.
         * @throws XAException
         *      if an error occurs. Possible error identified in the
         *      errorcode include: XAER_RMERR and XAER_RMFAIL.
         */
        virtual bool isSameRM(const XAResource* theXAResource) = 0;

        /**
         * Requests the Resource manager to prepare to commit a specified
         * transaction.
         *
         * @param xid
         *      the XID which identifies the global transaction.
         *
         * @return an integer: XA_RDONLY or XA_OK. XA_OK implies that the
         *         transaction work has been prepared normally, XA_RDONLY implies
         *         that the transaction branch is read only and has been committed.
         *         If there is a failure which requires a rollback, an XAException
         *         is raised.
         *
         * @throws XAException
         *      if an error occurs. Possible error identified in the
         *      errorcode include: XA_RB*, XAER_RMERR, XAER_RMFAIL,
         *      XAER_NOTA, XAER_INVAL, or XAER_PROTO.
         */
        virtual int prepare(const Xid* xid) = 0;

        /**
         * Get a list of prepared transaction branches.
         *
         * Typically used by a transaction manager during recovery to find
         * transaction branches that are in prepared or heuristically completed
         * states.
         *
         * @param flag
         *      an integer. Must be one of: XAResource::TMSTARTRSCAN,
         *      XAResource::TMENDRSCAN, XAResource::TMNOFLAGS.
         *
         * @return an array of zero or more XIDs identifying the transaction
         *         branches in the prepared or heuristically completed states.
         *
         * @throws XAException
         *      if an error occurs. Possible error identified in the
         *      errorcode include: XAER_RMERR, XAER_RMFAIL, XAER_INVAL, and
         *      XAER_PROTO.
         */
        virtual int recover(int flag, Xid** recovered) = 0;

        /**
         * Requests the Resource Manager to rollback a specified transaction branch.
         *
         * @param xid
         *      the XID which identifies the transaction branch.
         *
         * @throws XAException
         *      if an error occurs.
         */
        virtual void rollback(const Xid* xid) = 0;

        /**
         * Sets the transaction timeout value for this XAResource. If the value is
         * set to 0, the default timeout value for the Resource Manager is used.
         *
         * @param seconds
         *      the new Timeout value in seconds.
         *
         * @return true if the transaction timeout value has been updated, false
         *         otherwise.
         *
         * @throws XAException
         *      if an error occurs. Possible error identified in the
         *      errorcode include: XAER_RMERR, XAER_RMFAIL, or XAER_INVAL.
         */
        virtual bool setTransactionTimeout(int seconds) = 0;

        /**
         * Starts work for a specified transaction branch.
         *
         * @param xid
         *      the XID which identifies the transaction branch.
         * @param flags
         *      an integer. Must be one of XAResource::TMNOFLAGS,
         *      XAResource::TMJOIN, or XAResource::TMRESUME.
         *      <p>
         *      TMJOIN implies that the start applies to joining a transaction
         *      previously passed to the Resource Manager.
         *      <p>
         *      TMRESUME implies that the start applies to a suspended
         *      transaction that should be restarted.
         *      <p>
         *      If TMNOFLAGS is specified, then if the transaction has been
         *      previously seen by the Resource Manager, an XAException is
         *      raised with the code XAER_DUPID.
         *
         * @throws XAException
         *      if an error occurs. Possible error identified in the
         *      errorcode include: XA_RB*, XAER_RMERR, XAER_RMFAIL,
         *      XAER_DUPID, XAER_OUTSIDE, XAER_NOTA, XAER_INVAL, or
         *      XAER_PROTO.
         */
        virtual void start(const Xid* xid, int flags) = 0;

    };

}

#endif /* _CMS_XARESOURCE_H_ */