Package org.eclipse.handly.buffer

Interface IBuffer

All Superinterfaces:
AutoCloseable, IReferenceCountable, ISnapshotProvider
All Known Implementing Classes:
Buffer, ChildBuffer, TextEditorBuffer, TextFileBuffer
public interface IBuffer extends ISnapshotProvider, IReferenceCountable
Represents a potentially shared buffer that contains text contents of a resource. The contents may be in the process of being edited, differing from the actual contents of the underlying resource.

Clients can take a snapshot of the buffer, construct an edit tree based on the snapshot, and apply the change back to the buffer. Note that an update conflict may occur if the buffer's contents have changed since the inception of the base snapshot.

Buffers support IReferenceCountable protocol; clients need to follow the requirements set forth in that protocol. In particular, it is the client responsibility to release a buffer after it is no longer needed.

Buffers are generally designed to be safe for use by multiple threads. Each buffer implementation is expected to clearly document thread-safety guarantees it provides.

  • Method Summary

    Modifier and Type
    Method
    Description
    default 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.
    default 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.
    default 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.
    default 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 interface org.eclipse.handly.util.IReferenceCountable

    close

  • Method Details

    • getSnapshot

      ISnapshot getSnapshot()
      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 ISnapshotProvider
      Returns:
      the buffer's current snapshot (never null)

    • applyChange

      IBufferChange applyChange(IBufferChange change, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      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.

      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:
      StaleSnapshotException - if the buffer's contents have changed since the inception of the snapshot on which the change is based
      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

      void save(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      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.
      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

      boolean isDirty()
      Returns whether this buffer has been modified since the last time it was opened or saved.
      Returns:
      true if the buffer has unsaved changes, false otherwise

    • getDocument

      org.eclipse.jface.text.IDocument getDocument()
      Returns the underlying document of this buffer. The relationship between a buffer and its document does not change over the lifetime of the buffer.
      Returns:
      the buffer's underlying document (never null)

    • getAnnotationModel

      default org.eclipse.jface.text.source.IAnnotationModel getAnnotationModel()
      Returns the annotation model of this buffer, if any.
      Returns:
      the buffer's annotation model, or null if none
      Since:
      1.3

    • getSupportedListenerMethods

      default int getSupportedListenerMethods()
      Returns a bit-mask describing the listener methods supported by this buffer. The buffer will never invoke a listener method it does not support.
      Returns:
      a bit-mask describing the supported listener methods
      Since:
      1.4
      See Also:

    • addListener

      default void addListener(IBufferListener listener)
      Adds the given listener to this buffer. Has no effect if the same listener is already registered.
      Parameters:
      listener - not null
      Since:
      1.4

    • removeListener

      default void removeListener(IBufferListener listener)
      Removes the given listener from this buffer. Has no effect if the same listener was not already registered.
      Parameters:
      listener - not null
      Since:
      1.4

    • addRef

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

    • release

      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 IReferenceCountable
      Specified by:
      release in interface ISnapshotProvider
      See Also: