Eclipse Platform Release 3.7

## org.eclipse.ltk.core.refactoring.participants
Class RefactoringProcessor

    java.lang.Object
      org.eclipse.core.runtime.PlatformObject
          org.eclipse.ltk.core.refactoring.participants.RefactoringProcessor

All Implemented Interfaces:
  IAdaptable

Direct Known Subclasses:
  CopyProcessor, DeleteProcessor, MoveProcessor, RenameProcessor

    public abstract class RefactoringProcessor

extends PlatformObject

An abstract base class defining the protocol between a refactoring and its associated processor. The API is very similar to the one of a `Refactoring`. Implementors of this class should therefore study the interface of the refactoring class as well.

A refactoring processor is responsible for:

- refactoring the actual element. For example if a rename Java method refactoring is executed its associated processor provides the precondition checking for renaming a method and creates the change object describing the workspace modifications. This change object contains elementary changes to rename the Java method and to update all call sides of this method as well.
- loading all participants that want to participate in the refactoring. For example a Java method rename processor is responsible to load all participants that want to participate in a Java method rename.

A refactoring processor can not assume that all resources are saved before any methods are called on it. Therefore a processor must be able to deal with unsaved resources.

This class should be subclassed by clients wishing to provide special refactoring processors.

Since:
  3.0

Constructor Summary
`RefactoringProcessor()`

Method Summary
`abstract RefactoringStatus` `checkFinalConditions(IProgressMonitor pm, CheckConditionsContext context)` Checks the final conditions based on the element to be refactored.
`abstract RefactoringStatus` `checkInitialConditions(IProgressMonitor pm)` Checks some initial conditions based on the element to be refactored.
`abstract Change` `createChange(IProgressMonitor pm)` Creates a `Change` object describing the workspace modifications the processor contributes to the overall refactoring.
`abstract Object[]` `getElements()` Returns an array containing the elements to be refactored.
`abstract String` `getIdentifier()` Returns the unique identifier of the refactoring processor.
`abstract String` `getProcessorName()` Returns a human readable name.
`ProcessorBasedRefactoring` `getRefactoring()` Returns the associated refactoring.
`abstract boolean` `isApplicable()` Checks whether the processor is applicable to the elements to be refactored or not.
`abstract RefactoringParticipant[]` `loadParticipants(RefactoringStatus status, SharableParticipants sharedParticipants)` Returns the array of participants.
`Change` `postCreateChange(Change[] participantChanges, IProgressMonitor pm)` Additional hook allowing processors to add changes to the set of workspace modifications after all participant changes have been created.

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 Detail

### RefactoringProcessor

    public RefactoringProcessor()

Method Detail

### getRefactoring

    public ProcessorBasedRefactoring getRefactoring()

  Returns the associated refactoring. Returns `null` if the processor isn't associated with a refactoring yet.

  Returns:
    the associated refactoring
  Since:
    3.1

### getElements

    public abstract Object[] getElements()

  Returns an array containing the elements to be refactored. The concrete type of the elements depend on the concrete refactoring processor. For example a processor responsible for renaming Java methods returns the method to be renamed via this call.

  Returns:
    an array containing the elements to be refactored

### getIdentifier

    public abstract String getIdentifier()

  Returns the unique identifier of the refactoring processor. The identifier must not be `null`.

  Returns:
    a unique identifier.

### getProcessorName

    public abstract String getProcessorName()

  Returns a human readable name. The name will be displayed to users. The name must not be `null`.

  Returns:
    a human readable name

### isApplicable

    public abstract boolean isApplicable()
                                  throws CoreException

  Checks whether the processor is applicable to the elements to be refactored or not. If `false` is returned the processor is interpreted to be unusable.

  Returns:
    `true` if the processor is applicable to the elements; otherwise `false` is returned.
  Throws:
    `CoreException` - is the test fails. The processor is treated as unusable if this method throws an exception

