public abstract class RefactoringParticipant extends PlatformObject
RefactoringProcessor
.
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)
and getTextChange(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.
RefactoringProcessor
,
ISharableParticipant
Constructor and Description |
---|
RefactoringParticipant() |
Modifier and Type | Method and Description |
---|---|
abstract RefactoringStatus |
checkConditions(IProgressMonitor pm,
CheckConditionsContext context)
Checks the conditions of the refactoring participant.
|
abstract Change |
createChange(IProgressMonitor pm)
Creates a
Change 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 a
Change 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 or
null
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 arguments
|
boolean |
initialize(RefactoringProcessor processor,
Object element,
RefactoringArguments arguments)
Initializes the participant.
|
getAdapter
public RefactoringProcessor getProcessor()
public boolean initialize(RefactoringProcessor processor, Object element, RefactoringArguments arguments)
This method isn't intended to be extended or reimplemented by clients.
processor
- the processor this participant is associated withelement
- the element to be refactoredarguments
- the refactoring argumentstrue
if the participant could be initialized;
otherwise false
is returned. If false
is
returned then the participant will not be added to the refactoring.initialize(Object)
protected abstract boolean initialize(Object element)
false
then the framework
will consider the participant as not being initialized and the
participant will be dropped by the framework.element
- the element to be refactoredtrue
if the participant could be initialized;
otherwise false
is returned.protected abstract void initialize(RefactoringArguments arguments)
arguments
- the refactoring argumentspublic abstract String getName()
public abstract RefactoringStatus checkConditions(IProgressMonitor pm, CheckConditionsContext context) throws OperationCanceledException
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.
pm
- a progress monitor to report progresscontext
- a condition checking context to collect shared condition checksRefactoringStatus#FATAL
the refactoring is considered as not being executable.OperationCanceledException
- if the condition checking got canceledRefactoring.checkInitialConditions(IProgressMonitor)
,
RefactoringStatus
public Change createPreChange(IProgressMonitor pm) throws CoreException, OperationCanceledException
Change
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 method
getTextChange(Object)
.
The default implementation returns null
. Subclasses can extend or override.
Note that most refactorings will implement createChange(IProgressMonitor)
rather than this method.
pm
- a progress monitor to report progressnull
if no changes are madeCoreException
- if an error occurred while creating the changeOperationCanceledException
- if the change creation got canceledcreateChange(IProgressMonitor)
public abstract Change createChange(IProgressMonitor pm) throws CoreException, OperationCanceledException
Change
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 method
getTextChange(Object)
.
pm
- a progress monitor to report progressnull
if no changes are madeCoreException
- if an error occurred while creating the changeOperationCanceledException
- if the change creation got canceledcreatePreChange(IProgressMonitor)
public TextChange getTextChange(Object element)
null
if a text change doesn't exist. This method only returns a valid
result during change creation. Outside of change creation always
null
is returned.element
- the element to be modified for which a text change
is requestednull
if no text change exists
for the element
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.