/*******************************************************************************
 * Copyright (c) 2005 IBM Corporation and others.
 * 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:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.commands.operations;

import org.eclipse.core.commands.ExecutionException;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.IStatus;

/**
 * <p>
 * IAdvancedUndoableOperation defines an interface for undoable operations that
 * modify one or more elements in a model and attempt to keep model listeners up
 * to date with changes that occur in the undo and redo history involving particular
 * model elements.  It also defines methods for computing the validity of an operation
 * for undo or redo before attempting to perform the undo or redo.
 * </p>
 * <p>
 * This interface is intended to be used by legacy frameworks that are adapting
 * their original undo and redo support to this framework. The methods in this
 * interface allow legacy clients to maintain features not supported in the
 * basic operations framework.
 * </p>
 * 
 * @since 3.1
 * 
 */
public interface IAdvancedUndoableOperation {

	/**
	 * <p>
	 * An operation history notification about this operation is about to be
	 * sent to operation history listeners. Any preparation needed before
	 * listeners are notified about this operation should be performed here.
	 * 
	 * <p>
	 * This method has been added to support legacy undo frameworks that are
	 * adapting to IUndoableOperation. Operations that previously relied on
	 * notification from their containing history or stack before any listeners
	 * are notified about changes to the operation should implement this
	 * interface.
	 * 
	 * @param event 
	 *            the event that is about to be sent with the pending
	 *            notification
	 * 
	 */
	void aboutToNotify(OperationHistoryEvent event);

	/**
	 * <p>
	 * Return an array of objects that are affected by executing, undoing, or
	 * redoing this operation. If it cannot be determined which objects are
	 * affected, return null.
	 * </p>
	 * 
	 * @return the array of Objects modified by this operation, or
	 *         <code>null</code> if the affected objects cannot be determined.
	 */
	Object[] getAffectedObjects();

	/**
	 * Return a status indicating the projected outcome of undoing the receiver.
	 * 
	 * This method should be used to report the possible outcome of an undo and
	 * is used when computing the validity of an undo is too expensive to
	 * perform in {@link IUndoableOperation#canUndo()}. It is not called by the
	 * operation history, but instead is used by clients (such as implementers
	 * of {@link IOperationApprover}) who wish to perform advanced validation of
	 * an operation before attempting to undo it.
	 * 
	 * If the result of this method is the discovery that an operation can in
	 * fact not be undone, then the operation is expected to correctly answer
	 * <code>false</code> on subsequent calls to
	 * {@link IUndoableOperation#canUndo()}.
	 * 
	 * @param monitor 
	 *            the progress monitor (or <code>null</code>) to use for
	 *            reporting progress to the user while computing the validity.
	 * 
	 * @return the IStatus indicating the validity of the undo. The status
	 *         severity should be set to <code>OK</code> if the undo can
	 *         successfully be performed, and <code>ERROR</code> if it
	 *         cannnot. Any other status is assumed to represent an ambiguous
	 *         state.
	 * @throws ExecutionException
	 *             if an exception occurs while computing the validity.
	 */
	IStatus computeUndoableStatus(IProgressMonitor monitor)
			throws ExecutionException;

	/**
	 * Return a status indicating the projected outcome of redoing the receiver.
	 * 
	 * This method should be used to report the possible outcome of a redo and
	 * is used when computing the validity of a redo is too expensive to perform
	 * in {@link IUndoableOperation#canRedo()}. It is not called by the
	 * operation history, but instead is used by clients (such as implementers
	 * of {@link IOperationApprover}) who wish to perform advanced validation of
	 * an operation before attempting to redo it.
	 * 
	 * If the result of this method is the discovery that an operation can in
	 * fact not be redone, then the operation is expected to correctly answer
	 * <code>false</code> on subsequent calls to
	 * {@link IUndoableOperation#canRedo()}.
	 * 
	 * @param monitor 
	 *            the progress monitor (or <code>null</code>) to use for
	 *            reporting progress to the user while computing the validity.
	 * 
	 * @return the IStatus indicating the validity of the redo. The status
	 *         severity should be set to <code>OK</code> if the redo can
	 *         successfully be performed, and <code>ERROR</code> if it
	 *         cannnot. Any other status is assumed to represent an ambiguous
	 *         state.
	 * @throws ExecutionException
	 *             if an exception occurs while computing the validity.
	 */
	IStatus computeRedoableStatus(IProgressMonitor monitor)
			throws ExecutionException;

}