Package org.eclipse.handly.snapshot

# Interface ISnapshot

All Known Implementing Classes:
  `DocumentSnapshot`, `NonExpiringSnapshot`, `Snapshot`, `TextFileBufferSnapshot`, `TextFileSnapshot`, `TextFileStoreSnapshot`

public interface ISnapshot
A snapshot of the character contents of a resource or buffer. Clients may hold on to snapshots for extended periods of time, but a snapshot may 'expire' if the underlying resource or buffer has changed or ceased to exist since the snapshot inception. Depending on the snapshot implementation, an expired snapshot may become 'valid' again if the contents of the underlying resource or buffer is reverted to the original state.

Implementations of this interface must be thread-safe.

Restriction:
  This interface is not intended to be extended by clients.
Restriction:
  This interface is not intended to be implemented by clients directly. However, clients may extend the base implementation, class `Snapshot`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getContents()`
  A snapshot returns the same contents until it expires.
  `boolean`
  `isEqualTo(ISnapshot other)`
  Indicates whether some other snapshot is "equal to" this one.

- ## Method Details

  - ### getContents

    String getContents()
    A snapshot returns the same contents until it expires. This is the contents of the underlying resource or buffer at the moment the snapshot was taken. Expired snapshots return `null`.

    Protractedly holding on to the returned contents is not recommended, as it may potentially consume significant amount of space.

    Returns:
      the contents of the snapshot, or `null` if the snapshot has expired

  - ### isEqualTo

    boolean isEqualTo(ISnapshot other)
    Indicates whether some other snapshot is "equal to" this one.

    If snapshots are equal they have equal contents (or had had equal contents before one or both of them expired). However, the converse is not necessarily true.

    Note that snapshots which are equal but not identical may become unequal when one or both of them expire, and may become equal again in case they return to the valid (unexpired) state.

    Implementations of this method must be reflexive, symmetric and transitive on non-null references.

    Parameters:
      `other` - a snapshot to compare or `null`
    Returns:
      `true` if the snapshots are equal, and `false` otherwise