Class TextFileChange
- All Implemented Interfaces:
IAdaptable
TextChange that operates on a IFile.
As of 3.1 the content stamp managed by a text file change maps to the modification
stamp of its underlying IFile. Undoing a text file change will
roll back the modification stamp of a resource to its original value using
the new API IResource.revertModificationStamp(long)
The class should be subclassed by clients which need to perform special operation when acquiring or releasing a document.
- Since:
- 3.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intFlag (value 2) indicating that the file is to be saved after the change has been applied.static final intFlag (value 1) indicating that the file's save state has to be kept.static final intFlag (value 4) indicating that the file will not be saved after the change has been applied. -
Constructor Summary
ConstructorsConstructorDescriptionTextFileChange(String name, IFile file) Creates a newTextFileChangefor the given file. -
Method Summary
Modifier and TypeMethodDescriptionprotected IDocumentAcquires a reference to the document to be changed by this text change.protected voidcommit(IDocument document, IProgressMonitor pm) Commits the document acquired via a call toaquireDocument.protected final ChangecreateUndoChange(UndoEdit edit) Hook to create an undo change for the given undo edit.protected ChangecreateUndoChange(UndoEdit edit, ContentStamp stampToRestore) Hook to create an undo change for the given undo edit and content stamp.voiddispose()Disposes this change.Object[]Returns the elements affected by this change ornullif the affected elements cannot be determined.getFile()Returns theIFilethis change is working on.Returns the element modified by thisChange.intReturns the save state set viasetSaveMode(int).voidinitializeValidationData(IProgressMonitor monitor) Hook method to initialize some internal state to provide an adequate answer for theisValidmethod.protected booleanIs the document currently acquired?protected booleanHas the document been modified since it has been first acquired by the change?isValid(IProgressMonitor monitor) Verifies that this change object is still valid and can be executed by callingperform.protected booleanDoes the text file change need saving?protected UndoEditperformEdits(IDocument document) Executes the text edits on the given document.protected voidreleaseDocument(IDocument document, IProgressMonitor pm) Releases the document acquired via a call toaquireDocument.voidsetSaveMode(int saveMode) Sets the save state.Methods inherited from class org.eclipse.ltk.core.refactoring.TextChange
addEdit, addTextEditChangeGroup, addTextEditGroup, getCurrentContent, getCurrentContent, getCurrentDocument, getEdit, getPreviewContent, getPreviewContent, getPreviewContent, getPreviewDocument, getPreviewEdit, getPreviewEdits, getTextEditChangeGroups, perform, setEdit, setKeepPreviewEditsMethods inherited from class org.eclipse.ltk.core.refactoring.TextEditBasedChange
addChangeGroup, getChangeGroups, getKeepPreviewEdits, getName, getTextType, hasOneGroupCategory, setEnabled, setTextTypeMethods inherited from class org.eclipse.ltk.core.refactoring.Change
getAdapter, getDescriptor, getParent, isEnabled, setEnabledShallow
-
Field Details
-
KEEP_SAVE_STATE
public static final int KEEP_SAVE_STATEFlag (value 1) indicating that the file's save state has to be kept. This means an unsaved file is still unsaved after performing the change and a saved one will be saved.- See Also:
-
FORCE_SAVE
public static final int FORCE_SAVEFlag (value 2) indicating that the file is to be saved after the change has been applied.- See Also:
-
LEAVE_DIRTY
public static final int LEAVE_DIRTYFlag (value 4) indicating that the file will not be saved after the change has been applied.- See Also:
-
-
Constructor Details
-
TextFileChange
Creates a newTextFileChangefor the given file.- Parameters:
name- the change's name mainly used to render the change in the UIfile- the file this text change operates on
-
-
Method Details
-
setSaveMode
public void setSaveMode(int saveMode) Sets the save state. Must be one ofKEEP_SAVE_STATE,FORCE_SAVEorLEAVE_DIRTY.- Parameters:
saveMode- indicating how save is handled when the document gets committed
-
getSaveMode
public int getSaveMode()Returns the save state set viasetSaveMode(int).- Returns:
- the save state
-
getFile
Returns theIFilethis change is working on.- Returns:
- the file this change is working on
-
createUndoChange
Hook to create an undo change for the given undo edit and content stamp. This hook gets called while performing the change to construct the corresponding undo change object.- Parameters:
edit- theUndoEditto create an undo change forstampToRestore- the content stamp to restore when the undo edit is executed.- Returns:
- the undo change or
nullif no undo change can be created. Returningnullresults in the fact that the whole change tree can't be undone. So returningnullis only recommended if an exception occurred during creating the undo change.
-
getModifiedElement
Description copied from class:ChangeReturns the element modified by thisChange. The method may returnnullif the change isn't related to an element.- Specified by:
getModifiedElementin classChange- Returns:
- the element modified by this change
-
getAffectedObjects
Description copied from class:ChangeReturns 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.- Overrides:
getAffectedObjectsin classChange- Returns:
- the elements affected by this change or
nullif the affected elements cannot be determined
-
initializeValidationData
Description copied from class:ChangeHook 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.- Specified by:
initializeValidationDatain classChange- Parameters:
monitor- 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
Description copied from class:ChangeVerifies 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.- Specified by:
isValidin classChange- Parameters:
monitor- 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
-
dispose
public void dispose()Description copied from class:ChangeDisposes this change. Subclasses that override this method typically unregister listeners which got registered during the call toinitializeValidationData.Subclasses may override this method.
-
acquireDocument
Description copied from class:TextChangeAcquires a reference to the document to be changed by this text change. A document acquired by this call MUST be released via a call toTextChange.releaseDocument(IDocument, IProgressMonitor).The method
releaseDocumentmust be called as many times asaquireDocumenthas been called.- Specified by:
acquireDocumentin classTextChange- Parameters:
pm- a progress monitor- Returns:
- a reference to the document to be changed
- Throws:
CoreException- if the document can't be acquired
-
commit
Commits the document acquired via a call toaquireDocument. It is up to the implementors of this method to decide what committing a document means. Typically, the content of the document is written back to the file system.The implementation of this method only commits the underlying buffer if
needsSaving()andisDocumentModified()returnstrue.- Specified by:
commitin classTextChange- Parameters:
document- the document to commitpm- a progress monitor- Throws:
CoreException- if the document can't be committed
-
releaseDocument
Description copied from class:TextChangeReleases the document acquired via a call toaquireDocument.- Specified by:
releaseDocumentin classTextChange- Parameters:
document- the document to releasepm- a progress monitor- Throws:
CoreException- if the document can't be released
-
createUndoChange
Description copied from class:TextChangeHook to create an undo change for the given undo edit. This hook gets called while performing the change to construct the corresponding undo change object.- Specified by:
createUndoChangein classTextChange- Parameters:
edit- theUndoEditto create an undo change for- Returns:
- the undo change or
nullif no undo change can be created. Returningnullresults in the fact that the whole change tree can't be undone. So returningnullis only recommended if an exception occurred during the creation of the undo change.
-
performEdits
protected UndoEdit performEdits(IDocument document) throws BadLocationException, MalformedTreeException Description copied from class:TextChangeExecutes the text edits on the given document. Subclasses that override this method should callsuper.performEdits(document).- Overrides:
performEditsin classTextChange- Parameters:
document- the document- Returns:
- an object representing the undo of the executed edits
- Throws:
BadLocationException- is thrown if one of the edits in the tree can't be executed. The state of the document is undefined if this exception is thrown.MalformedTreeException- is thrown if the edit tree isn't in a valid state. This exception is thrown before any edit is executed. So the document is still in its original state.
-
isDocumentAcquired
protected boolean isDocumentAcquired()Is the document currently acquired?- Returns:
trueif the document is currently acquired,falseotherwise- Since:
- 3.2
-
isDocumentModified
protected boolean isDocumentModified()Has the document been modified since it has been first acquired by the change?- Returns:
- Returns true if the document has been modified since it got acquired by the change.
falseis returned if the document has not been acquired yet, or has been released already. - Since:
- 3.3
-
needsSaving
protected boolean needsSaving()Does the text file change need saving?The implementation of this method returns
trueif theFORCE_SAVEflag is enabled, or the underlying file is not dirty andKEEP_SAVE_STATEis enabled.- Returns:
trueif it needs saving according to its dirty state and the save mode flags,falseotherwise- Since:
- 3.3
-