KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > commands > operations > IAdvancedUndoableOperation


1 /*******************************************************************************
2  * Copyright (c) 2005 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  * IAdvancedUndoableOperation defines an interface for undoable operations that
20  * modify one or more elements in a model and attempt to keep model listeners up
21  * to date with changes that occur in the undo and redo history involving particular
22  * model elements. It also defines methods for computing the validity of an operation
23  * for undo or redo before attempting to perform the undo or redo.
24  * </p>
25  * <p>
26  * This interface is intended to be used by legacy frameworks that are adapting
27  * their original undo and redo support to this framework. The methods in this
28  * interface allow legacy clients to maintain features not supported in the
29  * basic operations framework.
30  * </p>
31  *
32  * @since 3.1
33  *
34  */
35 public interface IAdvancedUndoableOperation {
36
37     /**
38      * <p>
39      * An operation history notification about this operation is about to be
40      * sent to operation history listeners. Any preparation needed before
41      * listeners are notified about this operation should be performed here.
42      *
43      * <p>
44      * This method has been added to support legacy undo frameworks that are
45      * adapting to IUndoableOperation. Operations that previously relied on
46      * notification from their containing history or stack before any listeners
47      * are notified about changes to the operation should implement this
48      * interface.
49      *
50      * @param event
51      * the event that is about to be sent with the pending
52      * notification
53      *
54      */
55     void aboutToNotify(OperationHistoryEvent event);
56
57     /**
58      * <p>
59      * Return an array of objects that are affected by executing, undoing, or
60      * redoing this operation. If it cannot be determined which objects are
61      * affected, return null.
62      * </p>
63      *
64      * @return the array of Objects modified by this operation, or
65      * <code>null</code> if the affected objects cannot be determined.
66      */
67     Object JavaDoc[] getAffectedObjects();
68
69     /**
70      * Return a status indicating the projected outcome of undoing the receiver.
71      *
72      * This method should be used to report the possible outcome of an undo and
73      * is used when computing the validity of an undo is too expensive to
74      * perform in {@link IUndoableOperation#canUndo()}. It is not called by the
75      * operation history, but instead is used by clients (such as implementers
76      * of {@link IOperationApprover}) who wish to perform advanced validation of
77      * an operation before attempting to undo it.
78      *
79      * If the result of this method is the discovery that an operation can in
80      * fact not be undone, then the operation is expected to correctly answer
81      * <code>false</code> on subsequent calls to
82      * {@link IUndoableOperation#canUndo()}.
83      *
84      * @param monitor
85      * the progress monitor (or <code>null</code>) to use for
86      * reporting progress to the user while computing the validity.
87      *
88      * @return the IStatus indicating the validity of the undo. The status
89      * severity should be set to <code>OK</code> if the undo can
90      * successfully be performed, and <code>ERROR</code> if it
91      * cannnot. Any other status is assumed to represent an ambiguous
92      * state.
93      * @throws ExecutionException
94      * if an exception occurs while computing the validity.
95      */
96     IStatus computeUndoableStatus(IProgressMonitor monitor)
97             throws ExecutionException;
98
99     /**
100      * Return a status indicating the projected outcome of redoing the receiver.
101      *
102      * This method should be used to report the possible outcome of a redo and
103      * is used when computing the validity of a redo is too expensive to perform
104      * in {@link IUndoableOperation#canRedo()}. It is not called by the
105      * operation history, but instead is used by clients (such as implementers
106      * of {@link IOperationApprover}) who wish to perform advanced validation of
107      * an operation before attempting to redo it.
108      *
109      * If the result of this method is the discovery that an operation can in
110      * fact not be redone, then the operation is expected to correctly answer
111      * <code>false</code> on subsequent calls to
112      * {@link IUndoableOperation#canRedo()}.
113      *
114      * @param monitor
115      * the progress monitor (or <code>null</code>) to use for
116      * reporting progress to the user while computing the validity.
117      *
118      * @return the IStatus indicating the validity of the redo. The status
119      * severity should be set to <code>OK</code> if the redo can
120      * successfully be performed, and <code>ERROR</code> if it
121      * cannnot. Any other status is assumed to represent an ambiguous
122      * state.
123      * @throws ExecutionException
124      * if an exception occurs while computing the validity.
125      */
126     IStatus computeRedoableStatus(IProgressMonitor monitor)
127             throws ExecutionException;
128
129 }
130
Popular Tags