RefactoringParticipant


1   /*******************************************************************************
2    * Copyright (c) 2000, 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.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  import org.eclipse.ltk.core.refactoring.TextChange;
22  
23  import org.eclipse.ltk.internal.core.refactoring.ParticipantDescriptor;
24  
25  /**
26   * A refactoring participant can participate in the condition checking and
27   * change creation of a refactoring processor.
28   * <p>
29   * If the severity of the condition checking result is {@link RefactoringStatus#FATAL}
30   * then the whole refactoring will not be carried out. 
31   * </p>
32   * <p>
33   * The change created from a participant <em>MUST</em> not conflict with any changes
34   * provided by other participants or the refactoring itself. To ensure this a participant
35   * is only allowed to manipulate resources belonging to its domain. As of 3.1 this got
36   * relaxed for textual resources. A participant can now change a textual resource already
37   * manipulated by the processor as long as both are manipulating different regions in the
38   * file (see {@link #createChange(IProgressMonitor)} and {@link #getTextChange(Object)}). 
39   * For example a rename type participant updating launch configuration is only allowed to 
40   * update launch configurations or shared textual resources. If a change conflicts with 
41   * another change during execution then the participant who created the change will be 
42   * disabled for the rest of the eclipse session.
43   * </p>
44   * <p>
45   * A refactoring participant can not assume that all resources are saved before any 
46   * methods are called on it. Therefore a participant must be able to deal with unsaved
47   * resources.
48   * </p>
49   * <p>
50   * This class should be subclassed by clients wishing to provide special refactoring 
51   * participants extension points.
52   * </p>
53   * 
54   * @see org.eclipse.ltk.core.refactoring.participants.RefactoringProcessor
55   * 
56   * @since 3.0
57   */
58  public abstract class RefactoringParticipant extends PlatformObject {
59      
60      private RefactoringProcessor fProcessor;
61      
62      private ParticipantDescriptor fDescriptor;
63      
64      /**
65       * Returns the processor that is associated with this participant. 
66       * 
67       * @return the processor that is associated with this participant
68       */
69      public RefactoringProcessor getProcessor() {
70          return fProcessor;
71      }
72      
73      /**
74       * Initializes the participant. This method is called by the framework when a
75       * participant gets instantiated. 
76       * <p>
77       * This method isn't intended to be extended or reimplemented by clients.
78       * </p>
79       * @param processor the processor this participant is associated with
80       * @param element the element to be refactored
81       * @param arguments the refactoring arguments
82       * 
83       * @return <code>true</code> if the participant could be initialized;
84       *  otherwise <code>false</code> is returned. If <code>false</code> is
85       *  returned then the participant will not be added to the refactoring. 
86       * 
87       * @see #initialize(Object)
88       */
89      public boolean initialize(RefactoringProcessor processor, Object   element, RefactoringArguments arguments) {
90          Assert.isNotNull(processor);
91          Assert.isNotNull(arguments);
92          fProcessor= processor;
93          initialize(arguments);
94          return initialize(element);
95      }
96      
97      /**
98       * Initializes the participant with the element to be refactored.
99       * If this method returns <code>false</code> then the framework
100      * will consider the participant as not being initialized and the 
101      * participant will be dropped by the framework.
102      * 
103      * @param element the element to be refactored
104      * 
105      * @return <code>true</code> if the participant could be initialized;
106      *  otherwise <code>false</code> is returned.
107      */
108     protected abstract boolean initialize(Object   element);
109     
110     /**
111      * Initializes the participant with the refactoring arguments
112      * 
113      * @param arguments the refactoring arguments
114      */
115     protected abstract void initialize(RefactoringArguments arguments);
116     
117     /**
118      * Returns a human readable name of this participant.
119      * 
120      * @return a human readable name
121      */
122     public abstract String   getName();
123     
124     /**
125      * Checks the conditions of the refactoring participant. 
126      * <p>
127      * The refactoring is considered as not being executable if the returned status
128      * has the severity of <code>RefactoringStatus#FATAL</code>.
129      * </p>
130      * <p>
131      * This method can be called more than once.
132      * </p>
133      * 
134      * @param pm a progress monitor to report progress
135      * @param context a condition checking context to collect shared condition checks
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 OperationCanceledException if the condition checking got canceled
141      * 
142      * @see org.eclipse.ltk.core.refactoring.Refactoring#checkInitialConditions(IProgressMonitor)
143      * @see RefactoringStatus#FATAL
144      */         
145     public abstract RefactoringStatus checkConditions(IProgressMonitor pm, CheckConditionsContext context) throws OperationCanceledException;
146     
147     /**
148      * Creates a {@link Change}object that contains the workspace modifications
149      * of this participant. The changes provided by a participant <em>must</em>
150      * not conflict with any change provided by other participants or by the
151      * refactoring itself.
152      * <p>
153      * If the change conflicts with any change provided by other participants or
154      * by the refactoring itself then change execution will fail and the
155      * participant will be disabled for the rest of the eclipse session.
156      * </p>
157      * <p>
158      * If an exception occurs while creating the change the refactoring can not
159      * be carried out and the participant will be disabled for the rest of the
160      * eclipse session.
161      * </p>
162      * <p>
163      * As of 3.1 a participant can manipulate text resource already manipulated by
164      * the processor as long as the textual manipulations don't conflict (e.g.
165      * the participant manipulates a different region of the text resource).
166      * The method must not return those changes in its change tree since the change 
167      * is already part of another change tree. If the participant only manipulates 
168      * shared changes then it can return <code>null</code> to indicate that it didn't
169      * create own changes. A shared text change can be access via the method 
170      * {@link #getTextChange(Object)}. 
171      * </p>
172      * 
173      * @param pm a progress monitor to report progress
174      * 
175      * @return the change representing the workspace modifications or <code>null</code>
176      *  if no changes are made
177      * 
178      * @throws CoreException if an error occurred while creating the change
179      * 
180      * @throws OperationCanceledException if the condition checking got canceled
181      */
182     public abstract Change createChange(IProgressMonitor pm) throws CoreException, OperationCanceledException;
183 
184     /**
185      * Returns the text change for the given element or <code>null</code>
186      * if a text change doesn't exist. This method only returns a valid
187      * result during change creation. Outside of change creation always
188      * <code>null</code> is returned.
189      * 
190      * @param element the element to be modified for which a text change
191      *  is requested
192      *  
193      * @return the text change or <code>null</code> if no text change exists
194      *  for the element
195      *  
196      *  @since 3.1
197      */
198     public TextChange getTextChange(Object   element) {
199         return getProcessor().getRefactoring().getTextChange(element);
200     }
201     
202     //---- helper method ----------------------------------------------------
203     
204     /* package */ void setDescriptor(ParticipantDescriptor descriptor) {
205         Assert.isNotNull(descriptor);
206         fDescriptor= descriptor;
207     }
208     
209     /* package */ ParticipantDescriptor getDescriptor() {
210         return fDescriptor;
211     }
212 }
213
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags