| /******************************************************************************* |
| * Copyright (c) 2003, 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.wst.common.frameworks.internal.datamodel; |
| |
| import org.eclipse.core.commands.ExecutionException; |
| import org.eclipse.core.commands.operations.IUndoableOperation; |
| import org.eclipse.core.runtime.IAdaptable; |
| import org.eclipse.core.runtime.IProgressMonitor; |
| import org.eclipse.core.runtime.IStatus; |
| import org.eclipse.wst.common.frameworks.datamodel.IDataModel; |
| import org.eclipse.wst.common.frameworks.datamodel.IDataModelOperation; |
| |
| /** |
| * <p> |
| * IDataModelManagerOperation is an IDataModelOperation returned from |
| * {@link IDataModel#getDefaultOperation()}. This Operation wraps the IDataModelOperation returned |
| * from the IDatModelProvider backing the IDataModel that created it. |
| * </p> |
| * <p> |
| * This operation supports pre and post operation execution. Pre and post operations are |
| * IDataModelOperations registered through the OperationExtension extension point which are executed |
| * before and after the primary operation. |
| * </p> |
| * <p> |
| * <b>Example 1</b> <br> |
| * Suppose an IDataModelProvider returns IDataModelOperation X as its default operation, and this |
| * IDataModelManagerOperation is wrapping X. Also suppose operation A is registered as a pre |
| * operation to X and operation B is registered as a post operation to X. When this |
| * IDataModelManagerOperation is executed the following operations will be executed in this order: |
| * A, X, B which may be thought as a preorder execution of the following tree: |
| * </p> |
| * |
| * <pre> |
| * X |
| * / \ |
| * A B |
| * |
| * execution = A.execute(), X.execute(), B.execute() |
| * undo = B.undo(), X.undo(), A.undo() |
| * redo = A.redo(), X.redo(), B.redo() |
| * </pre> |
| * |
| * <p> |
| * <b>Example 2</b> <br> |
| * If A had a pre operation C and post operation D, and B had a pre operation E and post operation F |
| * then the tree would look like: |
| * </p> |
| * |
| * <pre> |
| * X |
| * / \ |
| * / \ |
| * A B |
| * / \ / \ |
| * C D E F |
| * |
| * execution = C.execute(), A.execute(), D.execute(), X.execute(), E.execute(), B.execute(), F.execute() |
| * undo = F.undo(), B.undo(), E.undo(), X.undo(), D.undo(), A.undo(), C.undo() |
| * redo = C.redo(), A.redo(), D.redo(), X.redo(), E.redo(), B.redo(), F.redo() |
| * </pre> |
| * |
| * </p> |
| * <b>Example 3</b> <br> |
| * If there is more than one pre operation or post operation for a particular operation, then there |
| * is no defined ordering of those pre and post operation with respect to each other, other than |
| * that it will be consistent. For example suppose operation X had only two pre operations, A and B, |
| * and two post operations, C and D. The execution tree would be one of the following: |
| * </p> |
| * |
| * <pre> |
| * X X X X |
| * / \ / \ / \ / \ |
| * AB CD BA CD AB DC BA DC |
| * |
| * exec = ABXCD exec = BAXCD exec = ABXDC exec = BAXDC |
| * undo = DCXBA undo = DCXAB undo = CDXBA undo = CDXAB |
| * redo = ABXCD redo = BAXCD redo = ABXDC redo = BAXDC |
| * </pre> |
| * |
| * <p> |
| * During execution, rollback, undo, and redo, {@link IDataModelPausibleOperationEvent}s are fired to all |
| * registered {@link IDataModelPausibleOperationListener}s giving each of them an opportunity to pause the |
| * operation by returning {@link IDataModelPausibleOperationListener#PAUSE}. |
| * {@link IDataModelPausibleOperationEvent} has more details on when these events are fired. |
| * </p> |
| * <p> |
| * This interface is not intended to be implemented by clients. |
| * </p> |
| * |
| * @see IDataModel#getDefaultOperation() |
| * |
| * @since 1.5 |
| */ |
| public interface IDataModelPausibleOperation extends IDataModelOperation { |
| |
| /** |
| * <p> |
| * The exeuction state when the operation never been executed. When the operation is in this |
| * state it may only be executed. |
| * </p> |
| * |
| * @see IUndoableOperation#execute(IProgressMonitor, IAdaptable) |
| */ |
| public static final int NOT_STARTED = 0; |
| /** |
| * <p> |
| * The exeuction state while the operation is executing. When the operation is in this state it |
| * may only be paused by an {@link IDataModelPausibleOperationListener}. |
| * </p> |
| * |
| * @see IUndoableOperation#execute(IProgressMonitor, IAdaptable) |
| * @see IDataModelPausibleOperationListener |
| */ |
| public static final int RUNNING_EXECUTE = 1; |
| /** |
| * <p> |
| * The exeuction state while the operation is rolling back. When the operation is in this state |
| * it may only be paused by an {@link IDataModelPausibleOperationListener}. |
| * </p> |
| * |
| * @see #rollBack(IProgressMonitor, IAdaptable) |
| * @see IDataModelPausibleOperationListener |
| */ |
| public static final int RUNNING_ROLLBACK = 2; |
| /** |
| * <p> |
| * The exeuction state while the operation is redoing. When the operation is in this state it |
| * may only be paused by an {@link IDataModelPausibleOperationListener}. |
| * </p> |
| * |
| * @see IUndoableOperation#undo(IProgressMonitor, IAdaptable) |
| * @see IDataModelPausibleOperationListener |
| */ |
| public static final int RUNNING_UNDO = 3; |
| /** |
| * <p> |
| * The exeuction state while the operaiton is redoing. When the operation is in this state it |
| * may only be paused by an {@link IDataModelPausibleOperationListener}. |
| * </p> |
| * |
| * @see IUndoableOperation#redo(IProgressMonitor, IAdaptable) |
| * @see IDataModelPausibleOperationListener |
| */ |
| public static final int RUNNING_REDO = 4; |
| /** |
| * <p> |
| * The exeuction state when the operation has been paused while it was executing. When the |
| * operation is in this state it may either be resumed to continue execution or rolled back to |
| * undo the partial execution. |
| * </p> |
| * |
| * @see #resume(IProgressMonitor, IAdaptable) |
| * @see #rollBack(IProgressMonitor, IAdaptable) |
| */ |
| public static final int PAUSED_EXECUTE = 5; |
| /** |
| * <p> |
| * The exeuction state when the operation has been paused while it was rolling back. When the |
| * operation is in this state it may either be resumed to continue rolling back or executed |
| * which continue the foward execution from the point where the rollback was paused |
| * </p> |
| * |
| * @see #resume(IProgressMonitor, IAdaptable) |
| * @see IUndoableOperation#execute(IProgressMonitor, IAdaptable) |
| */ |
| public static final int PAUSED_ROLLBACK = 6; |
| /** |
| * <p> |
| * The exeuction state when the operation has been paused while it was undoing. When the |
| * operation is in this state it may be only be resumed to continue undoing. |
| * </p> |
| * |
| * @see #resume(IProgressMonitor, IAdaptable) |
| */ |
| public static final int PAUSED_UNDO = 7; |
| /** |
| * <p> |
| * The exeuction state when the operation has been paused while it was redoing. When the |
| * operation is in this state it may only be resumed to continue redoing. |
| * </p> |
| * |
| * @see #resume(IProgressMonitor, IAdaptable) |
| */ |
| public static final int PAUSED_REDO = 8; |
| /** |
| * <p> |
| * The exeuction state when the operation finished execution. When the operation is in this |
| * state it may only be undone. |
| * </p> |
| * |
| * @see IUndoableOperation#undo(IProgressMonitor, IAdaptable) |
| */ |
| public static final int COMPLETE_EXECUTE = 9; |
| /** |
| * <p> |
| * The exeuction state when the operation finished rolling back. When the operation is in this |
| * state it may only be executed. |
| * </p> |
| * |
| * @see IUndoableOperation#execute(IProgressMonitor, IAdaptable) |
| */ |
| public static final int COMPLETE_ROLLBACK = 10; |
| /** |
| * <p> |
| * The exeuction state when the operation finished undoing. When the operation is in this state |
| * it may only be redone. |
| * </p> |
| * |
| * @see IUndoableOperation#redo(IProgressMonitor, IAdaptable) |
| */ |
| public static final int COMPLETE_UNDO = 11; |
| /** |
| * <p> |
| * The exeuction state when the operation finished redoing. When the operation is in this state |
| * it may only be udone. |
| * </p> |
| * |
| * @see IUndoableOperation#undo(IProgressMonitor, IAdaptable) |
| */ |
| public static final int COMPLETE_REDO = 12; |
| |
| |
| /** |
| * <p> |
| * Returns the current execution state of the operation. Returns one of: |
| * <ul> |
| * <li>{@link #NOT_STARTED}</li> |
| * <li>{@link #RUNNING_EXECUTE}</li> |
| * <li>{@link #RUNNING_ROLLBACK}</li> |
| * <li>{@link #RUNNING_UNDO}</li> |
| * <li>{@link #RUNNING_REDO}</li> |
| * <li>{@link #PAUSED_EXECUTE}</li> |
| * <li>{@link #PAUSED_ROLLBACK}</li> |
| * <li>{@link #PAUSED_UNDO}</li> |
| * <li>{@link #PAUSED_REDO}</li> |
| * <li>{@link #COMPLETE_EXECUTE}</li> |
| * <li>{@link #COMPLETE_ROLLBACK}</li> |
| * <li>{@link #COMPLETE_UNDO}</li> |
| * <li>{@link #COMPLETE_REDO}</li> |
| * </ul> |
| * <p> |
| * |
| * @return The current execution state. |
| */ |
| public int getExecutionState(); |
| |
| /** |
| * <p> |
| * Resumes execution if the operation is curently paused. An operation is paused if |
| * {@link #getExecutionState()} returns any of {@link #PAUSED_EXECUTE}, |
| * {@link #PAUSED_ROLLBACK}, {@link #PAUSED_UNDO}, or {@link #PAUSED_REDO}. |
| * </p> |
| * |
| * @param monitor |
| * the progress monitor (or <code>null</code>) to use for reporting progress to |
| * the user. |
| * @param info |
| * the IAdaptable (or <code>null</code>) provided by the caller in order to supply |
| * UI information for prompting the user if necessary. When this parameter is not |
| * <code>null</code>, it should minimally contain an adapter for the |
| * org.eclipse.swt.widgets.Shell.class. |
| * |
| * @return the IStatus of the resume. The status severity should be set to <code>OK</code> if |
| * the operation was successful, and <code>ERROR</code> if it was not. Any other |
| * status is assumed to represent an incompletion of the resume. |
| */ |
| public IStatus resume(IProgressMonitor monitor, IAdaptable info) throws ExecutionException; |
| |
| /** |
| * <p> |
| * Rolls back the partial execution if the operation is currently in |
| * {@link #getExecutionState()} returns eiter {@link #PAUSED_EXECUTE} or |
| * {@link #PAUSED_ROLLBACK}. |
| * </p> |
| * |
| * @param monitor |
| * the progress monitor (or <code>null</code>) to use for reporting progress to |
| * the user. |
| * @param info |
| * the IAdaptable (or <code>null</code>) provided by the caller in order to supply |
| * UI information for prompting the user if necessary. When this parameter is not |
| * <code>null</code>, it should minimally contain an adapter for the |
| * org.eclipse.swt.widgets.Shell.class. |
| * |
| * @return the IStatus of the resume. The status severity should be set to <code>OK</code> if |
| * the operation was successful, and <code>ERROR</code> if it was not. Any other |
| * status is assumed to represent an incompletion of the resume. |
| * |
| */ |
| public IStatus rollBack(IProgressMonitor monitor, IAdaptable info) throws ExecutionException; |
| |
| /** |
| * <p> |
| * Adds an operation listener to listen for operation events. |
| * </p> |
| * |
| * @param operationListener |
| * the IOperationListener to add. |
| */ |
| public void addOperationListener(IDataModelPausibleOperationListener operationListener); |
| |
| /** |
| * <p> |
| * Removes the specified IOperationLinstener. |
| * <p> |
| * |
| * @param operationListener |
| * The IOperatoinListener to remove. |
| */ |
| public void removeOperationListener(IDataModelPausibleOperationListener operationListener); |
| |
| } |
