/*
 * JBoss, Home of Professional Open Source
 * Copyright 2006, JBoss Inc., and individual contributors as indicated
 * by the @authors tag.  All rights reserved. 
 * See the copyright.txt in the distribution for a full listing 
 * of individual contributors.
 * This copyrighted material is made available to anyone wishing to use,
 * modify, copy, or redistribute it subject to the terms and conditions
 * of the GNU General Public License, v. 2.0.
 * This program is distributed in the hope that it will be useful, but WITHOUT A 
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
 * PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License,
 * v. 2.0 along with this distribution; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 
 * MA  02110-1301, USA.
 * 
 * (C) 2005-2006,
 * @author JBoss Inc.
 */
/*
 * Copyright (C) 1999-2001 by HP Bluestone Software, Inc. All rights Reserved.
 *
 * HP Arjuna Labs,
 * Newcastle upon Tyne,
 * Tyne and Wear,
 * UK.
 *
 * $Id: CosTransactions.idl 2342 2006-03-30 13:06:17Z  $
 */

#ifndef COSTRANSACTIONS_IDL_
#define COSTRANSACTIONS_IDL_

#include <orb.idl>

#ifndef NO_PRAGMA_SUPPORT
#pragma prefix "omg.org"
#endif

#ifdef HAVE_JAVAPACKAGE
#pragma javaPackage "org.omg"
#endif

//
// If Draft3 is defined includes most (but not all of the features
// of the revised OTS spec at Draft3 (Nov 22, 96).
// Those missing generally need support from other services or the ORB
// itself
//

/*
 * We provide minimal support for drafts before 3.
 * Because some systems (e.g., Orbix) do their own parsing and
 * can't cope with '#if defined' statements, we have some "extended"
 * conditional compilation lines!
 */

module CosTransactions
{
    enum Status { StatusActive, StatusMarkedRollback, StatusPrepared,
		  StatusCommitted, StatusRolledBack, StatusUnknown,
		  StatusPreparing, StatusCommitting, StatusRollingBack,
		  StatusNoTransaction };

    enum Vote { VoteCommit, VoteRollback, VoteReadOnly };

#ifndef ORB_OTS_SUPPORT
    // Standard exceptions - here until the Orb supports them
    
    exception TransactionRequired {};
    exception TransactionRolledBack {};
    exception InvalidTransaction {};
#endif

    exception WrongTransaction {};

    // Heuristic exceptions

    exception HeuristicRollback {};
    exception HeuristicCommit {};
    exception HeuristicMixed {};
    exception HeuristicHazard {};

    // Other transaction related exceptions
    
    exception SubtransactionsUnavailable {};
    exception NotSubtransaction {};
    exception Inactive {};
    exception NotPrepared {};
    exception NoTransaction {};
    exception InvalidControl {};
    exception Unavailable {};
    exception SynchronizationUnavailable {};

    // Forward references for later interfaces
	
    interface Control;
    interface Terminator;
    interface Coordinator;
    interface Resource;
    interface RecoveryCoordinator;
    interface SubtransactionAwareResource;
    interface TransactionFactory;
    interface TransactionalObject;
    interface Current;
    interface Synchronization;
    
    // Formally part of CosTSInteroperation

#ifdef NO_ANONYMOUS_SEQUENCES
    typedef sequence<octet> tranID;
#endif

    struct otid_t
    {
	long formatID;  /* format identifier. 0 is OSI TP */
	long bqual_length;
#ifndef NO_ANONYMOUS_SEQUENCES	
	sequence <octet> tid;
#else
	tranID tid;
#endif
    };

    struct TransIdentity
    {
	Coordinator coord;
	Terminator term;
	otid_t otid;
    };

#ifdef NO_ANONYMOUS_SEQUENCES
    typedef sequence<TransIdentity> hierarchy;
#endif

    struct PropagationContext
    {
	unsigned long timeout;
#ifdef LEGAL_IDL
	TransIdentity currentTransaction;
#else
	TransIdentity current;
#endif
#ifndef NO_ANONYMOUS_SEQUENCES
	sequence <TransIdentity> parents;
#else
	hierarchy parents;
#endif
	any implementation_specific_data;
    };
    
#ifdef ORB_CURRENT_SUPPORT    
    interface Current : CORBA::Current
#else
    interface Current
#endif
    {
	void begin () raises (SubtransactionsUnavailable);
	void commit (in boolean report_heuristics) raises (NoTransaction, HeuristicMixed, HeuristicHazard);
	void rollback () raises (NoTransaction);
	void rollback_only () raises (NoTransaction);

	Status get_status ();
	string get_transaction_name ();
	void set_timeout (in unsigned long seconds);

	Control get_control ();
	Control suspend ();
	void resume (in Control which) raises (InvalidControl);
    };
    
    interface TransactionFactory
    {
	Control create (in unsigned long time_out);
	Control recreate (in PropagationContext ctx);
    };

    interface Control
    {
	Terminator get_terminator () raises (Unavailable);
	Coordinator get_coordinator () raises (Unavailable);
    };

    interface Terminator
    {
	void commit (in boolean report_heuristics) raises (HeuristicMixed, HeuristicHazard);
	void rollback ();
    };

    interface Coordinator
    {
	Status get_status ();
	Status get_parent_status ();
	Status get_top_level_status ();
    
	boolean is_same_transaction (in Coordinator tc);
	boolean is_related_transaction (in Coordinator tc);
	boolean is_ancestor_transaction (in Coordinator tc);
	boolean is_descendant_transaction (in Coordinator tc);
	boolean is_top_level_transaction ();

	unsigned long hash_transaction ();
	unsigned long hash_top_level_tran ();

	RecoveryCoordinator register_resource (in Resource r) raises (Inactive);

	void register_synchronization (in Synchronization sync) raises (Inactive, SynchronizationUnavailable);

	void register_subtran_aware (in SubtransactionAwareResource r) raises (Inactive, NotSubtransaction);

	void rollback_only () raises (Inactive);

	string get_transaction_name ();

	Control create_subtransaction () raises (SubtransactionsUnavailable, Inactive);

	PropagationContext get_txcontext () raises (Unavailable);
    };

    interface RecoveryCoordinator
    {
	Status replay_completion (in Resource r) raises (NotPrepared);
    };
    
    interface Resource
    {
	Vote prepare () raises (HeuristicMixed, HeuristicHazard);
	void rollback () raises (HeuristicCommit, HeuristicMixed, HeuristicHazard);
	void commit () raises (NotPrepared, HeuristicRollback, HeuristicMixed, HeuristicHazard);
	void commit_one_phase () raises (HeuristicHazard);
	void forget ();
    };

    interface SubtransactionAwareResource : Resource
    {
	void commit_subtransaction (in Coordinator parent);
	void rollback_subtransaction ();
    };
    
    interface TransactionalObject
    {
    };

    interface Synchronization : TransactionalObject
    {
	void before_completion ();
	void after_completion (in Status s);
    };
    
};

#endif
