Eclipse Platform Release 3.7

## 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
`DocumentChange(String name, IDocument document)` Creates a new `DocumentChange` for the given `IDocument`.

Method Summary
`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()

  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)

  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

  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

  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

  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

  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)

  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.

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.