Page History

One property BookKeeper satisfies is persistence: if an entry e is added to a ledger and the client receives a confirmation, then the last entry of the ledger once it is closed is at least e.

...

To fence a ledger from the client API, you can simply open it using BookKeeper#asyncOpenLedger or BookKeeper#openLedger. If the ledger you are opening is currently being written to by another ledgerclient, it will automatically be fenced, and the writing client will receive a BKWriteException for any subsequent calls to LedgerHandle#addEntry/LedgerHandle#asyncAddEntry.

However, there are cases where you do not want to fence a ledger when you open it. For example, if you have a standby node tailing the WAL to maintain a up to date state for warm failover, then you do not want to impede the writer. In this case, you can open the ledger with BookKeeper#asyncOpenLedgerNoRecovery or BookKeeper#openLedgerNoRecovery. These methods do not guarantee that you will read the entire ledger, as if there is a concurrent writer, you will only be able to read the prefix of entries which had been confirmed at the time the ledger was opened. In these cases, you must open the ledger again with BookKeeper#asyncOpenLedger or BookKeeper#openLedger before failing over to your warm backup.

The full API doc is available at http://zookeeper.apache.org/bookkeeper/docs/r4.0.0/apidocs/org/apache/bookkeeper/client/BookKeeper.html.

Fencing internals

The following are the steps that the client takes to fence a ledger. This happens in tandem with recovery, so some details of this are also included. Multiple client can run the sequence of steps concurrently; the result will be the same and correct for all clients.

Step 1 (flag the ledger as in recovery) The client updates the zookeeper metadata for the ledger. This prevents the writer from changing the ensemble to continue writing. If the writer tries to change the ensemble it will see that the version of the metadata it has is out of date, and will have to read the new metadata before rebuilding the ensemble. On reading it will see the ledger is in recovery, so it will try to close the ledger.

Step 2 (fence the bookies) The client will send a read request to all bookies in the ensemble. It waits until it has received a response from at least one bookie in each possible ack quorum. For the RoundRobinDistributionSchedule(which is the only one at the moment), there are as many possible quorums as there are bookies in the ensemble. An individual bookie will usually be in more than one of these quorums. RRQuorumCoverageSet handles the logic for ensuring all the quorums are covered. Once this step is complete, the ledger is fenced. No more entries can be added.

Step 3 (ledger is recovered) At this point, the client can start recovering the ledger. It has read the last confirmed entry during Step 2. It starts reading forward, one entry at a time, until it gets an NoSuchEntry response from at least one bookie in each quorum for a particular entry id. The last entry in the ledger is, therefore, the preceding entry. The ledger is closed with this as its last entry.