org.eclipse.viatra2.core2/src/org/eclipse/viatra2/core/ITransactionManager.java

/*******************************************************************************
 * Copyright (c) 2004-2008 Andras Schmidt, Andras Balogh, Istvan Rath and Daniel Varro
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Andras Schmidt, Andras Balogh, Istvan Rath - initial API and implementation
 *******************************************************************************/

package org.eclipse.viatra2.core;

/**
 * This interface defines the required operations of a transaction manager for
 * the Viatra core. Transaction is bound to the thread that calls
 * beginTransaction.
 * 
 * 
 * @author Andras Balogh
 * 
 *         Modification on 2006.08.07 by Istvan Rath: - added
 *         beginUndoableTransaction - added tryBeginUndoableTransaction -
 *         introduced unique transaction ID: changed return type of functions to
 *         String - added undoTransaction
 * 
 */
public interface ITransactionManager {
	/**
	 * Initializes the transaction manager.
	 * 
	 * @param p
	 *            - the collection of runtime properties
	 * @param l
	 *            - the framework logger
	 * @param m
	 *            - the owning modelspace
	 * @throws VPMRuntimeException
	 */
	// public void init(Logger l, Properties p, IModelSpace m) throws
	// VPMRuntimeException;
	/**
	 * Begins a new undoable transaction. Can block the caller thread. If the
	 * current thread is in transaction then increments the transaction counter.
	 * 
	 * @return a unique transaction ID
	 */
	public String beginUndoableTransaction();

	/**
	 * Begins a new undoable transaction. Can block the caller thread. If the
	 * current thread is in transaction then increments the transaction counter.
	 * 
	 * @return a unique transaction ID
	 * @param info
	 *            an information object which is passed to all notification
	 *            listeners
	 */
	public String beginUndoableTransaction(Object info);

	/**
	 * Begins a new, NOT UNDOABLE transaction. Can block the caller thread. If
	 * the current thread is in transaction then increments the transaction
	 * counter.
	 * 
	 * @return a unique transaction ID
	 */
	public String beginTransaction();

	/**
	 * Begins a new, NOT UNDOABLE transaction. Can block the caller thread. If
	 * the current thread is in transaction then increments the transaction
	 * counter.
	 * 
	 * @return a unique transaction ID
	 * @param info
	 *            an information object which is passed to all notification
	 *            listeners. Example usage: pass Boolean.TRUE to stop the 
	 *            GUI from updating mid-transaction.
	 */
	public String beginTransaction(Object info);

	/**
	 * Tries to begin a transaction. Returns immediately. Can be used for both
	 * undoable and non-undoable transactions.
	 * 
	 * @return true if the modelspace was not locked and this thread locked the
	 *         modelspace false if modelspace is locked, and no lock was done
	 */
	public boolean tryBeginTransaction();

	/**
	 * Commits the current transaction. Decrements the transaction counter and
	 * if it is zero then commits the transaction.
	 * 
	 */
	public void commitTransaction();

	
	/**
	 * Commits all currently active subtransactions together with the main transaction.
	 */
	public void commitCompositeTransaction();
	
	
	/**
	 * Aborts the current transaction.
	 * Effect: the transaction lock will be released.
	 */
	public void abortTransaction();

	/**
	 * Undoes the effects of the transaction identified by the unique ID given.
	 * Note: all other transactions, which are affected, are also undoed.
	 * 
	 * @param aTransactionID
	 */
	public void undoTransaction(String aTransactionID);

	/**
	 * Pauses the current transaction. This means that lock is released. Should
	 * only be use by interpreter debugger. Pausing a transaction can cause the
	 * transaction code to crash.
	 * 
	 * @return object that contains transaction counter before pausing
	 *         transaction
	 */
	public IPause pauseTransaction() throws IllegalMonitorStateException;

	/**
	 * unpauses a transaction. Lock regained, and transaction goes on.
	 * 
	 * @param n
	 *            the object that was returned by pauseTransaction
	 */
	public void unPauseTransaction(IPause n);
}