This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/bookkeeper.git
The following commit(s) were added to refs/heads/asf-site by this push:
new d5bfa6a Updated site at revision 3abf2c7
d5bfa6a is described below
commit d5bfa6a18890a90869415828b93d84586a62042e
Author: jenkins <[email protected]>
AuthorDate: Wed Dec 6 01:32:07 2017 +0000
Updated site at revision 3abf2c7
---
.../index.html | 366 +++++++++++++++++++++
content/community/bookkeeper_proposals/index.html | 6 +-
2 files changed, 371 insertions(+), 1 deletion(-)
diff --git
a/content/bps/BP-22-separate-closing-ledgers-from-opening-ledgers/index.html
b/content/bps/BP-22-separate-closing-ledgers-from-opening-ledgers/index.html
new file mode 100644
index 0000000..8187235
--- /dev/null
+++ b/content/bps/BP-22-separate-closing-ledgers-from-opening-ledgers/index.html
@@ -0,0 +1,366 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Apache BookKeeper™ - BP-22: Separate closing ledgers from
opening ledgers</title>
+
+<meta charset="utf-8">
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+
+<link rel="stylesheet" href="/css/normalize.css">
+<link rel="stylesheet" href="/css/tippy.css">
+<link rel="stylesheet" href="/css/style.css">
+
+<link rel="shortcut icon" href="/img/favicon.ico">
+
+<script src="/js/tippy.min.js"></script>
+
+<script type="text/javascript">
+ var shiftWindow = function() { scrollBy(0, -25); };
+ window.addEventListener("hashchange", shiftWindow);
+ window.addEventListener("pageshow", shiftWindow);
+ function load() { if (window.location.hash) shiftWindow(); }
+</script>
+ </head>
+ <body class="body">
+ <main class="main">
+
+<nav class="navbar bk-topnav">
+ <div class="navbar-brand">
+ <a class="navbar-item bk-brand" href="/">
+ Apache BookKeeper™
+ </a>
+
+ <div class="navbar-burger burger" data-target="bkNav">
+ <span></span>
+ <span></span>
+ <span></span>
+ </div>
+ </div>
+
+ <div id="bkNav" class="navbar-menu">
+ <div class="navbar-start">
+ <div class="navbar-item has-dropdown is-hoverable">
+ <a class="navbar-link">Documentation</a>
+ <div class="navbar-dropdown is-boxed">
+ <a class="navbar-item" href="/docs/latest/overview/overview">
+ Version 4.7.0-SNAPSHOT
+ <span class="tag is-warning">Development</span>
+ </a>
+ <a class="navbar-item" href="/docs/latest/api/javadoc">
+ <span class="icon bk-javadoc-icon">
+ <img src="/img/java-icon.svg">
+ </span>
+ Javadoc
+ </a>
+ <hr class="dropdown-divider">
+
+ <a class="navbar-item" href="/docs/4.6.0/overview/overview">
+ Release 4.6.0
+
+ </a>
+
+ <a class="navbar-item" href="/docs/4.5.1/overview/overview">
+ Release 4.5.1
+
+ </a>
+
+ <a class="navbar-item" href="/docs/4.5.0/overview/overview">
+ Release 4.5.0
+ <span class="tag is-success">Stable</span>
+ </a>
+
+
+ <a class="navbar-item" href="/archives/docs/r4.4.0">
+ Release 4.4.0
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.3.2">
+ Release 4.3.2
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.3.1">
+ Release 4.3.1
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.3.0">
+ Release 4.3.0
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.2.4">
+ Release 4.2.4
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.2.3">
+ Release 4.2.3
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.2.2">
+ Release 4.2.2
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.2.1">
+ Release 4.2.1
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.2.0">
+ Release 4.2.0
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.1.0">
+ Release 4.1.0
+
+ </a>
+
+ <a class="navbar-item" href="/archives/docs/r4.0.0">
+ Release 4.0.0
+
+ </a>
+
+ </div>
+ </div>
+
+ <div class="navbar-item has-dropdown is-hoverable">
+ <a class="navbar-link">Community</a>
+ <div class="navbar-dropdown is-boxed">
+ <a class="navbar-item" href="/community/mailing-lists">Mailing
lists</a>
+ <a class="navbar-item" href="/community/slack">Slack</a>
+ <a class="navbar-item"
href="https://github.com/apache/bookkeeper/issues";>Github Issues</a>
+ <a class="navbar-item" href="/community/releases">Release
Management</a>
+ <a class="navbar-item" href="/community/meeting">Community
Meetings</a>
+ <hr class="dropdown-divider">
+ <a class="navbar-item" href="/community/contributing">Contribution
Guide</a>
+ <a class="navbar-item" href="/community/coding_guide">Coding
Guide</a>
+ <a class="navbar-item" href="/community/issue-report">Issue Report
Guide</a>
+ <a class="navbar-item" href="/community/release_guide">Release
Guide</a>
+ <hr class="dropdown-divider">
+ <a class="navbar-item"
href="/community/presentations">Presentations</a>
+ <a class="navbar-item"
href="/community/bookkeeper_proposals">BookKeeper Proposals</a>
+ </div>
+ </div>
+
+ <div class="navbar-item has-dropdown is-hoverable">
+ <a class="navbar-link">Project</a>
+ <div class="navbar-dropdown is-boxed">
+ <a class="navbar-item" href="/project/who">Who are we?</a>
+ <a class="navbar-item" href="/project/bylaws">Bylaws</a>
+ <a class="navbar-item"
href="http://www.apache.org/licenses/";>License</a>
+ <hr class="dropdown-divider">
+ <a class="navbar-item" href="/project/privacy">Privacy policy</a>
+ <a class="navbar-item"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a>
+ <a class="navbar-item"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a>
+ </div>
+ </div>
+ </div>
+
+ <div class="navbar-end">
+ <div class="navbar-item">
+ <div class="field is-grouped">
+ <p class="control">
+ <a class="button bk-twitter"
href="https://twitter.com/asfbookkeeper";>
+ <span class="icon">
+ <i class="fa fa-twitter"></i>
+ </span>
+ <span>Twitter</span>
+ </a>
+ </p>
+ <p class="control">
+ <a class="button" href="https://github.com/apache/bookkeeper";>
+ <span class="icon">
+ <i class="fa fa-github"></i>
+ </span>
+ <span>GitHub</span>
+ </a>
+ </p>
+ <p class="control">
+ <a class="button is-primary" href="/releases">
+ <span class="icon">
+ <i class="fa fa-download"></i>
+ </span>
+ <span>Download</span>
+ </a>
+ </p>
+ </div>
+ </div>
+ </div>
+ </div>
+</nav>
+
+
+ <div class="bk-community-container">
+ <div class="columns">
+ <div class="column is-12">
+ <header class="docs-title">
+ <nav class="level">
+ <div class="level-left">
+ <div class="level-item">
+ <h1 class="title">BP-22: Separate closing ledgers from opening
ledgers</h1>
+ </div>
+ </div>
+
+ </nav>
+
+
+ </header>
+
+ <hr />
+
+ <div class="content is-medium">
+ <section class="bk-community-content">
+ <p>Rejected due to lack of agreement that the issues raised in the
motivation are valid.</p>
+
+<h3 id="motivation">Motivation</h3>
+
+<p>In the beginning there was openLedger. Opening a ledger meant also figuring
out what the last entry of a ledger should be, and writing it to ZooKeeper. For
a long time this was the only way to read a ledger. If a writer was writing to
the ledger, then anything it wrote after this point would be lost (fencing was
added later). The open operation was the natural place to put recovery, as at
this point it was only possible to read a recovered ledger.</p>
+
+<p>openLedgerNoRecovery was added in 2011. This allowed users to read from a
ledger as it was being written to, which opened up a bunch of tailing uses
cases. Recovery was still the default, because that was what it had always
been, and tailing was still considered a secondary usecase. If the user wanted
to skip recovery, they’d have to explicitly call the no recovery method.</p>
+
+<p>Then the new API arrived. In the new API, tailing is the primary read use
case, and recovery has been demoted to a boolean flag on a builder for the open
operation. The user is for the most part unaware of recovery.</p>
+
+<p>However, recovery is still one of the most important aspects of BookKeeper.
It is the mechanism on which our Total Order Atomic Broadcast guarantees are
built. It deserves to be a bit more prominent than a boolean flag in a builder.
It also doesn’t help that the terminology is inconsistent. The flag is called
withRecovery, while the to check if recovery is needed, we call isClosed.
Closed itself is ambiguous because it may refer to the local handle, or it may
refer to the state of the [...]
+
+<p>As tailing is now the primary usecase, we expect that if a writer fails,
then whichever node takes over as writer already has a non-recovered ReadHandle
open. It would be nice to be able to continue using this Handle to read to the
end of the ledger.</p>
+
+<h3 id="public-interfaces">Public Interfaces</h3>
+
+<p>I proposes the removal of OpenOpBuilder#withRecovery()</p>
+
+<p>A new method on BookKeeper:</p>
+<div class="highlighter-rouge"><pre class="highlight"><code>interface
BookKeeper {
+
+ ...
+
+ CompletableFuture<Void> seal(ReadHandle handle);
+}
+</code></pre>
+</div>
+
+<h3 id="proposed-changes">Proposed Changes</h3>
+
+<p>With the proposed interface changes, every ReadHandle will be opened
without recovery. For the tailing usecase, usage will look like.</p>
+
+<div class="language-java highlighter-rouge"><pre
class="highlight"><code><span class="n">ReadHandle</span> <span
class="n">reader</span> <span class="o">=</span> <span class="n">bk</span><span
class="o">.</span><span class="na">newOpenLedgerOp</span><span
class="o">().</span><span class="na">withLedgerId</span><span
class="o">(</span><span class="n">X</span><span class="o">).</span><span
class="na">execute</span><span class="o">().</span><span
class="na">get</span><span class="o">();</span>
+<span class="kt">long</span> <span class="n">lastReadEntry</span> <span
class="o">=</span> <span class="o">-</span><span class="mi">1</span><span
class="o">;</span>
+<span class="k">while</span> <span class="o">(!</span><span
class="n">leader</span><span class="o">)</span> <span class="o">{</span>
+ <span class="kt">long</span> <span class="n">lac</span> <span
class="o">=</span> <span class="n">reader</span><span class="o">.</span><span
class="na">getLastAddConfirmed</span><span class="o">();</span>
+ <span class="k">if</span> <span class="o">(</span><span
class="n">lac</span> <span class="o">></span> <span
class="n">lastReadEntry</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">LedgerEntries</span> <span class="n">entries</span>
<span class="o">=</span> <span class="n">reader</span><span
class="o">.</span><span class="na">read</span><span class="o">(</span><span
class="n">lastReadEntry</span><span class="o">+</span><span
class="mi">1</span><span class="o">,</span> <span class="n">lac</span><span
class="o">).</span><span class="na">get</span><span class="o">();</span>
+ <span class="n">doSomethingWithEntries</span><span
class="o">(</span><span class="n">entries</span><span class="o">);</span>
+ <span class="n">lastReadEntry</span> <span class="o">=</span> <span
class="n">lac</span><span class="o">;</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+<span class="k">assert</span> <span class="o">(</span><span
class="n">leader</span><span class="o">);</span>
+<span class="n">bk</span><span class="o">.</span><span
class="na">seal</span><span class="o">(</span><span
class="n">reader</span><span class="o">).</span><span
class="na">get</span><span class="o">();</span>
+<span class="kt">long</span> <span class="n">lac</span> <span
class="o">=</span> <span class="n">reader</span><span class="o">.</span><span
class="na">readLastAddConfirmed</span><span class="o">().</span><span
class="na">get</span><span class="o">();</span>
+<span class="k">if</span> <span class="o">(</span><span class="n">lac</span>
<span class="o">></span> <span class="n">lastReadEntry</span><span
class="o">)</span> <span class="o">{</span>
+ <span class="n">LedgerEntries</span> <span class="n">entries</span> <span
class="o">=</span> <span class="n">reader</span><span class="o">.</span><span
class="na">read</span><span class="o">(</span><span
class="n">lastReadEntry</span><span class="o">+</span><span
class="mi">1</span><span class="o">,</span> <span class="n">lac</span><span
class="o">).</span><span class="na">get</span><span class="o">();</span>
+ <span class="n">doSomethingWithEntries</span><span class="o">(</span><span
class="n">entries</span><span class="o">);</span>
+<span class="o">}</span>
+<span class="n">WriteHandle</span> <span class="n">writer</span> <span
class="o">=</span> <span class="n">bk</span><span class="o">.</span><span
class="na">newCreateLedgerOp</span><span class="o">().</span><span
class="na">execute</span><span class="o">().</span><span
class="na">get</span><span class="o">();</span>
+</code></pre>
+</div>
+
+<p>Constrast this with how it is with the current recovery on open
mechanism.</p>
+
+<div class="highlighter-rouge"><pre class="highlight"><code>ReadHandle reader
= bk.newOpenLedgerOp().withLedgerId(X).execute().get();
+long lastReadEntry = -1;
+while (!leader) {
+ long lac = reader.getLastAddConfirmed();
+ if (lac > lastReadEntry) {
+ LedgerEntries entries = reader.read(lastReadEntry+1, lac).get();
+ doSomethingWithEntries(entries);
+ lastReadEntry = lac;
+ }
+}
+assert (leader);
+reader.close();
+reader =
bk.newOpenLedgerOp().withLedgerId(reader.getId()).withRecovery(true).execute.get();
+long lac = reader.readLastAddConfirmed().get();
+if (lac > lastReadEntry) {
+ LedgerEntries entries = reader.read(lastReadEntry+1, lac).get();
+ doSomethingWithEntries(entries);
+}
+WriteHandle writer = bk.newCreateLedgerOp().execute().get();
+</code></pre>
+</div>
+
+<p>The second one is more code, you need to remember to close the previous
handle, and the intent of the operation is less clear.</p>
+
+<h3 id="compatibility-deprecation-and-migration-plan">Compatibility,
Deprecation, and Migration Plan</h3>
+
+<p>This change is only on the new API, so there’s no promise of
compatibility.</p>
+
+<h3 id="test-plan">Test Plan</h3>
+
+<p>This change replaces #withRecovery() with #seal(), so anyplace withRecovery
was tested, should be replaced with #seal().</p>
+
+<h3 id="rejected-alternatives">Rejected Alternatives</h3>
+
+<ul>
+ <li>ReadHandle#seal: Rejected as ReadHandle should be side effect free</li>
+ <li>OpenOpBuilder#withRecovery(true): Rejected as we want tailing to be
default usecase.</li>
+ <li>ReadHandle#forceClosed() or BookKeeper#forceClosed(ReadHandle): Rejected
as unclear what the state of handle would be after (has ReadHandle#close been
called).</li>
+</ul>
+
+ </section>
+
+
+ </div>
+ </div>
+ </div>
+</div>
+ </main>
+
+ <footer class="footer">
+ <div class="container">
+ <div class="content has-text-centered">
+ <p>
+ Copyright © 2016 - 2017 <a href="https://www.apache.org/";>The
Apache Software Foundation</a>,<br /> licensed under the <a
href="http://www.apache.org/licenses/LICENSE-2.0";>Apache License, version
2.0</a>.
+ </p>
+ </div>
+ </div>
+</footer>
+
+ </body>
+
+ <script src="/js/app.js"></script>
+
+
+ <!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<script>
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new
Date();a=s.createElement(o),
+
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-104419626-1', 'auto');
+ ga('send', 'pageview');
+
+</script>
+
+
+</html>
diff --git a/content/community/bookkeeper_proposals/index.html
b/content/community/bookkeeper_proposals/index.html
index d93c5bd..fa5da62 100644
--- a/content/community/bookkeeper_proposals/index.html
+++ b/content/community/bookkeeper_proposals/index.html
@@ -341,7 +341,7 @@ of the thread is of the format <code
class="highlighter-rouge">[DISCUSS] BP-<
<p>This section lists all the <em>bookkeeper proposals</em> made to
BookKeeper.</p>
-<p><em>Next Proposal Number: 21</em></p>
+<p><em>Next Proposal Number: 23</em></p>
<h3 id="inprogress">Inprogress</h3>
@@ -459,6 +459,10 @@ of the thread is of the format <code
class="highlighter-rouge">[DISCUSS] BP-<
<td style="text-align: left"><a
href="../../bps/BP-21-new-api-close-inconsistencies">BP-21: New API close
inconsistencies</a></td>
<td style="text-align: left">Not A Problem</td>
</tr>
+ <tr>
+ <td style="text-align: left"><a
href="../../bps/BP-22-separate-closing-ledgers-from-opening-ledgers">BP-22:
Separate closing ledgers from opening ledgers</a></td>
+ <td style="text-align: left">Not A Problem</td>
+ </tr>
</tbody>
</table>
--
To stop receiving notification emails like this one, please contact
['"[email protected]" <[email protected]>'].
