Package org.eclipse.ltk.core.refactoring.participants

Class 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

    • Constructor Detail

      • RefactoringParticipant

        public RefactoringParticipant()

    • 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 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