Package org.eclipse.handly.buffer

# Class TextFileBuffer

java.lang.Object
org.eclipse.handly.buffer.TextFileBuffer

All Implemented Interfaces:
  `AutoCloseable`, `IBuffer`, `ISnapshotProvider`, `IReferenceCountable`

public final class TextFileBuffer extends Object implements IBuffer
Implementation of `IBuffer` backed by an `ITextFileBuffer`.

An instance of this class is safe for use by multiple threads, provided that the underlying `ITextFileBuffer` and its document are thread-safe.

This class has an optional dependency on `IFile` and can safely be used even when `org.eclipse.core.resources` bundle is not available.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TextFileBuffer(ICoreTextFileBufferProvider provider, org.eclipse.core.runtime.IProgressMonitor monitor)`
  Creates a new text file buffer instance and connects it to an underlying `ITextFileBuffer` via the given provider.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addListener(IBufferListener listener)`
  Adds the given listener to this buffer.
  `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.
  `static TextFileBuffer`
  `forFile(org.eclipse.core.resources.IFile file)`
  Returns a `TextFileBuffer` for the given file resource.
  `static TextFileBuffer`
  `forFileStore(org.eclipse.core.filesystem.IFileStore fileStore)`
  Returns a `TextFileBuffer` for the given file store.
  `static TextFileBuffer`
  `forLocation(org.eclipse.core.runtime.IPath location, org.eclipse.core.filebuffers.LocationKind locationKind)`
  Returns a `TextFileBuffer` for the given file location.
  `org.eclipse.jface.text.source.IAnnotationModel`
  `getAnnotationModel()`
  Returns the annotation model of this buffer, if any.
  `ICoreTextFileBufferProvider`
  `getCoreTextFileBufferProvider()`
  Returns the provider of the underlying `ITextFileBuffer` for this buffer.
  `org.eclipse.jface.text.IDocument`
  `getDocument()`
  Returns the underlying document of this buffer.
  `ISnapshot`
  `getSnapshot()`
  Returns the current snapshot of this buffer.
  `int`
  `getSupportedListenerMethods()`
  Returns a bit-mask describing the listener methods supported by 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`
  `removeListener(IBufferListener listener)`
  Removes the given listener from this buffer.
  `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 Details

  - ### TextFileBuffer

    public TextFileBuffer(ICoreTextFileBufferProvider provider, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
    Creates a new text file buffer instance and connects it to an underlying `ITextFileBuffer` via the given provider.

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

    Parameters:
      `provider` - a provider of the underlying `ITextFileBuffer` (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. The progress monitor is only valid for the duration of the invocation of this constructor
    Throws:
      `org.eclipse.core.runtime.CoreException` - if the buffer could not be created
      `org.eclipse.core.runtime.OperationCanceledException` - if this constructor is canceled

- ## Method Details

  - ### forLocation

    public static TextFileBuffer forLocation(org.eclipse.core.runtime.IPath location, org.eclipse.core.filebuffers.LocationKind locationKind) throws org.eclipse.core.runtime.CoreException
    Returns a `TextFileBuffer` for the given file location.

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

    Parameters:
      `location` - not `null`
      `locationKind` - not `null`
    Returns:
      a buffer for the given file location (never `null`)
    Throws:
      `org.eclipse.core.runtime.CoreException` - if the buffer could not be created

  - ### forFileStore

    public static TextFileBuffer forFileStore(org.eclipse.core.filesystem.IFileStore fileStore) throws org.eclipse.core.runtime.CoreException
    Returns a `TextFileBuffer` for the given file store.

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

    Parameters:
      `fileStore` - not `null`
    Returns:
      a buffer for the given file store (never `null`)
    Throws:
      `org.eclipse.core.runtime.CoreException` - if the buffer could not be created

  - ### forFile

    public static TextFileBuffer forFile(org.eclipse.core.resources.IFile file) throws org.eclipse.core.runtime.CoreException
    Returns a `TextFileBuffer` for the given file resource.

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

    Parameters:
      `file` - not `null`
    Returns:
      a buffer for the given file resource (never `null`)
    Throws:
      `org.eclipse.core.runtime.CoreException` - if the buffer could not be created

  - ### getCoreTextFileBufferProvider

    public ICoreTextFileBufferProvider getCoreTextFileBufferProvider()
    Returns the provider of the underlying `ITextFileBuffer` for this buffer.
    Returns:
      the underlying buffer's provider (never `null`)
    Throws:
      `IllegalStateException` - if this buffer is no longer accessible

  - ### 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.
    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

  - ### getSupportedListenerMethods

    public int getSupportedListenerMethods()
    Description copied from interface: `IBuffer`
    Returns a bit-mask describing the listener methods supported by this buffer. The buffer will never invoke a listener method it does not support.
    Specified by:
      `getSupportedListenerMethods` in interface `IBuffer`
    Returns:
      a bit-mask describing the supported listener methods
    See Also:
      - `IBufferListener`

  - ### addListener

    public void addListener(IBufferListener listener)
    Description copied from interface: `IBuffer`
    Adds the given listener to this buffer. Has no effect if the same listener is already registered.
    Specified by:
      `addListener` in interface `IBuffer`
    Parameters:
      `listener` - not `null`

  - ### removeListener

    public void removeListener(IBufferListener listener)
    Description copied from interface: `IBuffer`
    Removes the given listener from this buffer. Has no effect if the same listener was not already registered.
    Specified by:
      `removeListener` in interface `IBuffer`
    Parameters:
      `listener` - not `null`

  - ### 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 `IReferenceCountable`
    Specified by:
      `addRef` in interface `ISnapshotProvider`

  - ### 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 `IReferenceCountable`
    Specified by:
      `release` in interface `ISnapshotProvider`
    See Also:
      - `IReferenceCountable.close()`