KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ltk > core > refactoring > Refactoring


1 /*******************************************************************************
2  * Copyright (c) 2000, 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.ltk.core.refactoring;
12
13 import org.eclipse.core.runtime.CoreException;
14 import org.eclipse.core.runtime.IProgressMonitor;
15 import org.eclipse.core.runtime.OperationCanceledException;
16 import org.eclipse.core.runtime.PlatformObject;
17 import org.eclipse.core.runtime.SubProgressMonitor;
18
19 /**
20  * Abstract super class for all refactorings. Refactorings are used to perform
21  * behavior preserving work space transformations. A refactoring offers two
22  * different kind of methods:
23  * <ol>
24  * <li>methods to check conditions to determine if the refactoring can be carried out
25  * in general and if transformation will be behavioral persevering.
26  * </li>
27  * <li>a method to create a {@link org.eclipse.ltk.core.refactoring.Change} object
28  * that represents the actual work space modifications.
29  * </li>
30  * </ol>
31  * The life cycle of a refactoring is as follows:
32  * <ol>
33  * <li>the refactoring gets created</li>
34  * <li>the refactoring is initialized with the elements to be refactored. It is
35  * up to a concrete refactoring implementation to provide corresponding API.</li>
36  * <li>{@link #checkInitialConditions(IProgressMonitor)} is called. The method
37  * can be called more than once.</li>
38  * <li>additional arguments are provided to perform the refactoring (for example
39  * the new name of a element in the case of a rename refactoring). It is up
40  * to a concrete implementation to provide corresponding API.</li>
41  * <li>{@link #checkFinalConditions(IProgressMonitor)} is called. The method
42  * can be called more than once. The method must not be called if
43  * {@link #checkInitialConditions(IProgressMonitor)} returns a refactoring
44  * status of severity {@link RefactoringStatus#FATAL}.</li>
45  * <li>{@link #createChange(IProgressMonitor)} is called. The method must only be
46  * called once after each call to {@link #checkFinalConditions(IProgressMonitor)}
47  * and should not be called if one of the condition checking methods
48  * returns a refactoring status of severity {@link RefactoringStatus#FATAL}.
49  * </li>
50  * <li>steps 4 to 6 can be executed repeatedly (for example when the user goes
51  * back from the preview page).
52  * </li>
53  * </ol>
54  *
55  * <p>
56  * A refactoring can not assume that all resources are saved before any methods
57  * are called on it. Therefore a refactoring must be able to deal with unsaved
58  * resources.
59  * </p>
60  * <p>
61  * The class should be subclassed by clients wishing to implement new refactorings.
62  * </p>
63  *
64  * @since 3.0
65  */
66 public abstract class Refactoring extends PlatformObject {
67     
68     private Object JavaDoc fValidationContext;
69
70     /**
71      * Sets the validation context used when calling
72      * {@link org.eclipse.core.resources.IWorkspace#validateEdit(org.eclipse.core.resources.IFile[], java.lang.Object)}.
73      *
74      * @param context the <code>org.eclipse.swt.widgets.Shell</code> that is
75      * to be used to parent any dialogs with the user, or <code>null</code> if
76      * there is no UI context (declared as an <code>Object</code> to avoid any
77      * direct references on the SWT component)
78      */
79     public final void setValidationContext(Object JavaDoc context) {
80         fValidationContext= context;
81     }
82     
83     /**
84      * Returns the validation context
85      *
86      * @return the validation context or <code>null</code> if no validation
87      * context has been set.
88      */
89     public final Object JavaDoc getValidationContext() {
90         return fValidationContext;
91     }
92     
93     /**
94      * Returns the refactoring's name.
95      *
96      * @return the refactoring's human readable name. Must not be
97      * <code>null</code>
98      */
99     public abstract String JavaDoc getName();
100     
101     //---- Conditions ------------------------------------------------------------
102
103     /**
104      * Returns the tick provider used for progress reporting for this
105      * refactoring.
106      *
107      * @return the refactoring tick provider used for progress reporting
108      *
109      * @since 3.2
110      */
111     public final RefactoringTickProvider getRefactoringTickProvider() {
112         RefactoringTickProvider result= doGetRefactoringTickProvider();
113         if (result == null) {
114             result= RefactoringTickProvider.DEFAULT;
115         }
116         return result;
117     }
118     
119     /**
120      * Hook method to provide the tick provider used for progress reporting.
121      * <p>
122      * Subclasses may override this method
123      * </p>
124      * @return the refactoring tick provider used for progress reporting
125      *
126      * @since 3.2
127      */
128     protected RefactoringTickProvider doGetRefactoringTickProvider() {
129         return RefactoringTickProvider.DEFAULT;
130     }
131     
132     /**
133      * Checks all conditions. This implementation calls <code>checkInitialConditions</code>
134      * and <code>checkFinalConditions</code>.
135      * <p>
136      * Subclasses may extend this method to provide additional condition checks.
137      * </p>
138      *
139      * @param pm a progress monitor to report progress
140      *
141      * @return a refactoring status. If the status is <code>RefactoringStatus#FATAL</code>
142      * the refactoring has to be considered as not being executable.
143      *
144      * @throws CoreException if an exception occurred during condition checking.
145      * If this happens then the condition checking has to be interpreted as failed
146      *
147      * @throws OperationCanceledException if the condition checking got canceled
148      *
149      * @see #checkInitialConditions(IProgressMonitor)
150      * @see #checkFinalConditions(IProgressMonitor)
151      */
152     public RefactoringStatus checkAllConditions(IProgressMonitor pm) throws CoreException, OperationCanceledException {
153         RefactoringTickProvider refactoringTickProvider= getRefactoringTickProvider();
154         pm.beginTask("", refactoringTickProvider.getCheckAllConditionsTicks()); //$NON-NLS-1$
155 RefactoringStatus result= new RefactoringStatus();
156         result.merge(checkInitialConditions(new SubProgressMonitor(pm, refactoringTickProvider.getCheckInitialConditionsTicks())));
157         if (!result.hasFatalError()) {
158             if (pm.isCanceled())
159                 throw new OperationCanceledException();
160             result.merge(checkFinalConditions(new SubProgressMonitor(pm, refactoringTickProvider.getCheckFinalConditionsTicks())));
161         }
162         pm.done();
163         return result;
164     }
165     
166     /**
167      * Checks some initial conditions based on the element to be refactored. The
168      * method is typically called by the UI to perform an initial checks after an
169      * action has been executed.
170      * <p>
171      * The refactoring has to be considered as not being executable if the returned status
172      * has the severity of <code>RefactoringStatus#FATAL</code>.
173      * </p>
174      * <p>
175      * This method can be called more than once.
176      * </p>
177      *
178      * @param pm a progress monitor to report progress. Although initial checks
179      * are supposed to execute fast, there can be certain situations where progress
180      * reporting is necessary. For example rebuilding a corrupted index may report
181      * progress.
182      *
183      * @return a refactoring status. If the status is <code>RefactoringStatus#FATAL</code>
184      * the refactoring has to be considered as not being executable.
185      *
186      * @throws CoreException if an exception occurred during initial condition checking.
187      * If this happens then the initial condition checking has to be interpreted as failed
188      *
189      * @throws OperationCanceledException if the condition checking got canceled
190      *
191      * @see #checkFinalConditions(IProgressMonitor)
192      * @see RefactoringStatus#FATAL
193      */
194     public abstract RefactoringStatus checkInitialConditions(IProgressMonitor pm) throws CoreException, OperationCanceledException;
195     
196     /**
197      * After <code>checkInitialConditions</code> has been performed and the user has
198      * provided all input necessary to perform the refactoring this method is called
199      * to check the remaining preconditions.
200      * <p>
201      * The refactoring has to be considered as not being executable if the returned status
202      * has the severity of <code>RefactoringStatus#FATAL</code>.
203      * </p>
204      * <p>
205      * This method can be called more than once.
206      * </p>
207      *
208      * @param pm a progress monitor to report progress
209      *
210      * @return a refactoring status. If the status is <code>RefactoringStatus#FATAL</code>
211      * the refactoring is considered as not being executable.
212      *
213      * @throws CoreException if an exception occurred during final condition checking
214      * If this happens then the final condition checking is interpreted as failed
215      *
216      * @throws OperationCanceledException if the condition checking got canceled
217      *
218      * @see #checkInitialConditions(IProgressMonitor)
219      * @see RefactoringStatus#FATAL
220      */
221     public abstract RefactoringStatus checkFinalConditions(IProgressMonitor pm) throws CoreException, OperationCanceledException;
222     
223     //---- change creation ------------------------------------------------------
224
225     /**
226      * Creates a {@link Change} object that performs the actual workspace
227      * transformation.
228      *
229      * @param pm a progress monitor to report progress
230      *
231      * @return the change representing the workspace modifications of the
232      * refactoring
233      *
234      * @throws CoreException if an error occurred while creating the change
235      *
236      * @throws OperationCanceledException if the condition checking got canceled
237      */
238     public abstract Change createChange(IProgressMonitor pm) throws CoreException, OperationCanceledException;
239     
240     /**
241      * {@inheritDoc}
242      */
243     public Object JavaDoc getAdapter(Class JavaDoc adapter) {
244         if (adapter.isInstance(this))
245             return this;
246         return super.getAdapter(adapter);
247     }
248     
249     /* (non-Javadoc)
250      * for debugging only
251      */
252     public String JavaDoc toString() {
253         return getName();
254     }
255 }
256
Popular Tags