Package org.apache.bookkeeper.client.api

Interface WriteHandle

All Superinterfaces:

AutoCloseable, ForceableHandle, Handle, ReadHandle

All Known Implementing Classes:

LedgerHandle, LedgerHandleAdv, ReadOnlyLedgerHandle

@Public
@Unstable
public interface WriteHandle
extends ReadHandle, ForceableHandle

Provide write access to a ledger.

Since:

4.6

See Also:

• WriteAdvHandle

Method Summary

Modifier and Type	Method	Description
default long	append(byte[] data)	Add an entry synchronously to an open ledger.
default long	append(byte[] data, int offset, int length)	Add an entry synchronously to an open ledger.
default long	append(io.netty.buffer.ByteBuf data)	Add entry synchronously to an open ledger.
default long	append(ByteBuffer data)	Add entry synchronously to an open ledger.
default CompletableFuture<Long>	appendAsync(byte[] data)	Add an entry asynchronously to an open ledger.
default CompletableFuture<Long>	appendAsync(byte[] data, int offset, int length)	Add an entry asynchronously to an open ledger.
CompletableFuture<Long>	appendAsync(io.netty.buffer.ByteBuf data)	Add entry asynchronously to an open ledger.
default CompletableFuture<Long>	appendAsync(ByteBuffer data)	Add entry asynchronously to an open ledger.
default void	close()	Synchronous close the write handle, any adds in flight will return errors.
CompletableFuture<Void>	closeAsync()	Asynchronous close the write handle, any adds in flight will return errors.
long	getLastAddPushed()	Get the entry id of the last entry that has been enqueued for addition (but may not have possibly been persisted to the ledger).

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

force

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

getId, getLedgerMetadata

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

batchRead, batchReadAsync, getLastAddConfirmed, getLength, isClosed, read, readAsync, readLastAddConfirmed, readLastAddConfirmedAndEntry, readLastAddConfirmedAndEntryAsync, readLastAddConfirmedAsync, readUnconfirmed, readUnconfirmedAsync, tryReadLastAddConfirmed, tryReadLastAddConfirmedAsync

Method Details

appendAsync

CompletableFuture<Long> appendAsync(io.netty.buffer.ByteBuf data)

Add entry asynchronously to an open ledger.

Parameters:

data - a bytebuf to be written. The bytebuf's reference count will be decremented by 1 after the completable future is returned do not reuse the buffer, bk-client will release it appropriately.

Returns:

an handle to the result, in case of success it will return the id of the newly appended entry

append

default long append(io.netty.buffer.ByteBuf data)
             throws BKException,
InterruptedException

Add entry synchronously to an open ledger.

Parameters:

data - a bytebuf to be written. The bytebuf's reference count will be decremented by 1 after the call completes. do not reuse the buffer, bk-client will release it appropriately.

Returns:

the id of the newly appended entry

Throws:

BKException

InterruptedException

appendAsync

default CompletableFuture<Long> appendAsync(ByteBuffer data)

Add entry asynchronously to an open ledger.

Parameters:

data - array of bytes to be written do not reuse the buffer, bk-client will release it appropriately.

Returns:

an handle to the result, in case of success it will return the id of the newly appended entry

append

default long append(ByteBuffer data)
             throws BKException,
InterruptedException

Add entry synchronously to an open ledger.

Parameters:

data - array of bytes to be written do not reuse the buffer, bk-client will release it appropriately.

Returns:

the id of the newly appended entry

Throws:

BKException

InterruptedException

appendAsync

default CompletableFuture<Long> appendAsync(byte[] data)

Add an entry asynchronously to an open ledger.

Parameters:

data - array of bytes to be written do not reuse the buffer, bk-client will release it appropriately.

Returns:

a completable future represents the add result, in case of success the future returns the entry id of this newly appended entry

append

default long append(byte[] data)
             throws BKException,
InterruptedException

Add an entry synchronously to an open ledger.

Parameters:

data - array of bytes to be written do not reuse the buffer, bk-client will release it appropriately.

Returns:

the entry id of this newly appended entry

Throws:

BKException

InterruptedException

appendAsync

default CompletableFuture<Long> appendAsync(byte[] data,
 int offset,
 int length)

Add an entry asynchronously to an open ledger.

Parameters:

data - array of bytes to be written do not reuse the buffer, bk-client will release it appropriately.

offset - the offset in the bytes array

length - the length of the bytes to be appended

Returns:

a completable future represents the add result, in case of success the future returns the entry id of this newly appended entry

append

default long append(byte[] data,
 int offset,
 int length)
             throws BKException,
InterruptedException

Add an entry synchronously to an open ledger.

Parameters:

data - array of bytes to be written do not reuse the buffer, bk-client will release it appropriately.

offset - the offset in the bytes array

length - the length of the bytes to be appended

Returns:

the entry id of this newly appended entry

Throws:

BKException

InterruptedException

getLastAddPushed

long getLastAddPushed()

Get the entry id of the last entry that has been enqueued for addition (but may not have possibly been persisted to the ledger).

Returns:

the entry id of the last entry pushed or -1 if no entry has been pushed

closeAsync

CompletableFuture<Void> closeAsync()

Asynchronous close the write handle, any adds in flight will return errors.

Closing a ledger will ensure that all clients agree on what the last entry of the ledger is. Once the ledger has been closed, all reads from the ledger will return the same set of entries.

The close operation can error if it finds conflicting metadata when it tries to write to the metadata store. On close, the metadata state is set to closed and lastEntry and length of the ledger are fixed in the metadata. A conflict occurs if the metadata in the metadata store has a different value for the lastEntry or length. If another process has updated the metadata, setting it to closed, but have fixed the lastEntry and length to the same values as this process is trying to write, the operation completes successfully.

Specified by:

closeAsync in interface Handle

Returns:

an handle to access the result of the operation

close

default void close()
            throws BKException,
InterruptedException

Synchronous close the write handle, any adds in flight will return errors.

Closing a ledger will ensure that all clients agree on what the last entry of the ledger is. Once the ledger has been closed, all reads from the ledger will return the same set of entries.

The close operation can error if it finds conflicting metadata when it tries to write to the metadata store. On close, the metadata state is set to closed and lastEntry and length of the ledger are fixed in the metadata. A conflict occurs if the metadata in the metadata store has a different value for the lastEntry or length. If another process has updated the metadata, setting it to closed, but have fixed the lastEntry and length to the same values as this process is trying to write, the operation completes successfully.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Handle

Throws:

BKException

InterruptedException

See Also:

• Handle.closeAsync()