Package org.apache.bookkeeper.client.api

Interface ReadHandle

All Superinterfaces:
AutoCloseable, Handle
All Known Subinterfaces:
WriteAdvHandle, WriteHandle
All Known Implementing Classes:
LedgerHandle, LedgerHandleAdv, ReadOnlyLedgerHandle
@Public @Unstable public interface ReadHandle extends Handle
Provide read access to a ledger.
Since:
4.6

  • Method Details

    • readAsync

      CompletableFuture<LedgerEntries> readAsync(long firstEntry, long lastEntry)
      Read a sequence of entries asynchronously.
      Parameters:
      firstEntry - id of first entry of sequence
      lastEntry - id of last entry of sequence, inclusive
      Returns:
      an handle to the result of the operation

    • batchReadAsync

      default CompletableFuture<LedgerEntries> batchReadAsync(long startEntry, int maxCount, long maxSize)
      Read a sequence of entries asynchronously.
      Parameters:
      startEntry - start entry id
      maxCount - the total entries count.
      maxSize - the total entries size.
      Returns:
      an handle to the result of the operation

    • read

      default LedgerEntries read(long firstEntry, long lastEntry) throws BKException, InterruptedException
      Read a sequence of entries synchronously.
      Parameters:
      firstEntry - id of first entry of sequence
      lastEntry - id of last entry of sequence, inclusive
      Returns:
      the result of the operation
      Throws:
      BKException
      InterruptedException

    • batchRead

      default LedgerEntries batchRead(long startEntry, int maxCount, long maxSize) throws BKException, InterruptedException
      Parameters:
      startEntry - start entry id
      maxCount - the total entries count.
      maxSize - the total entries size.
      Returns:
      the result of the operation
      Throws:
      BKException
      InterruptedException

    • readUnconfirmedAsync

      CompletableFuture<LedgerEntries> readUnconfirmedAsync(long firstEntry, long lastEntry)
      Read a sequence of entries asynchronously, allowing to read after the LastAddConfirmed range.
      This is the same of read(long, long) but it lets the client read without checking the local value of LastAddConfirmed, so that it is possible to read entries for which the writer has not received the acknowledge yet.
      For entries which are within the range 0..LastAddConfirmed BookKeeper guarantees that the writer has successfully received the acknowledge.
      For entries outside that range it is possible that the writer never received the acknowledge and so there is the risk that the reader is seeing entries before the writer and this could result in a consistency issue in some cases.
      With this method you can even read entries before the LastAddConfirmed and entries after it with one call, the expected consistency will be as described above for each subrange of ids.
      Parameters:
      firstEntry - id of first entry of sequence
      lastEntry - id of last entry of sequence, inclusive
      Returns:
      an handle to the result of the operation
      See Also:

    • readUnconfirmed

      default LedgerEntries readUnconfirmed(long firstEntry, long lastEntry) throws BKException, InterruptedException
      Read a sequence of entries synchronously.
      Parameters:
      firstEntry - id of first entry of sequence
      lastEntry - id of last entry of sequence, inclusive
      Returns:
      an handle to the result of the operation
      Throws:
      BKException
      InterruptedException
      See Also:

    • readLastAddConfirmedAsync

      CompletableFuture<Long> readLastAddConfirmedAsync()
      Obtains asynchronously the last confirmed write from a quorum of bookies. This call obtains the last add confirmed each bookie has received for this ledger and returns the maximum. If the ledger has been closed, the value returned by this call may not correspond to the id of the last entry of the ledger, since it reads the hint of bookies. Consequently, in the case the ledger has been closed, it may return a different value than getLastAddConfirmed, which returns the local value of the ledger handle.
      Returns:
      an handle to the result of the operation
      See Also:

    • readLastAddConfirmed

      default long readLastAddConfirmed() throws BKException, InterruptedException
      Obtains asynchronously the last confirmed write from a quorum of bookies.
      Returns:
      the result of the operation
      Throws:
      BKException
      InterruptedException
      See Also:

    • tryReadLastAddConfirmedAsync

      CompletableFuture<Long> tryReadLastAddConfirmedAsync()
      Obtains asynchronously the last confirmed write from a quorum of bookies but it doesn't wait all the responses from the quorum. It would callback immediately if it received a LAC which is larger than current LAC.
      Returns:
      an handle to the result of the operation

    • tryReadLastAddConfirmed

      default long tryReadLastAddConfirmed() throws BKException, InterruptedException
      Obtains asynchronously the last confirmed write from a quorum of bookies but it doesn't wait all the responses from the quorum.
      Returns:
      the result of the operation
      Throws:
      BKException
      InterruptedException
      See Also:

    • getLastAddConfirmed

      long getLastAddConfirmed()
      Get the last confirmed entry id on this ledger. It reads the local state of the ledger handle, which is different from the readLastAddConfirmed() call.

      In the case the ledger is not closed and the client is a reader, it is necessary to call readLastAddConfirmed() to obtain a fresh value of last add confirmed entry id.

      Returns:
      the local value for LastAddConfirmed or -1L if no entry has been confirmed.
      See Also:

    • getLength

      long getLength()
      Returns the length of the data written in this ledger so much, in bytes.
      Returns:
      the length of the data written in this ledger, in bytes.

    • isClosed

      boolean isClosed()
      Returns whether the ledger is sealed or not.

      A ledger is sealed when either the client explicitly closes it (WriteHandle.close() or Handle.close()) or another client explicitly open and recovery it OpenBuilder.withRecovery(boolean).

      This method only checks the metadata cached locally. The metadata can be not update-to-date because the metadata notification is delayed.

      Returns:
      true if the ledger is sealed, otherwise false.

    • readLastAddConfirmedAndEntryAsync

      CompletableFuture<LastConfirmedAndEntry> readLastAddConfirmedAndEntryAsync(long entryId, long timeOutInMillis, boolean parallel)
      Asynchronous read specific entry and the latest last add confirmed. If the next entryId is less than known last add confirmed, the call will read next entry directly. If the next entryId is ahead of known last add confirmed, the call will issue a long poll read to wait for the next entry entryId.
      Parameters:
      entryId - next entry id to read
      timeOutInMillis - timeout period to wait for the entry id to be available (for long poll only) if timeout for get the entry, it will return null entry.
      parallel - whether to issue the long poll reads in parallel
      Returns:
      an handle to the result of the operation

    • readLastAddConfirmedAndEntry

      default LastConfirmedAndEntry readLastAddConfirmedAndEntry(long entryId, long timeOutInMillis, boolean parallel) throws BKException, InterruptedException
      Asynchronous read specific entry and the latest last add confirmed.
      Parameters:
      entryId - next entry id to read
      timeOutInMillis - timeout period to wait for the entry id to be available (for long poll only) if timeout for get the entry, it will return null entry.
      parallel - whether to issue the long poll reads in parallel
      Returns:
      the result of the operation
      Throws:
      BKException
      InterruptedException
      See Also: