org.eclipse.handly.ui.texteditor

## Class TextEditorBuffer

- java.lang.Object
- - org.eclipse.handly.ui.texteditor.TextEditorBuffer

- All Implemented Interfaces:
    java.lang.AutoCloseable, IBuffer, ISnapshotProvider, IReferenceCountable

      public final class TextEditorBuffer
      extends java.lang.Object
      implements IBuffer

  Implementation of `IBuffer` backed by an `ITextEditor`.

  An instance of this class is safe for use by multiple threads, provided that the underlying text editor's document is thread-safe. However, certain operations can only be executed by the UI thread:

  - `save`
  - `isDirty`
  - `applyChange` - if save is requested

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextEditorBuffer(org.eclipse.ui.texteditor.ITextEditor editor)` Creates a new buffer instance and connects it to the given text editor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRef()` Spawns a new independent ownership of this object.
    `IBufferChange` | `applyChange(IBufferChange change, org.eclipse.core.runtime.IProgressMonitor monitor)` Applies the given change to this buffer.
    `org.eclipse.jface.text.source.IAnnotationModel` | `getAnnotationModel()` Returns the annotation model of this buffer, if any.
    `org.eclipse.jface.text.IDocument` | `getDocument()` Returns the underlying document of this buffer.
    `ISnapshot` | `getSnapshot()` Returns the current snapshot of this buffer.
    `boolean` | `isDirty()` Returns whether this buffer has been modified since the last time it was opened or saved.
    `void` | `release()` Relinquishes an independent ownership of this object.
    `void` | `save(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Saves this buffer.

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

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

    - ### Methods inherited from interface org.eclipse.handly.util.IReferenceCountable

      `close`

- - ### Constructor Detail

    - #### TextEditorBuffer

          public TextEditorBuffer(org.eclipse.ui.texteditor.ITextEditor editor)
                           throws org.eclipse.core.runtime.CoreException

      Creates a new buffer instance and connects it to the given text editor.

      It is the client responsibility to `release` the created buffer after it is no longer needed.

      This constructor can only be executed by the UI thread.

      Parameters:
        `editor` - not `null`
      Throws:
        `org.eclipse.core.runtime.CoreException` - if the buffer could not be connected

  - ### Method Detail

    - #### getDocument

          public org.eclipse.jface.text.IDocument getDocument()

      Description copied from interface: `IBuffer`
      Returns the underlying document of this buffer. The relationship between a buffer and its document does not change over the lifetime of the buffer.
      Specified by:
        `getDocument` in interface `IBuffer`
      Returns:
        the buffer's underlying document (never `null`)

    - #### getAnnotationModel

          public org.eclipse.jface.text.source.IAnnotationModel getAnnotationModel()

      Description copied from interface: `IBuffer`
      Returns the annotation model of this buffer, if any.

      The default method implementation always returns `null`.

      Specified by:
        `getAnnotationModel` in interface `IBuffer`
      Returns:
        the buffer's annotation model, or `null` if none

    - #### getSnapshot

          public ISnapshot getSnapshot()

      Description copied from interface: `IBuffer`
      Returns the current snapshot of this buffer. The returned snapshot may immediately become stale or expire.

      Note that it is possible to obtain a `non-expiring` snapshot from the buffer, although protractedly holding on non-expiring snapshots is not recommended as they may potentially consume large amount of space.

      Specified by:
        `getSnapshot` in interface `IBuffer`
      Specified by:
        `getSnapshot` in interface `ISnapshotProvider`
      Returns:
        the buffer's current snapshot (never `null`)

    - #### applyChange

          public IBufferChange applyChange(IBufferChange change,
                                           org.eclipse.core.runtime.IProgressMonitor monitor)
                                    throws org.eclipse.core.runtime.CoreException

      Description copied from interface: `IBuffer`
      Applies the given change to this buffer.

      Note that an update conflict may occur if the buffer's contents have changed since the inception of the snapshot on which the change is based. In that case, a `StaleSnapshotException` is thrown.

      Specified by:
        `applyChange` in interface `IBuffer`
      Parameters:
        `change` - a buffer change (not `null`)
        `monitor` - a progress monitor, or `null` if progress reporting is not desired. The caller must not rely on `IProgressMonitor.done()` having been called by the receiver
      Returns:
        undo change, if requested by the change. Otherwise, `null`
      Throws:
        `org.eclipse.core.runtime.CoreException` - if the change's edit tree is not in a valid state, or if one of the edits in the tree could not be executed, or if save is requested by the change but the buffer could not be saved

    - #### save

          public void save(IContext context,
                           org.eclipse.core.runtime.IProgressMonitor monitor)
                    throws org.eclipse.core.runtime.CoreException

      Description copied from interface: `IBuffer`
      Saves this buffer. It is up to the implementors of this method to decide what saving means. Typically, the contents of the underlying resource is changed to the contents of the buffer.
      Specified by:
        `save` in interface `IBuffer`
      Parameters:
        `context` - the operation context (not `null`)
        `monitor` - a progress monitor, or `null` if progress reporting is not desired. The caller must not rely on `IProgressMonitor.done()` having been called by the receiver
      Throws:
        `org.eclipse.core.runtime.CoreException` - if the buffer could not be saved

    - #### isDirty

          public boolean isDirty()

      Description copied from interface: `IBuffer`
      Returns whether this buffer has been modified since the last time it was opened or saved.
      Specified by:
        `isDirty` in interface `IBuffer`
      Returns:
        `true` if the buffer has unsaved changes, `false` otherwise

    - #### addRef

          public void addRef()

      Description copied from interface: `IReferenceCountable`
      Spawns a new independent ownership of this object. Each successful call to `addRef()` must ultimately be followed by exactly one call to `IReferenceCountable.release()`.
      Specified by:
        `addRef` in interface `IBuffer`
      Specified by:
        `addRef` in interface `ISnapshotProvider`
      Specified by:
        `addRef` in interface `IReferenceCountable`

    - #### release

          public void release()

      Description copied from interface: `IReferenceCountable`
      Relinquishes an independent ownership of this object. Each independent ownership of the object must ultimately end with exactly one call to this method.
      Specified by:
        `release` in interface `IBuffer`
      Specified by:
        `release` in interface `ISnapshotProvider`
      Specified by:
        `release` in interface `IReferenceCountable`
      See Also:
        `IReferenceCountable.close()`

Copyright (c) 2014, 2020 1C-Soft LLC and others. Made available under the Eclipse Public License 2.0