1 /******************************************************************************* 2 * Copyright (c) 2006 IBM Corporation and others. 3 * All rights reserved. This program and the accompanying materials 4 * are made available under the terms of the Eclipse Public License v1.0 5 * which accompanies this distribution, and is available at 6 * http://www.eclipse.org/legal/epl-v10.html 7 * 8 * Contributors: 9 * IBM Corporation - initial API and implementation 10 *******************************************************************************/ 11 package org.eclipse.core.commands.operations; 12 13 import org.eclipse.core.commands.ExecutionException; 14 import org.eclipse.core.runtime.IProgressMonitor; 15 import org.eclipse.core.runtime.IStatus; 16 17 /** 18 * <p> 19 * IAdvancedUndoableOperation2 defines a method for computing the validity of 20 * executing an operation before attempting to execute it. It also defines a way 21 * for clients to specify that computing status should be done quietly, without 22 * consulting the user. This interface is useful when implementing 23 * {@link IOperationApprover2}, or any other object that performs validation of 24 * the undo history. It also allows operations to specify whether they should be 25 * run in the UI thread. 26 * </p> 27 * 28 * @since 3.3 29 * 30 */ 31 public interface IAdvancedUndoableOperation2 { 32 /** 33 * Return a status indicating the projected outcome of executing the 34 * receiver. 35 * 36 * This method should be used to report the possible outcome of executing an 37 * operation when computing the validity of an execute is too expensive to 38 * perform in {@link IUndoableOperation#canExecute()}. It is not called by 39 * the operation history, but instead is used by clients (such as 40 * implementers of {@link IOperationApprover2}) who wish to perform 41 * advanced validation of an operation before attempting to execute it. 42 * 43 * If the result of this method is the discovery that an operation can in 44 * fact not be executed, then the operation is expected to correctly answer 45 * <code>false</code> on subsequent calls to 46 * {@link IUndoableOperation#canExecute()}. 47 * 48 * @param monitor 49 * the progress monitor (or <code>null</code>) to use for 50 * reporting progress to the user while computing the validity. 51 * 52 * @return the IStatus indicating the validity of the execute. The status 53 * severity should be set to <code>OK</code> if the execute can 54 * successfully be performed, and <code>ERROR</code> if it cannot. 55 * Any other severity is assumed to represent an ambiguous state. 56 * @throws ExecutionException 57 * if an exception occurs while computing the validity. 58 */ 59 IStatus computeExecutionStatus(IProgressMonitor monitor) 60 throws ExecutionException; 61 62 /** 63 * Set a boolean that instructs whether the computation of the receiver's 64 * execution, undo, or redo status should quietly compute status without 65 * consulting or prompting the user. The default value is <code>false</code>. 66 * This flag should only be set to <code>true</code> while the execution, 67 * undo, or redo status computations are being performed in the background, 68 * and should be restored to <code>false</code> when complete. 69 * <p> 70 * If the status computation methods typically need to consult the user in 71 * order to determine the severity of a particular situation, the least 72 * severe status that could be chosen by the user should be returned when 73 * this flag is <code>true</code>. This can help to prevent overzealous 74 * disposal of the operation history when an operation is in an ambiguous 75 * state. Typically, the status computation methods are invoked with this 76 * flag set to <code>false</code> just before the actual execution, undo, 77 * or redo occurs, so the user can be consulted for the final outcome. 78 * 79 * @param quiet 80 * <code>true</code> if it is inappropriate to consult or 81 * otherwise prompt the user while computing status, and 82 * <code>false</code> if the user may be prompted. 83 * 84 * @see #computeExecutionStatus(IProgressMonitor) 85 * @see IAdvancedUndoableOperation#computeUndoableStatus(IProgressMonitor) 86 * @see IAdvancedUndoableOperation#computeRedoableStatus(IProgressMonitor) 87 */ 88 public void setQuietCompute(boolean quiet); 89 90 /** 91 * Return a boolean that instructs whether the operation should be executed, 92 * undone, or redone in a background thread. 93 * 94 * @return <code>true</code> if the operation should be run in the 95 * background, <code>false</code> if it should not. 96 */ 97 public boolean runInBackground(); 98 } 99