Class Change
- All Implemented Interfaces:
IAdaptable
- Direct Known Subclasses:
CompositeChange,NullChange,ResourceChange,TextEditBasedChange,UndoTextFileChange
Change object is typically created by calling
Refactoring.createChange(IProgressMonitor). This class should be subclassed by clients
wishing to provide new changes.
Changes are best executed by using a PerformChangeOperation. If clients execute a change
directly then the following life cycle has to be honored:
- After a single change or a tree of changes has been created, the method
initializeValidationDatahas to be called. - The method
isValidcan be used to determine if a change can still be applied to the workspace. If the method returns aRefactoringStatuswith a severity of FATAL then the change has to be treated as invalid. Performing an invalid change isn't allowed and results in an unspecified result. This method can be called multiple times. - Then the method
performcan be called. A disabled change must not be executed. Theperformmethod can only be called once. After a change has been executed, only the methoddisposemust be called. - the method
disposehas to be called either after theperformmethod has been called or if a change is no longer needed. The second case for example occurs when the undo stack gets flushed and all change objects managed by the undo stack are no longer needed. The methoddisposeis typically implemented to unregister listeners registered during the methodinitializeValidationData. There is no guarantee thatinitializeValidationData,isValid, orperformhas been called beforedisposeis called.
Change change= createChange();
try {
change.initializeValidationData(pm);
....
if (!change.isEnabled())
return;
RefactoringStatus valid= change.isValid(subMonitor.newChild(1));
if (valid.hasFatalError())
return;
Change undo= change.perform(subMonitor.newChild(1));
if (undo != null) {
undo.initializeValidationData(subMonitor.newChild(1));
// do something with the undo object
}
} finally {
change.dispose();
}
It is important that implementors of this abstract class provide an adequate implementation of
isValid and that they provide an undo change via the return value of the method
perform. If no undo can be provided then the perform method is allowed
to return null. But implementors should be aware that not providing an undo object
for a change object that is part of a larger change tree will result in the fact that for the
whole change tree no undo object will be present.
Changes which are returned as top-level changes (e.g. by Refactoring.createChange())
can optionally return a descriptor object of the refactoring which created this change object.
Clients may subclass this class.
- Since:
- 3.0
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoiddispose()Disposes this change.<T> TgetAdapter(Class<T> adapter) Returns an object which is an instance of the given class associated with this object.Object[]Returns the elements affected by this change ornullif the affected elements cannot be determined.Returns a descriptor of this change.abstract ObjectReturns the element modified by thisChange.abstract StringgetName()Returns the human readable name of this change.Returns the parent change.abstract voidHook method to initialize some internal state to provide an adequate answer for theisValidmethod.booleanReturns whether this change is enabled or not.abstract RefactoringStatusVerifies that this change object is still valid and can be executed by callingperform.abstract ChangePerforms this change.voidsetEnabled(boolean enabled) Sets whether this change is enabled or not.final voidsetEnabledShallow(boolean enabled) Sets the enablement state of this change in a shallow way.
-
Constructor Details
-
Change
protected Change()Constructs a new change object.
-
-
Method Details
-
getDescriptor
Returns a descriptor of this change.Subclasses of changes created by
Refactoring.createChange(IProgressMonitor)should override this method to return aRefactoringChangeDescriptor. 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 ofCompositeChangein theirRefactoring.createChange(IProgressMonitor)method which implements this method. The refactoring framework searches the change tree top-down until a refactoring descriptor is found.- Returns:
- a descriptor of this change, or
nullif this change does not provide a change descriptor. - Since:
- 3.2
-
getName
Returns the human readable name of this change. The name MUST not benull.- Returns:
- the human readable name of this change
-
isEnabled
public boolean isEnabled()Returns whether this change is enabled or not. Disabled changes must not be executed.- Returns:
trueif the change is enabled;falseotherwise.
-
setEnabled
public void setEnabled(boolean enabled) Sets whether this change is enabled or not.- Parameters:
enabled-trueto enable this change;falseotherwise
-
setEnabledShallow
public final void setEnabledShallow(boolean enabled) Sets the enablement state of this change in a shallow way. For changes having children this means that only this change's enablement state changes. The children are left untouched.- Parameters:
enabled-trueto enable this change;falseotherwise- Since:
- 3.1
-
getParent
Returns the parent change. Returnsnullif no parent exists.- Returns:
- the parent change
-
initializeValidationData
Hook method to initialize some internal state to provide an adequate answer for theisValidmethod. 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
isValidis called.
For example, a change object that manipulates the content of an
IFilecould 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 whenisValidis called.- Parameters:
pm- a progress monitor
- 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
-
isValid
public abstract RefactoringStatus isValid(IProgressMonitor pm) throws CoreException, OperationCanceledException Verifies that this change object is still valid and can be executed by callingperform. If a refactoring status with a severity ofRefactoringStatus.FATALis 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
UndoManagerto decide if an undo or redo change is still valid and therefore can be executed.- 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 occursOperationCanceledException- if the validation check got canceled
-
perform
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 toIProgressMonitor.isCanceled()since canceling a change tree in the middle of its execution leaves the workspace in a half changed state.- Parameters:
pm- a progress monitor- Returns:
- the undo change for this change object or
nullif no undo is provided - Throws:
CoreException- if an error occurred during change execution
-
dispose
public void dispose()Disposes this change. Subclasses that override this method typically unregister listeners which got registered during the call toinitializeValidationData.Subclasses may override this method.
-
getModifiedElement
Returns the element modified by thisChange. The method may returnnullif the change isn't related to an element.- Returns:
- the element modified by this change
-
getAffectedObjects
Returns the elements affected by this change ornullif the affected elements cannot be determined. Returns an empty array if the change doesn't modify any elements.This default implementation returns
nullto indicate that the affected elements are unknown. Subclasses should reimplement this method if they can compute the set of affected elements.- Returns:
- the elements affected by this change or
nullif the affected elements cannot be determined - Since:
- 3.1
-
getAdapter
Description copied from interface:IAdaptableReturns an object which is an instance of the given class associated with this object. Returnsnullif no such object can be found.Clients may implement this method but should generally call
Adapters.adapt(Object, Class, boolean)rather than invoking it directly.- Specified by:
getAdapterin interfaceIAdaptable- Type Parameters:
T- the class type- Parameters:
adapter- the adapter class to look up- Returns:
- a object of the given class, or
nullif this object does not have an adapter for the given class
-