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
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
isSynthetic
public boolean isSynthetic()
- Returns whether this change is synthetic or not.
-
-
Returns:
-
trueif 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
initializeValidationState.
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
-
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
