SleeTransactionManager.java

 /*
  * Mobicents: The Open Source SLEE Platform      
  *
  * Copyright 2003-2005, CocoonHive, LLC., 
  * and individual contributors as indicated
  * by the @authors tag. See the copyright.txt 
  * in the distribution for a full listing of   
  * individual contributors.
  *
  * This is free software; you can redistribute it
  * and/or modify it under the terms of the 
  * GNU Lesser General Public License as
  * published by the Free Software Foundation; 
  * either version 2.1 of
  * the License, or (at your option) any later version.
  *
  * This software is distributed in the hope that 
  * it will be useful, but WITHOUT ANY WARRANTY; 
  * without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR 
  * PURPOSE. See the GNU Lesser General Public License
  * for more details.
  *
  * You should have received a copy of the 
  * GNU Lesser General Public
  * License along with this software; 
  * if not, write to the Free
  * Software Foundation, Inc., 51 Franklin St, 
  * Fifth Floor, Boston, MA
  * 02110-1301 USA, or see the FSF site:
  * http://www.fsf.org.
  */

package org.mobicents.slee.runtime.transaction;

import javax.slee.SLEEException;
import javax.slee.TransactionRequiredLocalException;
import javax.transaction.HeuristicMixedException;
import javax.transaction.HeuristicRollbackException;
import javax.transaction.RollbackException;
import javax.transaction.SystemException;
import javax.transaction.TransactionManager;

/** 
 * 
 * Transaction manager contract within SLEE. 
 * Provides convenience methods for tx and its context handling.
 * 
 * @author M. Ranganathan
 * @author Ivelin Ivanov
 * @author martins
 * 
 */
public interface SleeTransactionManager extends javax.slee.transaction.SleeTransactionManager {
	
    public static final String JNDI_NAME = "SleeTransactionManager";
    
	/** Verifies if we are in the context of a transaction.
	 * 
	 * @throws  TransactionRequiredLocalException if we are not in the context of a transaction.
	 */
	public void mandateTransaction() throws TransactionRequiredLocalException;
	
	/**
	 * Ensures a transaction exists, i.e., if there is no transaction one is created
	 * @return true if a transaction was created
	 */
	public boolean requireTransaction();
	
	/**
	 * Executes logic to complete the handling of a slee transaction by a method that requires a tx context. to be used as a complement of requireTransaction()
	 *  
	 * @param terminateTx indicates if the logic should terminate the tx or not
	 * @param doRollback if true indicates a rollback should be done, either by terminating the tx with rollback() or by just setting the rollback only flag
	 * @param txManager the tx manager to use
	 * @throws SLEEException if the transaction can't be finalized
	 * @throws SystemException 
	 * @throws SecurityException 
	 * @throws IllegalStateException 
	 * @throws HeuristicRollbackException 
	 * @throws HeuristicMixedException 
	 * @throws RollbackException 
	 */
	public void requireTransactionEnd(boolean terminateTx, boolean doRollback) throws IllegalStateException, SecurityException, SystemException, RollbackException, HeuristicMixedException, HeuristicRollbackException;

	/**
	 * retrieves the context object associated with the current transaction
	 * @return
	 * @throws SystemException
	 */
	public TransactionContext getTransactionContext() throws SystemException;
	
	/**
	 * adds a new {@link TransactionalAction} that will be executed as soon as the transaction commits
	 * @param action
	 * @throws SystemException
	 */
	public void addAfterCommitPriorityAction(TransactionalAction action) throws SystemException; 
	
	/**
	 * adds a new {@link TransactionalAction} that will be executed after the priority actions are executed, which is when the transaction commits
	 * @param action
	 * @throws SystemException
	 */
	public void addAfterCommitAction(TransactionalAction action) throws SystemException; 
	
	/**
	 * Convinience method to add a {@link TransactionalAction} to the
	 * {@link TransactionContext} and execute it if rollback occurrs. This
	 * method will ignore the action if there is no valid transaction, instead of failing.
	 * 
	 * @param action
	 * @throws SystemException 
	 */
	public void addAfterRollbackAction(TransactionalAction action) throws SystemException; 
	
	/**
	 * adds a new {@link TransactionalAction} that will be executed before the transaction is committed
	 * @param action
	 * @throws SystemException
	 */
	public void addBeforeCommitAction(TransactionalAction action) throws SystemException; 
	
	/**
	 * adds a new {@link TransactionalAction} that will be executed before the transaction is committed, at first
	 * @param action
	 * @throws SystemException
	 */
	public void addBeforeCommitPriorityAction(TransactionalAction action) throws SystemException;
	
	/**
	 * 
	 * @return true if the current transaction is marked for rollback
	 * @throws SystemException
	 */
    public boolean getRollbackOnly() throws SystemException;
    
   /**
     * @return String - a list of ongoing SLEE transactions
     */
    public String displayOngoingSleeTransactions();

    /**
     * Retrieves the underlying transaction manager.
     * @return
     */
    public TransactionManager getRealTransactionManager();
    
}