org.apache.bookkeeper.client

Class LedgerHandle

java.lang.Object

org.apache.bookkeeper.client.LedgerHandle

public class LedgerHandle
extends Object

Ledger handle contains ledger metadata and is used to access the read and write operations to a ledger.

Field Summary

Fields

Modifier and Type	Field and Description
static long	INVALID_ENTRY_ID Invalid entry id.

Method Summary

Methods

Modifier and Type	Method and Description
long	addEntry(byte[] data) Add entry synchronously to an open ledger.
long	addEntry(byte[] data, int offset, int length) Add entry synchronously to an open ledger.
void	asyncAddEntry(byte[] data, AsyncCallback.AddCallback cb, Object ctx) Add entry asynchronously to an open ledger.
void	asyncAddEntry(byte[] data, int offset, int length, AsyncCallback.AddCallback cb, Object ctx) Add entry asynchronously to an open ledger, using an offset and range.
void	asyncClose(AsyncCallback.CloseCallback cb, Object ctx) Asynchronous close, any adds in flight will return errors.
void	asyncReadEntries(long firstEntry, long lastEntry, AsyncCallback.ReadCallback cb, Object ctx) Read a sequence of entries asynchronously.
void	asyncReadLastConfirmed(AsyncCallback.ReadLastConfirmedCallback cb, Object ctx) Obtains asynchronously the last confirmed write from a quorum of bookies.
void	asyncTryReadLastConfirmed(AsyncCallback.ReadLastConfirmedCallback cb, Object ctx) Obtains asynchronously the last confirmed write from a quorum of bookies.
void	close() Close this ledger synchronously.
long	getId() Get the id of the current ledger
long	getLastAddConfirmed() Get the last confirmed entry id on this ledger.
long	getLastAddPushed() Get the entry id of the last entry that has been enqueued for addition (but may not have possibly been persited to the ledger)
byte[]	getLedgerKey() Get the Ledger's key/password.
long	getLength() Returns the length of the ledger in bytes.
Enumeration<LedgerEntry>	readEntries(long firstEntry, long lastEntry) Read a sequence of entries synchronously.
long	readLastConfirmed() Obtains synchronously the last confirmed write from a quorum of bookies.
long	tryReadLastConfirmed() Obtains synchronously the last confirmed write from a quorum of bookies.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INVALID_ENTRY_ID

public static final long INVALID_ENTRY_ID

Invalid entry id. This value is returned from methods which should return an entry id but there is no valid entry available.

See Also:

Constant Field Values

Method Detail

getId

public long getId()

Get the id of the current ledger

Returns:

the id of the ledger

getLastAddConfirmed

public 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 readLastConfirmed call. In the case the ledger is not closed and the client is a reader, it is necessary to call readLastConfirmed to obtain an estimate of the last add operation that has been confirmed.

Returns:

the last confirmed entry id or INVALID_ENTRY_ID if no entry has been confirmed

See Also:

readLastConfirmed()

getLastAddPushed

public long getLastAddPushed()

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

Returns:

the id of the last entry pushed or INVALID_ENTRY_ID if no entry has been pushed

getLedgerKey

public byte[] getLedgerKey()

Get the Ledger's key/password.

Returns:

byte array for the ledger's key/password.

getLength

public long getLength()

Returns the length of the ledger in bytes.

Returns:

the length of the ledger in bytes

close

public void close()
           throws InterruptedException,
                  BKException

Close this ledger synchronously.

Throws:

InterruptedException

BKException

See Also:

asyncClose(org.apache.bookkeeper.client.AsyncCallback.CloseCallback, java.lang.Object)

asyncClose

public void asyncClose(AsyncCallback.CloseCallback cb,
              Object ctx)

Asynchronous close, 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. This ensures that, once the ledger has been closed, all reads from the ledger will return the same set of entries.

Parameters:

cb - callback implementation

ctx - control object

readEntries

public Enumeration<LedgerEntry> readEntries(long firstEntry,
                                   long lastEntry)
                                     throws InterruptedException,
                                            BKException

Read a sequence of entries synchronously.

Parameters:

firstEntry - id of first entry of sequence (included)

lastEntry - id of last entry of sequence (included)

Throws:

InterruptedException

BKException

asyncReadEntries

public void asyncReadEntries(long firstEntry,
                    long lastEntry,
                    AsyncCallback.ReadCallback cb,
                    Object ctx)

Read a sequence of entries asynchronously.

Parameters:

firstEntry - id of first entry of sequence

lastEntry - id of last entry of sequence

cb - object implementing read callback interface

ctx - control object

addEntry

public long addEntry(byte[] data)
              throws InterruptedException,
                     BKException

Add entry synchronously to an open ledger.

Parameters:

data - array of bytes to be written to the ledger

Returns:

the entryId of the new inserted entry

Throws:

InterruptedException

BKException

addEntry

public long addEntry(byte[] data,
            int offset,
            int length)
              throws InterruptedException,
                     BKException

Add entry synchronously to an open ledger.

Parameters:

data - array of bytes to be written to the ledger

offset - offset from which to take bytes from data

length - number of bytes to take from data

Returns:

the entryId of the new inserted entry

Throws:

InterruptedException

BKException

asyncAddEntry

public void asyncAddEntry(byte[] data,
                 AsyncCallback.AddCallback cb,
                 Object ctx)

Add entry asynchronously to an open ledger.

Parameters:

data - array of bytes to be written

cb - object implementing callbackinterface

ctx - some control object

asyncAddEntry

public void asyncAddEntry(byte[] data,
                 int offset,
                 int length,
                 AsyncCallback.AddCallback cb,
                 Object ctx)

Add entry asynchronously to an open ledger, using an offset and range.

Parameters:

data - array of bytes to be written

offset - offset from which to take bytes from data

length - number of bytes to take from data

cb - object implementing callbackinterface

ctx - some control object

Throws:

ArrayIndexOutOfBoundsException - if offset or length is negative or offset and length sum to a value higher than the length of data.

asyncReadLastConfirmed

public void asyncReadLastConfirmed(AsyncCallback.ReadLastConfirmedCallback cb,
                          Object ctx)

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.

Parameters:

cb -

ctx -

See Also:

getLastAddConfirmed()

asyncTryReadLastConfirmed

public void asyncTryReadLastConfirmed(AsyncCallback.ReadLastConfirmedCallback cb,
                             Object ctx)

Obtains asynchronously the last confirmed write from a quorum of bookies. It is similar as asyncTryReadLastConfirmed(org.apache.bookkeeper.client.AsyncCallback.ReadLastConfirmedCallback, Object), 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.

Parameters:

cb - callback to return read last confirmed

ctx - callback context

See Also:

asyncTryReadLastConfirmed(org.apache.bookkeeper.client.AsyncCallback.ReadLastConfirmedCallback, Object)

readLastConfirmed

public long readLastConfirmed()
                       throws InterruptedException,
                              BKException

Obtains synchronously 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:

The entry id of the last confirmed write or INVALID_ENTRY_ID if no entry has been confirmed

Throws:

InterruptedException

BKException

See Also:

getLastAddConfirmed()

tryReadLastConfirmed

public long tryReadLastConfirmed()
                          throws InterruptedException,
                                 BKException

Obtains synchronously the last confirmed write from a quorum of bookies. It is similar as readLastConfirmed(), 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:

The entry id of the last confirmed write or INVALID_ENTRY_ID if no entry has been confirmed

Throws:

InterruptedException

BKException

See Also:

readLastConfirmed()