Package org.eclipse.handly.snapshot

## Interface ISnapshotProvider

- All Superinterfaces:
    `java.lang.AutoCloseable`, `IReferenceCountable`
  All Known Subinterfaces:
    `IBuffer`
  All Known Implementing Classes:
    `Buffer`, `ChildBuffer`, `TextEditorBuffer`, `TextFileBuffer`

      public interface ISnapshotProvider
      extends IReferenceCountable

  An object capable of providing snapshots of the underlying resource or buffer.

  Snapshot providers support `IReferenceCountable` protocol, although some implementations do not have a need in reference counting and inherit a no-op implementation of the protocol methods in this interface. When it is known that a snapshot provider does not actually use reference counting, clients do not need to follow the requirements set forth in that protocol.

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

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default void` | `addRef()` | Spawns a new independent ownership of this object.
    `ISnapshot` | `getSnapshot()` | Returns the current snapshot of the underlying resource or buffer.
    `default void` | `release()` | Relinquishes an independent ownership of this object.

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

      `close`

- - ### Method Detail

    - #### getSnapshot

          ISnapshot getSnapshot()

      Returns the current snapshot of the underlying resource or buffer. The returned snapshot may immediately become stale or expire.

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

      Returns:
        the current snapshot (never `null`)
      Throws:
        `java.lang.IllegalStateException` - if no snapshot can be taken at this time

    - #### addRef

          default 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`

    - #### release

          default 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`
      See Also:
        `IReferenceCountable.close()`