Package 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`

## Constructor Summary

Constructors
Constructor
Description
`RefactoringParticipant()`

## Method Summary

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

### Methods inherited from class org.eclipse.core.runtime.PlatformObject

`getAdapter`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### RefactoringParticipant

public RefactoringParticipant()

## Method Details

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