### checkInitialConditions

    public abstract RefactoringStatus checkInitialConditions(IProgressMonitor pm)
                                                      throws CoreException,
                                                             OperationCanceledException

  Checks some initial conditions based on the element to be refactored.

  The refactoring using this processor is considered as not being executable if the returned status has the severity of `RefactoringStatus#FATAL`.

  This method can be called more than once.

  Parameters:
    `pm` - a progress monitor to report progress. Although availability checks are supposed to execute fast, there can be certain situations where progress reporting is necessary. For example rebuilding a corrupted index may report progress.
  Returns:
    a refactoring status. If the status is `RefactoringStatus#FATAL` the refactoring is considered as not being executable.
  Throws:
    `CoreException` - if an exception occurred during initial condition checking. If this happens, the initial condition checking is interpreted as failed.
    `OperationCanceledException` - if the condition checking got canceled
  See Also:
    `Refactoring.checkInitialConditions(IProgressMonitor)`, `RefactoringStatus.FATAL`

### checkFinalConditions

    public abstract RefactoringStatus checkFinalConditions(IProgressMonitor pm,
                                                           CheckConditionsContext context)
                                                    throws CoreException,
                                                           OperationCanceledException

  Checks the final conditions based on the element to be refactored.

  The refactoring using this processor is considered as not being executable if the returned status has the severity of `RefactoringStatus#FATAL`.

  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:
    `CoreException` - if an exception occurred during final condition checking. If this happens, the final condition checking is interpreted as failed.
    `OperationCanceledException` - if the condition checking got canceled
  See Also:
    `Refactoring.checkFinalConditions(IProgressMonitor)`, `RefactoringStatus.FATAL`

### createChange

    public abstract Change createChange(IProgressMonitor pm)
                                 throws CoreException,
                                        OperationCanceledException

  Creates a `Change` object describing the workspace modifications the processor contributes to the overall refactoring.

  Parameters:
    `pm` - a progress monitor to report progress
  Returns:
    the change representing the workspace modifications of the processor
  Throws:
    `CoreException` - if an error occurred while creating the change
    `OperationCanceledException` - if the condition checking got canceled
  See Also:
    `Refactoring.createChange(IProgressMonitor)`

### postCreateChange

    public Change postCreateChange(Change[] participantChanges,
                                   IProgressMonitor pm)
                            throws CoreException,
                                   OperationCanceledException

  Additional hook allowing processors to add changes to the set of workspace modifications after all participant changes have been created.

  Parameters:
    `participantChanges` - an array containing the changes created by the participants
    `pm` - a progress monitor to report progress
  Returns:
    change representing additional workspace modifications, or `null`
  Throws:
    `CoreException` - if an error occurred while creating the post change
    `OperationCanceledException` - if the condition checking got canceled
  See Also:
    `createChange(IProgressMonitor)`

### loadParticipants

    public abstract RefactoringParticipant[] loadParticipants(RefactoringStatus status,
                                                              SharableParticipants sharedParticipants)
                                                       throws CoreException

  Returns the array of participants. It is up to the implementor of a concrete processor to define which participants are loaded. In general, three different kinds of participants can be distinguished:
  - participants listening to the processed refactoring itself. For example if a Java field gets renamed all participants listening to Java field renames should be added via this hook.
  - participants listening to changes of derived elements. For example if a Java field gets renamed corresponding setter and getters methods are renamed as well. The setter and getter methods are considered as derived elements and the corresponding participants should be added via this hook.
  - participants listening to changes of a domain model different than the one that gets manipulated, but changed as a "side effect" of the refactoring. For example, renaming a package moves all its files to a different folder. If the package contains a HTML file then the rename package processor is supposed to load all move HTML file participants via this hook.

  Implementors are responsible to initialize the created participants with the right arguments. The method is called after `checkFinalConditions(IProgressMonitor, CheckConditionsContext)`has been called on the processor itself.

  Parameters:
    `status` - a refactoring status to report status if problems occur while loading the participants
    `sharedParticipants` - a list of sharable participants. Implementors of this method can simply pass this instance to the corresponding participant loading methods defined in `ParticipantManager`.
  Returns:
    an array of participants or `null` or an empty array if no participants are loaded
  Throws:
    `CoreException` - if creating or loading of the participants failed
  See Also:
    `ISharableParticipant`

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.