// -------------------------------------------------------------
// OpenORB OTS
// -------------------------------------------------------------

#include <CosTransactions.idl>

#pragma prefix "org"

/**
 * This module provides implementation specific interfaces and data required by openORB OTS.
 *
 * @author Distributed Object Group
 * @version 2.0
 */
module openorb
{
    /**
     * This module provides additional interfaces and data types required by openORB OTS.
     */
    module ots
    {
        /**
         * The openORB OTS ID ( This is used into Transaction Id and XA XID )
         */
        const long openORB_OTS = 1000;

        typedef octet octetTab[ 10 ];

        /**
         * This structure is contained into the implementation specific data of the
         * propagation context.
         */
        struct SpecificData
        {
            /**
             * The magic to recognize OpenORB OTS Implementation specific data, its value is
             * O P E N O R B O T S 
             */
            octetTab magic;

            /**
             * openORB Implementation specific data major version ( current value is 2 )
             */
            short version_major;

            /**
             * openORB Implementation specific data minor version ( current value is 0 )
             */
            short version_minor;

            /**
             * The transaction control object reference.
             */
            CosTransactions::Control ctrl;
        };

        typedef sequence<octet> OctetSeq;

        /**
         * openORB XID Format
         */
        struct XID
        {
            /**
             * openORB Format ID
             */
            long format_id;

            /**
             * Global Transaction Identifier
             */
            OctetSeq gtrid;

            /**
             * Branch Qualifier Identifier
             */
            OctetSeq bqual;
        };

        /**
         * This native description is used to provide the local object SessionManager. In Java,
         * its value is java.sql.Connection
         */
        native ConnectionHandle;

        /**
         * This native description is used into the updateConnection operation of the local object
         * SessionManager.In Java, its value is javax.sql.XAConnection
         */
        native XAConnectionHandle;

        /**
         * This local object manages connection to a database. The user must use it in order to propagate
         * a transaction from the OTS to the database.
         * To get access to this object, the user must apply the 'TransactionSessionManager' value to
         * the resolve_initial_references operation.
         */
        local interface SessionManager
        {
            /**
             * Return a connection to a database. This connection can be used to make SQL statements.
             * The user must get one connection for one thread transaction. But several serialized 
             * transactions can shared the same connection.
             *
             * Thus, if you have concurrent access ( several transactions at the same time ), you
             * must use a distint connection for each transaction.
             *
             * @param user_name the user name to get a connection to the database.
             * @param user_password the user password to get a connection to the database.
             * @param profile_name the database profile ( this profile name is used to get information from
             * the openORB OTS configuration file, i.e. JDBC driver and so on... )
             * @return a connection handle to access to the database
             */
            ConnectionHandle getConnection( in string user_name, in string user_password, in string profile_name );

            /**
             * This operation is automatically called by the openORB OTS to free all connections involved into
             * a transaction when it completed.
             *
             * In a normal usage, the user will not use this operation.
             */
            void freeConnections( in CosTransactions::Coordinator coordinator );

            /**
             * This operation is automatically called by the openORB OTS to change a connection state.
             *
             * In a normal usage, the user will not use this operation.
             */
            void updateConnection( in XAConnectionHandle connection, in CosTransactions::Coordinator coordinator );
        };

        /**
         * To manage transactions, a user has to register a ManagerCallback object to the OTS manager.
         * By this way, the user manager will be notified when transactions begin, commit or rollback.
         */
        interface ManagerCallback
        {
            /**
             * This operation is automatically called by this OTS, when a new transaction has been
             * created.
             *
             * @param control the new available control to manage this transaction
             * @param id the transaction XID
             */
            oneway void transaction_created( in CosTransactions::Control control, in XID id );

            /**
             * This operation is automatically called by this OTS, when a new transaction has been
             * committed.
             *
             * @param id the transaction XID
             */
            oneway void transaction_committed( in XID id );

            /**
             * This operation is automatically called by this OTS, when a new transaction has been
             * rolledback.
             *
             * @param id the transaction XID
             */
            oneway void transaction_rolledback( in XID id );

            /**
             * Heuristic kind for heuristic reports
             */
            enum HeuristicKind
            {
                commit, rollback, mixed, hazard
            };

            /**
             * This operation is automatically called by this OTS, when a new transaction has been
             * committed or rolledback with an heuristic.
             *
             * @param id the transaction XID
             */
            oneway void transaction_heuristic( in XID id, in HeuristicKind heuristic );
        };

        /**
         * This interface is provided by openORB OTS to manage transactions.
         */
        interface Manager
        {
            typedef sequence< CosTransactions::Control > Controls;

            /**
             * Return all the controls for current transactions. By this way, it is possible to
             * get access to the coordinator or the terminator to manage transacton management.
             */
            Controls currentTransactions( in ManagerCallback callback );
        };
    };
};
