Package org.eclipse.ltk.core.refactoring

## Class DocumentChange

- java.lang.Object
- - org.eclipse.ltk.core.refactoring.Change
  - - org.eclipse.ltk.core.refactoring.TextEditBasedChange
    - - org.eclipse.ltk.core.refactoring.TextChange
      - - org.eclipse.ltk.core.refactoring.DocumentChange

All Implemented Interfaces:
  `IAdaptable`

    public class DocumentChange
    extends TextChange

A text change that operates directly on instances of `IDocument`. The document change uses a simple length compare to check if it is still valid. So as long as its length hasn't changed the text edits managed have a valid range and can be applied to the document. The same applies to the undo change returned from the perform method.

Note: this class is not intended to be extended by clients.

Since:
  3.0
Restriction:
  This class is not intended to be subclassed by clients.

### Constructor Summary

Constructors
`DocumentChange​(String name, IDocument document)` Creates a new `DocumentChange` for the given `IDocument`.

### Method Summary

All Methods Instance Methods Concrete Methods
`protected IDocument` `acquireDocument​(IProgressMonitor pm)` Acquires a reference to the document to be changed by this text change.
`protected void` `commit​(IDocument document, IProgressMonitor pm)` Commits the document acquired via a call to `aquireDocument`.
`protected Change` `createUndoChange​(UndoEdit edit)` Hook to create an undo change for the given undo edit.
`Object` `getModifiedElement()` Returns the element modified by this `Change`.
`void` `initializeValidationData​(IProgressMonitor pm)` Hook method to initialize some internal state to provide an adequate answer for the `isValid` method.
`RefactoringStatus` `isValid​(IProgressMonitor pm)` Verifies that this change object is still valid and can be executed by calling `perform`.
`protected UndoEdit` `performEdits​(IDocument document)` Executes the text edits on the given document.
`protected void` `releaseDocument​(IDocument document, IProgressMonitor pm)` Releases the document acquired via a call to `aquireDocument`.

### 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, setKeepPreviewEdits`

### Methods inherited from class org.eclipse.ltk.core.refactoring.TextEditBasedChange

`addChangeGroup, getChangeGroups, getKeepPreviewEdits, getName, getTextType, hasOneGroupCategory, setEnabled, setTextType`

### Methods inherited from class org.eclipse.ltk.core.refactoring.Change

`dispose, getAdapter, getAffectedObjects, getDescriptor, getParent, isEnabled, setEnabledShallow`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### DocumentChange

    public DocumentChange​(String name,
                          IDocument document)

Creates a new `DocumentChange` for the given `IDocument`.

Parameters:
  `name` - the change's name. Has to be a human readable name.
  `document` - the document this change is working on

### Method Detail

#### getModifiedElement

    public Object getModifiedElement()

Description copied from class: `Change`
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

#### initializeValidationData

    public void initializeValidationData​(IProgressMonitor pm)

Description copied from class: `Change`
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.

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

#### isValid

    public RefactoringStatus isValid​(IProgressMonitor pm)
                              throws CoreException

Description copied from class: `Change`
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.

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

#### acquireDocument

    protected IDocument acquireDocument​(IProgressMonitor pm)
                                 throws CoreException

Description copied from class: `TextChange`
Acquires a reference to the document to be changed by this text change. A document acquired by this call MUST be released via a call to `TextChange.releaseDocument(IDocument, IProgressMonitor)`.

The method `releaseDocument` must be called as many times as `aquireDocument` has been called.

Specified by:
  `acquireDocument` in class `TextChange`
Parameters:
  `pm` - a progress monitor
Returns:
  a reference to the document to be changed
Throws:
  `CoreException` - if the document can't be acquired

#### commit

    protected void commit​(IDocument document,
                          IProgressMonitor pm)
                   throws CoreException

Description copied from class: `TextChange`
Commits the document acquired via a call to `aquireDocument`. 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.

Specified by:
  `commit` in class `TextChange`
Parameters:
  `document` - the document to commit
  `pm` - a progress monitor
Throws:
  `CoreException` - if the document can't be committed

#### releaseDocument

    protected void releaseDocument​(IDocument document,
                                   IProgressMonitor pm)
                            throws CoreException

Description copied from class: `TextChange`
Releases the document acquired via a call to `aquireDocument`.

Specified by:
  `releaseDocument` in class `TextChange`
Parameters:
  `document` - the document to release
  `pm` - a progress monitor
Throws:
  `CoreException` - if the document can't be released

#### performEdits

    protected UndoEdit performEdits​(IDocument document)
                             throws BadLocationException,
                                    MalformedTreeException

Description copied from class: `TextChange`
Executes the text edits on the given document. Subclasses that override this method should call `super.performEdits(document)`.

Overrides:
  `performEdits` in class `TextChange`
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.

#### createUndoChange

    protected Change createUndoChange​(UndoEdit edit)

Description copied from class: `TextChange`
Hook 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:
  `createUndoChange` in class `TextChange`
Parameters:
  `edit` - the `UndoEdit` to create an undo change for
Returns:
  the undo change or `null` if no undo change can be created. Returning `null` results in the fact that the whole change tree can't be undone. So returning `null` is only recommended if an exception occurred during the creation of the undo change.