Class RefactoringParticipant
- java.lang.Object
-
- org.eclipse.core.runtime.PlatformObject
-
- org.eclipse.ltk.core.refactoring.participants.RefactoringParticipant
-
- All Implemented Interfaces:
IAdaptable
- Direct Known Subclasses:
CopyParticipant
,CreateParticipant
,DeleteParticipant
,MoveParticipant
,RenameParticipant
public abstract class RefactoringParticipant extends PlatformObject
A refactoring participant can participate in the condition checking and change creation of aRefactoringProcessor
.If the severity of the condition checking result is
RefactoringStatus.FATAL
then the whole refactoring will not be carried out.The changes created by a participant MUST not conflict with any changes provided by other participants or the refactoring itself. To ensure this, a participant is only allowed to manipulate resources belonging to its domain. As of 3.1 this got relaxed for textual resources. A participant can now change a textual resource already manipulated by the processor as long as both are manipulating different regions in the file (see
createChange(IProgressMonitor)
andgetTextChange(Object)
). For example a rename type participant updating launch configuration is only allowed to update launch configurations or shared textual resources. If a change conflicts with another change during execution then the participant who created the change will be disabled for the rest of the eclipse session.A refactoring participant can not assume that all resources are saved before any methods are called on it. Therefore a participant must be able to deal with unsaved resources.
A refactoring participant can implement
ISharableParticipant
in order to be shared for multiple elements to be refactored by the same processor.This class should be subclassed by clients wishing to provide special refactoring participants extension points.
Since 3.4, a refactoring participant can also override
createPreChange(IProgressMonitor)
to add changes that will be executed before the main refactoring changes are executed.- Since:
- 3.0
- See Also:
RefactoringProcessor
,ISharableParticipant
-
-
Constructor Summary
Constructors Constructor Description RefactoringParticipant()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract RefactoringStatus
checkConditions(IProgressMonitor pm, CheckConditionsContext context)
Checks the conditions of the refactoring participant.abstract Change
createChange(IProgressMonitor pm)
Creates aChange
object that contains the workspace modifications of this participant to be executed after the changes from the refactoring are executed.Change
createPreChange(IProgressMonitor pm)
Creates aChange
object that contains the workspace modifications of this participant to be executed before the changes from the refactoring are executed.abstract String
getName()
Returns a human readable name of this participant.RefactoringProcessor
getProcessor()
Returns the processor that is associated with this participant.TextChange
getTextChange(Object element)
Returns the text change for the given element ornull
if a text change doesn't exist.protected abstract boolean
initialize(Object element)
Initializes the participant with the element to be refactored.protected abstract void
initialize(RefactoringArguments arguments)
Initializes the participant with the refactoring argumentsboolean
initialize(RefactoringProcessor processor, Object element, RefactoringArguments arguments)
Initializes the participant.-
Methods inherited from class org.eclipse.core.runtime.PlatformObject
getAdapter
-
-
-
-
Method Detail
-
getProcessor
public RefactoringProcessor getProcessor()
Returns the processor that is associated with this participant.- Returns:
- the processor that is associated with this participant
-
initialize
public boolean initialize(RefactoringProcessor processor, Object element, RefactoringArguments arguments)
Initializes the participant. This method is called by the framework when a participant gets instantiated.This method isn't intended to be extended or reimplemented by clients.
- Parameters:
processor
- the processor this participant is associated withelement
- the element to be refactoredarguments
- the refactoring arguments- Returns:
true
if the participant could be initialized; otherwisefalse
is returned. Iffalse
is returned then the participant will not be added to the refactoring.- See Also:
initialize(Object)
-
initialize
protected abstract boolean initialize(Object element)
Initializes the participant with the element to be refactored. If this method returnsfalse
then the framework will consider the participant as not being initialized and the participant will be dropped by the framework.- Parameters:
element
- the element to be refactored- Returns:
true
if the participant could be initialized; otherwisefalse
is returned.
-
initialize
protected abstract void initialize(RefactoringArguments arguments)
Initializes the participant with the refactoring arguments- Parameters:
arguments
- the refactoring arguments
-
getName
public abstract String getName()
Returns a human readable name of this participant.- Returns:
- a human readable name
-
checkConditions
public abstract RefactoringStatus checkConditions(IProgressMonitor pm, CheckConditionsContext context) throws OperationCanceledException
Checks the conditions of the refactoring participant.The refactoring is considered as not being executable if the returned status has the severity of
RefactoringStatus#FATAL
. Note that this blocks the whole refactoring operation!Clients should use the passed
CheckConditionsContext
to validate the changes they generate. If the generated changes include workspace resource modifications, clients should call ...(ResourceChangeChecker) context.getChecker(ResourceChangeChecker.class); IResourceChangeDescriptionFactory deltaFactory= checker.getDeltaFactory();
... and use the delta factory to describe all resource modifications in advance.
This method can be called more than once.
- Parameters:
pm
- a progress monitor to report progresscontext
- a condition checking context to collect shared condition checks- Returns:
- a refactoring status. If the status is
RefactoringStatus#FATAL
the refactoring is considered as not being executable. - Throws:
OperationCanceledException
- if the condition checking got canceled- See Also:
Refactoring.checkInitialConditions(IProgressMonitor)
,RefactoringStatus
-
createPreChange
public Change createPreChange(IProgressMonitor pm) throws CoreException, OperationCanceledException
Creates aChange
object that contains the workspace modifications of this participant to be executed before the changes from the refactoring are executed. Note that this implies that the undo change of the returned Change object will be executed after the undo changes from the refactoring have been executed.The changes provided by a participant must not conflict with any change provided by other participants or by the refactoring itself.
If the change conflicts with any change provided by other participants or by the refactoring itself, then change execution will fail and the participant will be disabled for the rest of the eclipse session.
If an exception occurs while creating the change, the refactoring can not be carried out, and the participant will be disabled for the rest of the eclipse session.
A participant can manipulate text resource already manipulated by the processor as long as the textual manipulations don't conflict (e.g. the participant manipulates a different region of the text resource). The method must not return those changes in its change tree since the change is already part of another change tree. If the participant only manipulates shared changes then it can return
null
to indicate that it didn't create own changes. A shared text change can be accessed via the methodgetTextChange(Object)
.The default implementation returns
null
. Subclasses can extend or override.Note that most refactorings will implement
createChange(IProgressMonitor)
rather than this method.- Parameters:
pm
- a progress monitor to report progress- Returns:
- the change representing the workspace modifications to be executed
before the refactoring change or
null
if no changes are made - Throws:
CoreException
- if an error occurred while creating the changeOperationCanceledException
- if the change creation got canceled- Since:
- 3.4
- See Also:
createChange(IProgressMonitor)
-
createChange
public abstract Change createChange(IProgressMonitor pm) throws CoreException, OperationCanceledException
Creates aChange
object that contains the workspace modifications of this participant to be executed after the changes from the refactoring are executed. Note that this implies that the undo change of the returned Change object will be executed before the undo changes from the refactoring have been executed.The changes provided by a participant must not conflict with any change provided by other participants or by the refactoring itself.
If the change conflicts with any change provided by other participants or by the refactoring itself, then change execution will fail and the participant will be disabled for the rest of the eclipse session.
If an exception occurs while creating the change, the refactoring can not be carried out, and the participant will be disabled for the rest of the eclipse session.
As of 3.1, a participant can manipulate text resources already manipulated by the processor as long as the textual manipulations don't conflict (i.e. the participant manipulates a different region of the text resource). The method must not return those changes in its change tree since the change is already part of another change tree. If the participant only manipulates shared changes, then it can return
null
to indicate that it didn't create own changes. A shared text change can be accessed via the methodgetTextChange(Object)
.- Parameters:
pm
- a progress monitor to report progress- Returns:
- the change representing the workspace modifications to be executed
after the refactoring change or
null
if no changes are made - Throws:
CoreException
- if an error occurred while creating the changeOperationCanceledException
- if the change creation got canceled- See Also:
createPreChange(IProgressMonitor)
-
getTextChange
public TextChange getTextChange(Object element)
Returns the text change for the given element ornull
if a text change doesn't exist. This method only returns a valid result during change creation. Outside of change creation alwaysnull
is returned.- Parameters:
element
- the element to be modified for which a text change is requested- Returns:
- the text change or
null
if no text change exists for the element - Since:
- 3.1
-
-