RefactoringProcessor


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.participants;
12  
13  import org.eclipse.core.runtime.Assert;
14  import org.eclipse.core.runtime.CoreException;
15  import org.eclipse.core.runtime.IProgressMonitor;
16  import org.eclipse.core.runtime.OperationCanceledException;
17  import org.eclipse.core.runtime.PlatformObject;
18  
19  import org.eclipse.ltk.core.refactoring.Change;
20  import org.eclipse.ltk.core.refactoring.RefactoringStatus;
21  
22  /**
23   * An abstract base class defining the protocol between a refactoring and
24   * its associated processor. The API is very similar to the one of a 
25   * {@link org.eclipse.ltk.core.refactoring.Refactoring}. Implementors of
26   * this class should therefore study the interface of the refactoring class
27   * as well.
28   * <p>
29   * A refactoring processor is responsible for:
30   * <ul>
31   *   <li>refactoring the actual element. For example if a rename Java method
32   *       refactoring is executed its associated processor provides the 
33   *       precondition checking for renaming a method and creates the change
34   *       object describing the workspace modifications. This change object
35   *       contains elementary changes to rename the Java method and
36   *       to update all call sides of this method as well.</li>
37   *   <li>loading all participants that want to participate in the refactoring.
38   *       For example a Java method rename processor is responsible to load
39   *       all participants that want to participate in a Java method rename.</li>
40   * </ul>
41   * </p>
42   * <p>
43   * A refactoring processor can not assume that all resources are saved before
44   * any methods are called on it. Therefore a processor must be able to deal with
45   * unsaved resources.
46   * </p>
47   * <p>
48   * This class should be subclassed by clients wishing to provide special refactoring 
49   * processors.
50   * </p>
51   * 
52   * @since 3.0
53   */
54  public abstract class RefactoringProcessor extends PlatformObject {
55  
56      private ProcessorBasedRefactoring fRefactoring;
57      
58      /**
59       * Set the owning refactoring.
60       * 
61       * @param refactoring the refactoring
62       *
63       * @since 3.1
64       */
65      /* package */ void setRefactoring(ProcessorBasedRefactoring refactoring) {
66          Assert.isTrue(fRefactoring == null, "The refactoring can only be set once"); //$NON-NLS-1$
67          Assert.isNotNull(refactoring);
68          fRefactoring= refactoring;
69      }
70      
71      /**
72       * Returns the associated refactoring. Returns <code>null</code> if the 
73       * processor isn't associated with a refactoring yet.
74       * 
75       * @return the associated refactoring
76       *
77       * @since 3.1
78       */
79      public ProcessorBasedRefactoring getRefactoring() {
80          return fRefactoring;
81      }
82      
83      /**
84       * Returns an array containing the elements to be refactored. The concrete
85       * type of the elements depend on the concrete refactoring processor. For
86       * example a processor responsible for renaming Java methods returns the
87       * method to be renamed via this call.
88       * 
89       * @return an array containing the element to be refactored
90       */
91      public abstract Object  [] getElements();
92  
93      /**
94       * Returns the unique identifier of the refactoring processor. The
95       * identifier must not be <code>null</code>.
96       * 
97       * @return a unique identifier.
98       */
99      public abstract String   getIdentifier();
100 
101     /**
102      * Returns a human readable name. The name will be displayed to users. The
103      * name must not be <code>null</code>.
104      * 
105      * @return a human readable name
106      */
107     public abstract String   getProcessorName();
108 
109     /**
110      * Checks whether the processor is applicable to the elements to be
111      * refactored or not. If <code> false</code> is returned the processor is
112      * interpreted to be unusable.
113      * 
114      * @return <code>true</code> if the processor is applicable to the
115      *         elements; otherwise <code>false</code> is returned.
116      * @throws CoreException is the test fails. The processor is treated as
117      *  unusable if this method throws an exception
118      */
119     public abstract boolean isApplicable() throws CoreException;
120 
121     /**
122      * Checks some initial conditions based on the element to be refactored.
123      * <p>
124      * The refactoring using this processor is considered as not being
125      * executable if the returned status has the severity of
126      * <code>RefactoringStatus#FATAL</code>.
127      * </p>
128      * <p>
129      * This method can be called more than once.
130      * </p>
131      * 
132      * @param pm a progress monitor to report progress. Although availability
133      *        checks are supposed to execute fast, there can be certain
134      *        situations where progress reporting is necessary. For example
135      *        rebuilding a corrupted index may report progress.
136      * 
137      * @return a refactoring status. If the status is <code>RefactoringStatus#FATAL</code> 
138      *  the refactoring is considered as not being executable.
139      * 
140      * @throws CoreException if an exception occurred during initial condition
141      *         checking. If this happens the initial condition checking is
142      *         interpreted as failed.
143      * 
144      * @throws OperationCanceledException if the condition checking got canceled
145      * 
146      * @see org.eclipse.ltk.core.refactoring.Refactoring#checkInitialConditions(IProgressMonitor)
147      * @see RefactoringStatus#FATAL
148      */
149     public abstract RefactoringStatus checkInitialConditions(IProgressMonitor pm) throws CoreException, OperationCanceledException;
150 
151     /**
152      * Checks the final conditions based on the element to be refactored.
153      * <p>
154      * The refactoring using this processor is considered as not being
155      * executable if the returned status has the severity of
156      * <code>RefactoringStatus#FATAL</code>.
157      * </p>
158      * <p>
159      * This method can be called more than once.
160      * </p>
161      * 
162      * @param pm a progress monitor to report progress
163      * @param context a condition checking context to collect shared condition checks
164      * 
165      * @return a refactoring status. If the status is <code>RefactoringStatus#FATAL</code> 
166      *  the refactoring is considered as not being executable.
167      * 
168      * @throws CoreException if an exception occurred during final condition
169      *  checking. If this happens the final condition checking is interpreted as failed.
170      * 
171      * @throws OperationCanceledException if the condition checking got canceled
172      * 
173      * @see org.eclipse.ltk.core.refactoring.Refactoring#checkFinalConditions(IProgressMonitor)
174      * @see RefactoringStatus#FATAL
175      */
176     public abstract RefactoringStatus checkFinalConditions(IProgressMonitor pm, CheckConditionsContext context)
177         throws CoreException, OperationCanceledException;
178 
179     /**
180      * Creates a {@link Change} object describing the workspace modifications
181      * the processor contributes to the overall refactoring.
182      * 
183      * @param pm a progress monitor to report progress
184      * 
185      * @return the change representing the workspace modifications of the
186      *  processor
187      * 
188      * @throws CoreException if an error occurred while creating the change
189      * 
190      * @throws OperationCanceledException if the condition checking got canceled
191      * 
192      * @see org.eclipse.ltk.core.refactoring.Refactoring#createChange(IProgressMonitor)
193      */
194     public abstract Change createChange(IProgressMonitor pm) throws CoreException, OperationCanceledException;
195 
196     /**
197      * Additional hook allowing processors to add changes to the set of workspace
198      * modifications after all participant changes have been created.
199      * 
200      * @param participantChanges an array containing the changes created by the
201      *  participants
202      * @param pm a progress monitor to report progress
203      * 
204      * @return change representing additional workspace modifications, or <code>null</code>
205      * 
206      * @throws CoreException if an error occurred while creating the post change
207      * 
208      * @throws OperationCanceledException if the condition checking got canceled
209      * 
210      * @see #createChange(IProgressMonitor)
211      */
212     public Change postCreateChange(Change[] participantChanges, IProgressMonitor pm) throws CoreException, OperationCanceledException {
213         return null;
214     }
215     
216     /**
217      * Returns the array of participants. It is up to the implementor of a
218      * concrete processor to define which participants are loaded. In general,
219      * three different kinds of participants can be distinguished:
220      * <ul>
221      *   <li>participants listening to the processed refactoring itself. For
222      *       example if a Java field gets renamed all participants listening
223      *       to Java field renames should be added via this hook.</li>
224      *   <li>participants listening to changes of derived elements. For example
225      *       if a Java field gets renamed corresponding setter and getters methods 
226      *       are renamed as well. The setter and getter methods are considered as 
227      *       derived elements and the corresponding participants should be added via 
228      *       this hook.</li>
229      *   <li>participants listening to changes of a domain model different than
230      *       the one that gets manipulated, but changed as a "side effect" of the
231      *       refactoring. For example, renaming a package moves all its files to a
232      *       different folder. If the package contains a HTML file then the rename
233      *       package processor is supposed to load all move HTML file participants 
234      *       via this hook.</li>
235      * </ul>
236      * <p>
237      * Implementors are responsible to initialize the created participants with
238      * the right arguments. The method is called after
239      * {@link #checkFinalConditions(IProgressMonitor, CheckConditionsContext)}has 
240      * been called on the processor itself.
241      * </p>
242      * @param status a refactoring status to report status if problems occur while
243      *  loading the participants
244      * @param sharedParticipants a list of sharable participants. Implementors of
245      *  this method can simply pass this instance to the corresponding participant
246      *  loading methods defined in {@link ParticipantManager}.  
247      * 
248      * @return an array of participants or <code>null</code> or an empty array
249      *  if no participants are loaded
250      * 
251      * @throws CoreException if creating or loading of the participants failed
252      * 
253      * @see ISharableParticipant
254      */
255     public abstract RefactoringParticipant[] loadParticipants(RefactoringStatus status, SharableParticipants sharedParticipants) throws CoreException;
256 }
257
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags