org.eclipse.ltk.core.refactoring.participants
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 a
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.
-
Since:
- 3.0
-
See Also:
-
RefactoringProcessor,
ISharableParticipant
|
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
RefactoringParticipant
public RefactoringParticipant()
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 with -
element - the element to be refactored -
arguments - the refactoring arguments
-
Returns:
-
true if the participant could be initialized;
otherwise false is returned. If false 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 returns
false 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;
otherwise false 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 progress -
context - 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 a
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.
-
-
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 change
-
OperationCanceledException
- if the change creation got canceled -
Since:
- 3.4
-
See Also:
-
createChange(IProgressMonitor)
createChange
public abstract
Change createChange(
IProgressMonitor pm)
throws
CoreException,
OperationCanceledException
- Creates a
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).
-
-
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 change
-
OperationCanceledException
- if the change creation got canceled -
See Also:
-
createPreChange(IProgressMonitor)
getTextChange
public
TextChange getTextChange(
Object element)
- Returns the text change for the given element or
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.
-
-
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
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
