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
initializeValidationData
has to be called. - The method
isValid
can be used to determine if a change can still be applied to the workspace. If the method returns aRefactoringStatus
with 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
perform
can be called. A disabled change must not be executed. Theperform
method can only be called once. After a change has been executed, only the methoddispose
must be called. - the method
dispose
has to be called either after theperform
method 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 methoddispose
is typically implemented to unregister listeners registered during the methodinitializeValidationData
. There is no guarantee thatinitializeValidationData
,isValid
, orperform
has been called beforedispose
is 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
-
Method Summary
Modifier and TypeMethodDescriptionvoid
dispose()
Disposes this change.<T> T
getAdapter
(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 ornull
if the affected elements cannot be determined.Returns a descriptor of this change.abstract Object
Returns the element modified by thisChange
.abstract String
getName()
Returns the human readable name of this change.Returns the parent change.abstract void
Hook method to initialize some internal state to provide an adequate answer for theisValid
method.boolean
Returns whether this change is enabled or not.abstract RefactoringStatus
Verifies that this change object is still valid and can be executed by callingperform
.abstract Change
Performs this change.void
setEnabled
(boolean enabled) Sets whether this change is enabled or not.final void
setEnabledShallow
(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 ofCompositeChange
in 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
null
if 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:
true
if the change is enabled;false
otherwise.
-
setEnabled
public void setEnabled(boolean enabled) Sets whether this change is enabled or not.- Parameters:
enabled
-true
to enable this change;false
otherwise
-
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
-true
to enable this change;false
otherwise- Since:
- 3.1
-
getParent
Returns the parent change. Returnsnull
if no parent exists.- Returns:
- the parent change
-
initializeValidationData
Hook method to initialize some internal state to provide an adequate answer for theisValid
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 whenisValid
is 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.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.- 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
null
if 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 returnnull
if the change isn't related to an element.- Returns:
- the element modified by this change
-
getAffectedObjects
Returns the elements affected by this change ornull
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.- Returns:
- the elements affected by this change or
null
if the affected elements cannot be determined - Since:
- 3.1
-
getAdapter
Description copied from interface:IAdaptable
Returns an object which is an instance of the given class associated with this object. Returnsnull
if 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:
getAdapter
in interfaceIAdaptable
- Type Parameters:
T
- the class type- Parameters:
adapter
- the adapter class to look up- Returns:
- a object of the given class, or
null
if this object does not have an adapter for the given class
-