Eclipse Platform Release 3.7

## org.eclipse.ltk.core.refactoring
Class CompositeChange

    java.lang.Object
      org.eclipse.ltk.core.refactoring.Change
          org.eclipse.ltk.core.refactoring.CompositeChange

All Implemented Interfaces:
  IAdaptable

    public class CompositeChange

extends Change

Represents a composite change. Composite changes can be marked as synthetic. A synthetic composite changes might not be rendered in the refactoring preview tree to save display real-estate.

Clients may subclass this class.

Since:
  3.0
See Also:
  `Change`

Constructor Summary
`CompositeChange(String name)` Creates a new composite change with the given name.
`CompositeChange(String name, Change[] children)` Creates a new composite change with the given name and array of children.

Method Summary
`void` `add(Change change)` Adds the given change to the list of children.
`void` `addAll(Change[] changes)` Adds all changes in the given array to the list of children.
`Change[]` `clear()` Removes all changes from this composite change.
`protected Change` `createUndoChange(Change[] childUndos)` Hook to create an undo change.
`void` `dispose()` Disposes this change. The composite change sends `dispose` to all its children.
`Object[]` `getAffectedObjects()` Returns the elements affected by this change or `null` if the affected elements cannot be determined.
`Change[]` `getChildren()` Returns the children managed by this composite change.
`ChangeDescriptor` `getDescriptor()` Returns a descriptor of this change.
`Object` `getModifiedElement()` Returns the element modified by this `Change`.
`String` `getName()` Returns the human readable name of this change.
`Change` `getUndoUntilException()` Returns the undo object containing all undo changes of those children that got successfully executed while performing this change.
`void` `initializeValidationData(IProgressMonitor pm)` Hook method to initialize some internal state to provide an adequate answer for the `isValid` method. The composite change sends `initializeValidationData` to all its children.
`protected boolean` `internalContinueOnCancel()` Note: this is an internal method and should not be overridden outside of the refactoring framework.
`protected void` `internalHandleException(Change change, Throwable t)` Note: this is an internal method and should not be overridden outside of the refactoring framework.
`protected boolean` `internalProcessOnCancel(Change change)` Note: this is an internal method and should not be overridden outside of the refactoring framework.
`boolean` `isSynthetic()` Returns whether this change is synthetic or not.
`RefactoringStatus` `isValid(IProgressMonitor pm)` Verifies that this change object is still valid and can be executed by calling `perform`. The composite change sends `isValid` to all its children until the first one returns a status with a severity of `FATAL` .
`void` `markAsSynthetic()` Marks this change as synthetic.
`void` `merge(CompositeChange change)` Merges the children of the given composite change into this change.
`Change` `perform(IProgressMonitor pm)` Performs this change. The composite change sends `perform` to all its enabled children.
`boolean` `remove(Change change)` Removes the given change from the list of children.
`void` `setEnabled(boolean enabled)` Sets whether this change is enabled or not. The composite change sends `setEnabled` to all its children.
`String` `toString()`

Methods inherited from class org.eclipse.ltk.core.refactoring.Change
`getAdapter, getParent, isEnabled, setEnabledShallow`

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

Constructor Detail

### CompositeChange

    public CompositeChange(String name)

  Creates a new composite change with the given name.

  Parameters:
    `name` - the human readable name of the change. Will be used to display the change in the user interface

### CompositeChange

    public CompositeChange(String name,
                           Change[] children)

  Creates a new composite change with the given name and array of children.

  Parameters:
    `name` - the human readable name of the change. Will be used to display the change in the user interface
    `children` - the initial array of children

Method Detail

### isSynthetic

    public boolean isSynthetic()

  Returns whether this change is synthetic or not.

  Returns:
    `true`if this change is synthetic; otherwise `false`

### markAsSynthetic

    public void markAsSynthetic()

  Marks this change as synthetic.

### getName

    public String getName()

  Returns the human readable name of this change. The name MUST not be `null`.

  Specified by:
    `getName` in class `Change`
  Returns:
    the human readable name of this change

### add

    public void add(Change change)

  Adds the given change to the list of children. The change to be added can be `null`. Adding a "null" change does nothing.

  Parameters:
    `change` - the change to add

### addAll

    public void addAll(Change[] changes)

  Adds all changes in the given array to the list of children.

  Parameters:
    `changes` - the changes to add

### merge

    public void merge(CompositeChange change)

  Merges the children of the given composite change into this change. This means the changes are removed from the given composite change and added to this change.

  Parameters:
    `change` - the change to merge

### remove

    public boolean remove(Change change)

  Removes the given change from the list of children.

  Parameters:
    `change` - the change to remove
  Returns:
    `true` if the change contained the given child; otherwise `false` is returned

### clear

    public Change[] clear()

  Removes all changes from this composite change.

  Returns:
    the list of changes removed from this composite change
  Since:
    3.1

### getChildren

    public Change[] getChildren()

  Returns the children managed by this composite change.

  Returns:
    the children of this change or an empty array if no children exist

### setEnabled

    public void setEnabled(boolean enabled)

  Sets whether this change is enabled or not.

  The composite change sends `setEnabled` to all its children.

  Client are allowed to extend this method.

  Overrides:
    `setEnabled` in class `Change`
  Parameters:
    `enabled` - `true` to enable this change; `false` otherwise

### initializeValidationData

    public void initializeValidationData(IProgressMonitor pm)

  Hook method to initialize some internal state to provide an adequate answer for the `isValid` method. This method gets called after a change or a whole change tree has been created.

  Typically this method is implemented in one of the following ways:

  - the change hooks up a listener on some delta notification mechanism and marks itself as invalid if it receives a certain delta. Is this the case the implementor must take care of unhooking the listener in `dispose`.
  - the change remembers some information allowing to decide if a change object is still valid when `isValid` is called.

  For example, a change object that manipulates the content of an `IFile` could either listen to resource changes and detect that the file got changed or it could remember some content stamp and compare it with the actual content stamp when `isValid` is called.

  The composite change sends `initializeValidationData` to all its children.

  Client are allowed to extend this method.

  Specified by:
    `initializeValidationData` in class `Change`
  Parameters:
    `pm` - a progress monitor

