org.apache.bookkeeper.client.api

Interface ReadHandle

All Superinterfaces:

java.lang.AutoCloseable, Handle

All Known Subinterfaces:

WriteAdvHandle, WriteHandle

All Known Implementing Classes:

LedgerHandle, LedgerHandleAdv, ReadOnlyLedgerHandle

@InterfaceAudience.Public
 @InterfaceStability.Unstable
public interface ReadHandle
extends Handle

Provide read access to a ledger.

Since:

4.6

Method Summary

Modifier and Type	Method and Description
long	getLastAddConfirmed() Get the last confirmed entry id on this ledger.
long	getLength() Returns the length of the data written in this ledger so much, in bytes.
boolean	isClosed() Returns whether the ledger is sealed or not.
default LedgerEntries	read(long firstEntry, long lastEntry) Read a sequence of entries synchronously.
java.util.concurrent.CompletableFuture<LedgerEntries>	readAsync(long firstEntry, long lastEntry) Read a sequence of entries asynchronously.
default long	readLastAddConfirmed() Obtains asynchronously the last confirmed write from a quorum of bookies.
default LastConfirmedAndEntry	readLastAddConfirmedAndEntry(long entryId, long timeOutInMillis, boolean parallel) Asynchronous read specific entry and the latest last add confirmed.
java.util.concurrent.CompletableFuture<LastConfirmedAndEntry>	readLastAddConfirmedAndEntryAsync(long entryId, long timeOutInMillis, boolean parallel) Asynchronous read specific entry and the latest last add confirmed.
java.util.concurrent.CompletableFuture<java.lang.Long>	readLastAddConfirmedAsync() Obtains asynchronously the last confirmed write from a quorum of bookies.
default LedgerEntries	readUnconfirmed(long firstEntry, long lastEntry) Read a sequence of entries synchronously.
java.util.concurrent.CompletableFuture<LedgerEntries>	readUnconfirmedAsync(long firstEntry, long lastEntry) Read a sequence of entries asynchronously, allowing to read after the LastAddConfirmed range.
default long	tryReadLastAddConfirmed() Obtains asynchronously the last confirmed write from a quorum of bookies but it doesn't wait all the responses from the quorum.
java.util.concurrent.CompletableFuture<java.lang.Long>	tryReadLastAddConfirmedAsync() Obtains asynchronously the last confirmed write from a quorum of bookies but it doesn't wait all the responses from the quorum.

Methods inherited from interface org.apache.bookkeeper.client.api.Handle

close, closeAsync, getId, getLedgerMetadata

Method Detail

readAsync

java.util.concurrent.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

read

default LedgerEntries read(long firstEntry,
                           long lastEntry)
                    throws BKException,
                           java.lang.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

java.lang.InterruptedException

readUnconfirmedAsync

java.util.concurrent.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 possibile 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:

readAsync(long, long), readLastAddConfirmedAsync()

readUnconfirmed

default LedgerEntries readUnconfirmed(long firstEntry,
                                      long lastEntry)
                               throws BKException,
                                      java.lang.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

java.lang.InterruptedException

See Also:

readUnconfirmedAsync(long, long)

readLastAddConfirmedAsync

java.util.concurrent.CompletableFuture<java.lang.Long> readLastAddConfirmedAsync()

Obtains asynchronously the last confirmed write from a quorum of bookies. This call obtains the 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:

getLastAddConfirmed()

readLastAddConfirmed

default long readLastAddConfirmed()
                           throws BKException,
                                  java.lang.InterruptedException

Obtains asynchronously the last confirmed write from a quorum of bookies.

Returns:

the result of the operation

Throws:

BKException

java.lang.InterruptedException

See Also:

readLastAddConfirmedAsync()

tryReadLastAddConfirmedAsync

java.util.concurrent.CompletableFuture<java.lang.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,
                                     java.lang.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

java.lang.InterruptedException

See Also:

tryReadLastAddConfirmedAsync()

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:

readLastAddConfirmed()

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

java.util.concurrent.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,
                                                           java.lang.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

java.lang.InterruptedException

See Also:

readLastAddConfirmedAndEntry(long, long, boolean)