Eclipse Platform Release 3.7

## org.eclipse.ltk.ui.refactoring.history
Class RefactoringHistoryWizard

    java.lang.Object
      org.eclipse.jface.wizard.Wizard
          org.eclipse.ltk.ui.refactoring.history.RefactoringHistoryWizard

All Implemented Interfaces:
  IWizard

    public class RefactoringHistoryWizard

extends Wizard

A default implementation of a refactoring history wizard. Refactoring history wizards are used to execute the refactorings described by a refactoring history. A refactoring history wizard differs from a normal wizard in the following characteristics:

- A refactoring history wizard consists of a sequence of one error page to present the outcome of a refactoring's condition checking and one preview page to present a preview of the workspace changes.
- Refactorings are applied to the workspace as soon as a preview has been accepted. Additionally, refactoring history wizards support the headless execution of refactorings. The user guided execution of a refactoring history triggers a series of error pages and preview pages. Within this sequence of pages, going back is not supported anymore. However, canceling the refactoring history wizard will undo the already performed refactorings.

A refactoring history wizard is usually opened using the `WizardDialog`. Clients must ensure that the calling thread holds the workspace lock.

Note: this class is intended to be extended by clients.

Since:
  3.2
See Also:
  `Refactoring`, `RefactoringHistory`

Field Summary
`static int` `STATUS_CODE_INTERRUPTED` The status code representing an interrupted operation.

Fields inherited from class org.eclipse.jface.wizard.Wizard
`DEFAULT_IMAGE`

Constructor Summary
`RefactoringHistoryWizard(boolean overview, String caption, String title, String description)` Creates a new refactoring history wizard.
`RefactoringHistoryWizard(String caption, String title, String description)` Creates a new refactoring history wizard.

Method Summary
`protected RefactoringStatus` `aboutToPerformHistory(IProgressMonitor monitor)` Hook method which is called before the first refactoring of the history is executed.
`protected RefactoringStatus` `aboutToPerformRefactoring(Refactoring refactoring, RefactoringDescriptor descriptor, IProgressMonitor monitor)` Hook method which is called before the a refactoring of the history is executed.
`void` `addPage(IWizardPage page)` Adds a new page to this wizard. Clients must contribute their wizard pages by re-implementing `addUserDefinedPages()`.
`void` `addPages()` The `Wizard` implementation of this `IWizard` method does nothing.
`protected void` `addUserDefinedPages()` Adds user defined wizard pages in front of the wizard.
`boolean` `canFinish()` Returns whether this wizard could be finished without further user interaction.
`protected Refactoring` `createRefactoring(RefactoringDescriptor descriptor, RefactoringStatus status)` Method which is called to create a refactoring instance from a refactoring descriptor.
`protected Refactoring` `createRefactoring(RefactoringDescriptor descriptor, RefactoringStatus status, IProgressMonitor monitor)` Creates a refactoring from the specified refactoring descriptor.
`void` `dispose()` The `Wizard` implementation of this `IWizard` method disposes all the pages controls using `DialogPage.dispose`.
`org.eclipse.ltk.internal.ui.refactoring.IErrorWizardPage` `getErrorPage()` Returns the error wizard page.
`IWizardPage` `getNextPage(IWizardPage page)` Returns the successor of the given page.
`org.eclipse.ltk.internal.ui.refactoring.IPreviewWizardPage` `getPreviewPage()` Returns the preview wizard page.
`IWizardPage` `getPreviousPage(IWizardPage page)` Returns the predecessor of the given page.
`protected RefactoringStatus` `historyPerformed(IProgressMonitor monitor)` Hook method which is called when all refactorings of the history have been executed.
`boolean` `performCancel()` The `Wizard` implementation of this `IWizard` method does nothing and returns `true`.
`boolean` `performFinish()` Subclasses must implement this `IWizard` method to perform any special finish processing for their wizard.
`RefactoringStatus` `performPreviewChange(Change change, Refactoring refactoring)` Performs the change previously displayed in the preview.
`protected RefactoringStatus` `refactoringPerformed(Refactoring refactoring, IProgressMonitor monitor)` Hook method which is called when the specified refactoring has been performed, e.g. its change object has been successfully applied to the workspace.
`protected boolean` `selectPreviewChange(Change change)` Hook method which is called for each change before it is displayed in a preview page.
`protected boolean` `selectStatusEntry(RefactoringStatusEntry entry)` Hook method which is called for each status entry before it is displayed in a wizard page.
`void` `setConfiguration(RefactoringHistoryControlConfiguration configuration)` Sets the refactoring history control configuration.
`void` `setInput(RefactoringHistory history)` Sets the refactoring history.

Methods inherited from class org.eclipse.jface.wizard.Wizard

`createPageControls, getContainer, getDefaultPageImage, getDialogSettings, getPage, getPageCount, getPages, getShell, getStartingPage, getTitleBarColor, getWindowTitle, isHelpAvailable, needsPreviousAndNextButtons, needsProgressMonitor, setContainer, setDefaultPageImageDescriptor, setDialogSettings, setForcePreviousAndNextButtons, setHelpAvailable, setNeedsProgressMonitor, setTitleBarColor, setWindowTitle`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### STATUS_CODE_INTERRUPTED

    public static final int STATUS_CODE_INTERRUPTED

  The status code representing an interrupted operation.

  Note: This API must not be used from outside the refactoring framework.

  See Also:
    Constant Field Values

Constructor Detail

### RefactoringHistoryWizard

    public RefactoringHistoryWizard(boolean overview,
                                    String caption,
                                    String title,
                                    String description)

  Creates a new refactoring history wizard.

  Clients must ensure that the refactoring history and the refactoring history control configuration are set before opening the wizard in a dialog.

  Parameters:
    `overview` - `true` to show an overview of the refactorings, `false` otherwise
    `caption` - the caption of the wizard window
    `title` - the title of the overview page
    `description` - the description of the overview page
  See Also:
    `setConfiguration(RefactoringHistoryControlConfiguration)`, `setInput(RefactoringHistory)`

### RefactoringHistoryWizard

    public RefactoringHistoryWizard(String caption,
                                    String title,
                                    String description)

  Creates a new refactoring history wizard.

  Clients must ensure that the refactoring history and the refactoring history control configuration are set before opening the wizard in a dialog.

  Calling his constructor is equivalent to `RefactoringHistoryWizard(boolean, String, String, String)` with the first argument equal to `true`.

  Parameters:
    `caption` - the caption of the wizard window
    `title` - the title of the overview page
    `description` - the description of the overview page
  See Also:
    `setConfiguration(RefactoringHistoryControlConfiguration)`, `setInput(RefactoringHistory)`

Method Detail

### aboutToPerformHistory

    protected RefactoringStatus aboutToPerformHistory(IProgressMonitor monitor)

  Hook method which is called before the first refactoring of the history is executed. This method may be called from non-UI threads.

  This method is guaranteed to be called exactly once during the lifetime of a refactoring history wizard. The default implementation does nothing and returns a refactoring status of severity `RefactoringStatus.OK`.

  Subclasses may reimplement this method to perform any special processing.

  Returning a status of severity `RefactoringStatus.FATAL` will terminate the execution of the refactorings.

  Parameters:
    `monitor` - the progress monitor to use
  Returns:
    a status describing the outcome of the operation

### aboutToPerformRefactoring

    protected RefactoringStatus aboutToPerformRefactoring(Refactoring refactoring,
                                                          RefactoringDescriptor descriptor,
                                                          IProgressMonitor monitor)

  Hook method which is called before the a refactoring of the history is executed. The refactoring itself is in an initialized state at the time of the method call. The default implementation does nothing and returns a status of severity `RefactoringStatus.OK`. This method may be called from non-UI threads.

  Subclasses may extend this method to perform any special processing.

  Returning a status of severity `RefactoringStatus.FATAL` will terminate the execution of the current refactoring.

  Parameters:
    `refactoring` - the refactoring about to be executed
    `descriptor` - the refactoring descriptor
    `monitor` - the progress monitor to use
  Returns:
    a status describing the outcome of the initialization

### addPage

    public final void addPage(IWizardPage page)

  Adds a new page to this wizard. The page is inserted at the end of the page list. Clients must contribute their wizard pages by re-implementing `addUserDefinedPages()`.

  Overrides:
    `addPage` in class `Wizard`
  Parameters:
    `page` - the new page

### addPages

    public final void addPages()

  The `Wizard` implementation of this `IWizard` method does nothing. Subclasses should extend if extra pages need to be added before the wizard opens. New pages should be added by calling `addPage`.

  Specified by:
    `addPages` in interface `IWizard`
  Overrides:
    `addPages` in class `Wizard`

### addUserDefinedPages

    protected void addUserDefinedPages()

  Adds user defined wizard pages in front of the wizard.

  Clients may extend this method to add custom wizard pages in front of the wizard.

### canFinish

    public boolean canFinish()

  Returns whether this wizard could be finished without further user interaction.

  The result of this method is typically used by the wizard container to enable or disable the Finish button.

  Specified by:
    `canFinish` in interface `IWizard`
  Overrides:
    `canFinish` in class `Wizard`
  Returns:
    `true` if the wizard could be finished, and `false` otherwise

### createRefactoring

    protected Refactoring createRefactoring(RefactoringDescriptor descriptor,
                                            RefactoringStatus status)
                                     throws CoreException

  Method which is called to create a refactoring instance from a refactoring descriptor. The refactoring must be in an initialized state after the return of the method call. The default implementation delegates the task to the refactoring descriptor. This method may be called from non-UI threads.

  Subclasses may reimplement this method to customize the initialization of a refactoring.

  Parameters:
    `descriptor` - the refactoring descriptor
    `status` - a refactoring status describing the outcome of the initialization
  Returns:
    the refactoring, or `null` if this refactoring descriptor represents the unknown refactoring, or if no refactoring contribution is available for this refactoring descriptor
  Throws:
    `CoreException` - if an error occurs while creating the refactoring instance

### createRefactoring

    protected Refactoring createRefactoring(RefactoringDescriptor descriptor,
                                            RefactoringStatus status,
                                            IProgressMonitor monitor)
                                     throws CoreException

  Creates a refactoring from the specified refactoring descriptor.

  The default implementation calls `createRefactoring(RefactoringDescriptor, RefactoringStatus)` followed by `aboutToPerformRefactoring(Refactoring, RefactoringDescriptor, IProgressMonitor)`. Implementors can replace this implementation.

  Parameters:
    `descriptor` - the refactoring descriptor
    `status` - the refactoring status
    `monitor` - the progress monitor to use
  Returns:
    the refactoring, or `null` if this refactoring descriptor represents the unknown refactoring, or if no refactoring contribution is available for this refactoring descriptor
  Throws:
    `CoreException` - if an error occurs while creating the refactoring instance
  Since:
    3.4

### dispose

    public void dispose()

  The `Wizard` implementation of this `IWizard` method disposes all the pages controls using `DialogPage.dispose`. Subclasses should extend this method if the wizard instance maintains addition SWT resource that need to be disposed.

  Specified by:
    `dispose` in interface `IWizard`
  Overrides:
    `dispose` in class `Wizard`

### getErrorPage

    public final org.eclipse.ltk.internal.ui.refactoring.IErrorWizardPage getErrorPage()

  Returns the error wizard page.

  Note: This API must not be called from outside the refactoring framework.

  Returns:
    the error wizard page
  Restriction:
    This method is not intended to be referenced by clients.

### getNextPage

    public IWizardPage getNextPage(IWizardPage page)

  Returns the successor of the given page.

  This method is typically called by a wizard page

  Specified by:
    `getNextPage` in interface `IWizard`
  Overrides:
    `getNextPage` in class `Wizard`
  Parameters:
    `page` - the page
  Returns:
    the next page, or `null` if none

### getPreviewPage

    public final org.eclipse.ltk.internal.ui.refactoring.IPreviewWizardPage getPreviewPage()

  Returns the preview wizard page.

  Note: This API must not be called from outside the refactoring framework.

  Returns:
    the preview wizard page
  Restriction:
    This method is not intended to be referenced by clients.

### getPreviousPage

    public IWizardPage getPreviousPage(IWizardPage page)

  Returns the predecessor of the given page.

  This method is typically called by a wizard page

  Specified by:
    `getPreviousPage` in interface `IWizard`
  Overrides:
    `getPreviousPage` in class `Wizard`
  Parameters:
    `page` - the page
  Returns:
    the previous page, or `null` if none

### historyPerformed

    protected RefactoringStatus historyPerformed(IProgressMonitor monitor)

  Hook method which is called when all refactorings of the history have been executed. This method may be called from non-UI threads.

  This method is guaranteed to be called exactly once during the lifetime of a refactoring history wizard. It is not guaranteed that the user interface has not already been disposed of. The default implementation does nothing and returns a refactoring status of severity `RefactoringStatus.OK`.

  Subclasses may reimplement this method to perform any special processing.

  Parameters:
    `monitor` - the progress monitor to use
  Returns:
    a status describing the outcome of the operation

### performCancel

    public boolean performCancel()

  The `Wizard` implementation of this `IWizard` method does nothing and returns `true`. Subclasses should reimplement this method if they need to perform any special cancel processing for their wizard.

  Specified by:
    `performCancel` in interface `IWizard`
  Overrides:
    `performCancel` in class `Wizard`
  Returns:
    `true` to indicate the cancel request was accepted, and `false` to indicate that the cancel request was refused

### performFinish

    public boolean performFinish()

  Subclasses must implement this `IWizard` method to perform any special finish processing for their wizard.

  Specified by:
    `performFinish` in interface `IWizard`
  Specified by:
    `performFinish` in class `Wizard`
  Returns:
    `true` to indicate the finish request was accepted, and `false` to indicate that the finish request was refused

### performPreviewChange

    public final RefactoringStatus performPreviewChange(Change change,
                                                        Refactoring refactoring)

  Performs the change previously displayed in the preview.

  Note: This API must not be called from outside the refactoring framework.

  Parameters:
    `change` - the change displayed in the preview
    `refactoring` - the associated refactoring
  Returns:
    the status of the operation, already handled by the user

### refactoringPerformed

    protected RefactoringStatus refactoringPerformed(Refactoring refactoring,
                                                     IProgressMonitor monitor)

  Hook method which is called when the specified refactoring has been performed, e.g. its change object has been successfully applied to the workspace. The default implementation does nothing and returns a refactoring status of severity `RefactoringStatus.OK`. This method may be called from non-UI threads.

  Subclasses may reimplement this method to perform any special processing.

  Returning a status of severity `RefactoringStatus.FATAL` will terminate the execution of the refactorings.

  Parameters:
    `refactoring` - the refactoring which has been performed
    `monitor` - the progress monitor to use
  Returns:
    a status describing the outcome of the operation

### selectPreviewChange

    protected boolean selectPreviewChange(Change change)

  Hook method which is called for each change before it is displayed in a preview page. The default implementation returns `true`.

  Subclasses may reimplement this method to perform any special filtering of preview changes.

  Parameters:
    `change` - the change to select
  Returns:
    `true` if the change passes the filter, `false` otherwise

### selectStatusEntry

    protected boolean selectStatusEntry(RefactoringStatusEntry entry)

  Hook method which is called for each status entry before it is displayed in a wizard page. The default implementation returns `true`.

  Subclasses may reimplement this method to perform any special filtering of status entries on error pages.

  Parameters:
    `entry` - the status entry to select
  Returns:
    `true` if the status entry passes the filter, `false` otherwise

### setConfiguration

    public final void setConfiguration(RefactoringHistoryControlConfiguration configuration)

  Sets the refactoring history control configuration.

  This method must be called before opening the wizard in a dialog.

  Parameters:
    `configuration` - the configuration to set

### setInput

    public final void setInput(RefactoringHistory history)

  Sets the refactoring history.

  This method must be called before opening the wizard in a dialog.

  Parameters:
    `history` - the refactoring history

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

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