### isValid

    public RefactoringStatus isValid(IProgressMonitor pm)
                              throws CoreException

  Verifies that this change object is still valid and can be executed by calling `perform`. If a refactoring status with a severity of `RefactoringStatus.FATAL` is returned then the change has to be treated as invalid and can no longer be executed. Performing such a change produces an unspecified result and will very likely throw an exception.

  This method is also called by the `UndoManager` to decide if an undo or redo change is still valid and therefore can be executed.

  The composite change sends `isValid` to all its children until the first one returns a status with a severity of `FATAL` . If one of the children throws an exception the remaining children will not receive the `isValid` call.

  Client are allowed to extend this method.

  Specified by:
    `isValid` in class `Change`
  Parameters:
    `pm` - a progress monitor.
  Returns:
    a refactoring status describing the outcome of the validation check
  Throws:
    `CoreException` - if an error occurred during validation check. The change is to be treated as invalid if an exception occurs

### perform

    public Change perform(IProgressMonitor pm)
                   throws CoreException

  Performs this change. If this method is called on an invalid or disabled change object the result is unspecified. Changes should in general not respond to `IProgressMonitor.isCanceled()` since canceling a change tree in the middle of its execution leaves the workspace in a half changed state.

  The composite change sends `perform` to all its enabled children. If one of the children throws an exception the remaining children will not receive the `perform` call. In this case the method `getUndoUntilException` can be used to get an undo object containing the undo objects of all executed children.

  Client are allowed to extend this method.

  Specified by:
    `perform` in class `Change`
  Parameters:
    `pm` - a progress monitor
  Returns:
    the undo change for this change object or `null` if no undo is provided
  Throws:
    `CoreException` - if an error occurred during change execution

### internalHandleException

    protected void internalHandleException(Change change,
                                           Throwable t)

  Note: this is an internal method and should not be overridden outside of the refactoring framework.

  The method gets called if one of the changes managed by this composite change generates an exception when performed.

  Parameters:
    `change` - the change that caused the exception
    `t` - the exception itself
  Restriction:
    This method is not intended to be referenced by clients.

### internalContinueOnCancel

    protected boolean internalContinueOnCancel()

  Note: this is an internal method and should not be overridden outside of the refactoring framework.

  The method gets called if one of the changes managed by this composite change generates an operation canceled exception when performed.

  Returns:
    `true` if performing the change should continue on cancel; otherwise `false`
  Since:
    3.1
  Restriction:
    This method is not intended to be referenced by clients.

### internalProcessOnCancel

    protected boolean internalProcessOnCancel(Change change)

  Note: this is an internal method and should not be overridden outside of the refactoring framework.

  The method gets called if the execution of this change got canceled, but `internalContinueOnCancel` returned true.

  Parameters:
    `change` - the change to perform
  Returns:
    `true` if the given change should be performed although the execution got canceled; otherwise `false`
  Since:
    3.1
  Restriction:
    This method is not intended to be referenced by clients.

### dispose

    public void dispose()

  Disposes this change. Subclasses that override this method typically unregister listeners which got registered during the call to `initializeValidationData`.

  Subclasses may override this method.

  The composite change sends `dispose` to all its children. It is guaranteed that all children receive the `dispose` call.

  Overrides:
    `dispose` in class `Change`

### getUndoUntilException

    public Change getUndoUntilException()

  Returns the undo object containing all undo changes of those children that got successfully executed while performing this change. Returns `null` if all changes were executed successfully.

  This method is not intended to be overridden or extended.

  Returns:
    the undo object containing all undo changes of those children that got successfully executed while performing this change

### createUndoChange

    protected Change createUndoChange(Change[] childUndos)

  Hook to create an undo change. The method should be overridden by clients which provide their own composite change to create a corresponding undo change.

  Parameters:
    `childUndos` - the child undo. The undo edits appear in the list in the reverse order of their execution. So the first change in the array is the undo change of the last change that got executed.
  Returns:
    the undo change

### getAffectedObjects

    public Object[] getAffectedObjects()

  Returns the elements affected by this change or `null` if the affected elements cannot be determined. Returns an empty array if the change doesn't modify any elements.

  This default implementation returns `null` to indicate that the affected elements are unknown. Subclasses should reimplement this method if they can compute the set of affected elements.

  Overrides:
    `getAffectedObjects` in class `Change`
  Returns:
    the elements affected by this change or `null` if the affected elements cannot be determined

### getModifiedElement

    public Object getModifiedElement()

  Returns the element modified by this `Change`. The method may return `null` if the change isn't related to an element.

  Specified by:
    `getModifiedElement` in class `Change`
  Returns:
    the element modified by this change

### getDescriptor

    public ChangeDescriptor getDescriptor()

  Returns a descriptor of this change.

  Subclasses of changes created by `Refactoring.createChange(IProgressMonitor)` should override this method to return a `RefactoringChangeDescriptor`. A change tree created by a particular refactoring is supposed to contain at most one change which returns a refactoring descriptor. Refactorings usually return an instance of `CompositeChange` in their `Refactoring.createChange(IProgressMonitor)` method which implements this method. The refactoring framework searches the change tree top-down until a refactoring descriptor is found.

  Overrides:
    `getDescriptor` in class `Change`
  Returns:
    a descriptor of this change, or `null` if this change does not provide a change descriptor.
  Since:
    3.2

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

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