IUndoableOperation


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.IAdaptable;
15  import org.eclipse.core.runtime.IProgressMonitor;
16  import org.eclipse.core.runtime.IStatus;
17  
18  /**
19   * <p>
20   * IUndoableOperation defines an operation that can be executed, undone, and
21   * redone. Operations typically have fully defined parameters. That is, they are
22   * usually created after the user has been queried for any input needed to
23   * define the operation.
24   * </p>
25   * <p>
26   * Operations determine their ability to execute, undo, or redo according to the
27   * current state of the application. They do not make decisions about their
28   * validity based on where they occur in the operation history. That is left to
29   * the particular operation history.
30   * </p>
31   * 
32   * @since 3.1
33   */
34  public interface IUndoableOperation {
35  
36      /**
37       * <p>
38       * Add the specified context to the operation. If a context equal to the
39       * specified context is already present, do not add it again. Note that
40       * determining whether a context is already present is based on equality,
41       * not whether the context matches ({@link IUndoContext#matches(IUndoContext)})
42       * another context.
43       * </p>
44       * 
45       * @param context
46       *            the context to be added
47       */
48      void addContext(IUndoContext context);
49  
50      /**
51       * <p>
52       * Returns whether the operation can be executed in its current state.
53       * </p>
54       * 
55       * <p>
56       * Note: The computation for this method must be fast, as it is called
57       * frequently. If necessary, this method can be optimistic in its
58       * computation (returning true) and later perform more time-consuming
59       * computations during the actual execution of the operation, returning the
60       * appropriate status if the operation cannot actually execute at that time.
61       * </p>
62       * 
63       * @return <code>true</code> if the operation can be executed;
64       *         <code>false</code> otherwise.
65       */
66      boolean canExecute();
67  
68      /**
69       * <p>
70       * Returns whether the operation can be redone in its current state.
71       * </p>
72       * 
73       * <p>
74       * Note: The computation for this method must be fast, as it is called
75       * frequently. If necessary, this method can be optimistic in its
76       * computation (returning true) and later perform more time-consuming
77       * computations during the actual redo of the operation, returning the
78       * appropriate status if the operation cannot actually be redone at that
79       * time.
80       * </p>
81       * 
82       * @return <code>true</code> if the operation can be redone;
83       *         <code>false</code> otherwise.
84       */
85      boolean canRedo();
86  
87      /**
88       * <p>
89       * Returns whether the operation can be undone in its current state.
90       * </p>
91       * 
92       * <p>
93       * Note: The computation for this method must be fast, as it is called
94       * frequently. If necessary, this method can be optimistic in its
95       * computation (returning true) and later perform more time-consuming
96       * computations during the actual undo of the operation, returning the
97       * appropriate status if the operation cannot actually be undone at that
98       * time.
99       * </p>
100      * 
101      * @return <code>true</code> if the operation can be undone;
102      *         <code>false</code> otherwise.
103      */
104     boolean canUndo();
105 
106     /**
107      * Dispose of the operation. This method is used when the operation is no
108      * longer kept in the history. Implementers of this method typically
109      * unregister any listeners.
110      * 
111      */
112     void dispose();
113 
114     /**
115      * Execute the operation. This method should only be called the first time
116      * that an operation is executed.
117      * 
118      * @param monitor
119      *            the progress monitor (or <code>null</code>) to use for
120      *            reporting progress to the user.
121      * @param info
122      *            the IAdaptable (or <code>null</code>) provided by the
123      *            caller in order to supply UI information for prompting the
124      *            user if necessary. When this parameter is not
125      *            <code>null</code>, it should minimally contain an adapter
126      *            for the org.eclipse.swt.widgets.Shell.class.
127      * 
128      * @return the IStatus of the execution. The status severity should be set
129      *         to <code>OK</code> if the operation was successful, and
130      *         <code>ERROR</code> if it was not. Any other status is assumed
131      *         to represent an incompletion of the execution.
132      * @throws ExecutionException
133      *             if an exception occurred during execution.
134      */
135     IStatus execute(IProgressMonitor monitor, IAdaptable info)
136             throws ExecutionException;
137 
138     /**
139      * <p>
140      * Returns the array of contexts that have been assigned to the operation.
141      * </p>
142      * <p>
143      * This method may be called by the operation history from inside a
144      * synchronized block. To avoid deadlock conditions, implementers of this
145      * method must avoid dispatching and waiting on threads that modify the
146      * operation history during this method.
147      * </p>
148      * 
149      * @return the array of contexts
150      */
151     IUndoContext[] getContexts();
152 
153     /**
154      * Return the label that should be used to show the name of the operation to
155      * the user. This label is typically combined with the command strings shown
156      * to the user in "Undo" and "Redo" user interfaces.
157      * 
158      * @return the label
159      */
160     String   getLabel();
161 
162     /**
163      * <p>
164      * Returns whether the operation has a matching context for the specified
165      * context.
166      * </p>
167      * <p>
168      * This method may be called by the operation history from inside a
169      * synchronized block. To avoid deadlock conditions, implementers of this
170      * method must avoid dispatching and waiting on threads that modify the
171      * operation history during this method.
172      * </p>
173      * 
174      * @see IUndoContext#matches(IUndoContext)
175      * 
176      * @param context
177      *            the context in question
178      * @return <code>true</code> if the context is present, <code>false</code>
179      *         if it is not.
180      */
181     boolean hasContext(IUndoContext context);
182 
183     /**
184      * Redo the operation. This method should only be called after an operation
185      * has been undone.
186      * 
187      * @param monitor
188      *            the progress monitor (or <code>null</code>) to use for
189      *            reporting progress to the user.
190      * @param info
191      *            the IAdaptable (or <code>null</code>) provided by the
192      *            caller in order to supply UI information for prompting the
193      *            user if necessary. When this parameter is not
194      *            <code>null</code>, it should minimally contain an adapter
195      *            for the org.eclipse.swt.widgets.Shell.class.
196      * @return the IStatus of the redo. The status severity should be set to
197      *         <code>OK</code> if the redo was successful, and
198      *         <code>ERROR</code> if it was not. Any other status is assumed
199      *         to represent an incompletion of the redo.
200      * @throws ExecutionException
201      *             if an exception occurred during redo.
202      */
203 
204     IStatus redo(IProgressMonitor monitor, IAdaptable info)
205             throws ExecutionException;
206 
207     /**
208      * Remove the specified context from the operation. This method has no
209      * effect if the context is not equal to another context in the context
210      * list. Note that determining whether a context is present when removing it
211      * is based on equality, not whether the context matches ({@link
212      * IUndoContext#matches(IUndoContext)}) another context.
213      * 
214      * @param context
215      *            the context to be removed
216      */
217     void removeContext(IUndoContext context);
218 
219     /**
220      * Undo the operation. This method should only be called after an operation
221      * has been executed.
222      * 
223      * @param monitor
224      *            the progress monitor (or <code>null</code>) to use for
225      *            reporting progress to the user.
226      * @param info
227      *            the IAdaptable (or <code>null</code>) provided by the
228      *            caller in order to supply UI information for prompting the
229      *            user if necessary. When this parameter is not
230      *            <code>null</code>, it should minimally contain an adapter
231      *            for the org.eclipse.swt.widgets.Shell.class.
232      * @return the IStatus of the undo. The status severity should be set to
233      *         <code>OK</code> if the redo was successful, and
234      *         <code>ERROR</code> if it was not. Any other status is assumed
235      *         to represent an incompletion of the undo.
236      * @throws ExecutionException
237      *             if an exception occurred during undo.
238      */
239     IStatus undo(IProgressMonitor monitor, IAdaptable info)
240             throws ExecutionException;
241 
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags