You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@bookkeeper.apache.org by gi...@apache.org on 2018/02/02 07:24:56 UTC
[bookkeeper] branch asf-site updated: Updated site at revision
49b011b
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 7c8381d Updated site at revision 49b011b
7c8381d is described below
commit 7c8381d81b2b5492af1ffabfd394a00ee1e70d7b
Author: jenkins <bu...@apache.org>
AuthorDate: Fri Feb 2 07:24:54 2018 +0000
Updated site at revision 49b011b
---
content/bps/BP-27-new-bookkeeper-cli/index.html | 393 ++++++++++++++++++++++
content/community/bookkeeper_proposals/index.html | 6 +-
2 files changed, 398 insertions(+), 1 deletion(-)
diff --git a/content/bps/BP-27-new-bookkeeper-cli/index.html b/content/bps/BP-27-new-bookkeeper-cli/index.html
new file mode 100644
index 0000000..13eeb43
--- /dev/null
+++ b/content/bps/BP-27-new-bookkeeper-cli/index.html
@@ -0,0 +1,393 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Apache BookKeeper™ - BP-27: New BookKeeper CLI</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.1/overview/overview">
+ Release 4.6.1
+
+ </a>
+
+ <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/testing">Testing 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-27: New BookKeeper CLI</h1>
+ </div>
+ </div>
+
+ </nav>
+
+
+ </header>
+
+ <hr />
+
+ <div class="content is-medium">
+ <section class="bk-community-content">
+ <h3 id="motivation">Motivation</h3>
+
+<p><code class="highlighter-rouge">BookieShell</code> is the current bookkeeper cli for interacting and operating a bookkeeper cluster. However, this class is getting bigger with more commands added to it. It is facing a few problems for maintenance and extensibility.</p>
+
+<ul>
+ <li>All commands sit in one gaint shell class. It is hard to tell if a command is used for managing a bookie only or if a command is used for managing a cluster.</li>
+ <li>Lack of unit tests. This class has very few test coverage. Most of the commands (introduced in early days) don’t have a unit test.</li>
+ <li>Lack of extensibility. If a new function component (for example, dlog) is introduced, it is a bit hard to extend this CLI to have commands for new function component.</li>
+</ul>
+
+<p>All these problems lead to the proposal here. This proposal is to propose refactoring/redesigning the bookkeeper CLI to allow better managebility for maintenance, better test coverage and better extensibility for new function components.</p>
+
+<h3 id="public-interfaces">Public Interfaces</h3>
+
+<p>This proposal will not change existing <code class="highlighter-rouge">BookieShell</code>. All functionalities will remain as same when using <code class="highlighter-rouge">bin/bookkeeper shell</code>.
+Instead a new module <code class="highlighter-rouge">bookkeeper-tools</code> will be introduced for developing the new BookKeeper CLI and a new script <code class="highlighter-rouge">bin/bookkeeper-cli</code> for executing CLI commands.</p>
+
+<p>The new bookkeeper CLI follows the pattern that pulsar-admin is using. The CLI commandline format would be:</p>
+
+<div class="highlighter-rouge"><pre class="highlight"><code>$ bookkeeper-cli [general options] <command-group> <command> [options of command]
+</code></pre>
+</div>
+
+<h4 id="commandgroup-and-command">CommandGroup and Command</h4>
+
+<p><code class="highlighter-rouge"><command-group></code> and <code class="highlighter-rouge"><command></code> are introduced for categorizing the commands into groups. So the commands within same group have same operation scope (e.g. whether a command is applied to a cluster or a command is applied to a bookie).</p>
+
+<p>When a new function component is introduced, all its related commands can be managed in its own command group and register the group to CLI. This would allow flexible extensibility and make maintenance easier and clearer.</p>
+
+<p>The proposed command groups are:</p>
+
+<ul>
+ <li>“cluster”: commands that operate on a cluster</li>
+ <li>“bookie”: commands that operate on a single bookie</li>
+ <li>“metadata”: commands that operate with metadata store</li>
+ <li>“client”: commands that use a bookkeeper client for interacting with a cluster.</li>
+</ul>
+
+<p>Example Outputs for the new BookKeeper CLI:</p>
+
+<ul>
+ <li>Show all command groups: <code class="highlighter-rouge">bookkeeper-cli --help</code></li>
+</ul>
+
+<div class="highlighter-rouge"><pre class="highlight"><code>Usage: bookkeeper-cli [options] [command] [command options]
+ Options:
+ -c, --conf
+ Bookie Configuration File
+ -h, --help
+ Show this help message
+ Default: false
+ Commands:
+ bookie Commands on operating a single bookie
+ Usage: bookie [options]
+
+ client Commands that interact with a cluster
+ Usage: client [options]
+
+ cluster Commands that operate a cluster
+ Usage: cluster [options]
+
+ metadata Commands that interact with metadata storage
+ Usage: metadata [options]
+</code></pre>
+</div>
+<ul>
+ <li>Show commands under <code class="highlighter-rouge">cluster</code>: <code class="highlighter-rouge">bookkeeper-cli cluster --help</code>
+ <div class="highlighter-rouge"><pre class="highlight"><code>Usage: bookie-shell cluster [options] [command] [command options]
+Commands:
+ listbookies List the bookies, which are running as either readwrite or readonly mode.
+ Usage: listbookies [options]
+ Options:
+ -ro, --readonly
+ Print readonly bookies
+ Default: false
+ -rw, --readwrite
+ Print readwrite bookies
+ Default: false
+</code></pre>
+ </div>
+ </li>
+</ul>
+
+<h3 id="proposed-changes">Proposed Changes</h3>
+
+<ul>
+ <li>Introduced a new module called <code class="highlighter-rouge">bookkeeper-tools</code> for developing the new CLI.</li>
+ <li>The new CLI will use <a href="http://jcommander.org">JCommander</a> for parse command line paramters: better on supporting this proposal commandline syntax.</li>
+ <li>All the actual logic of the commands will be organized under <code class="highlighter-rouge">org.apache.bookkeeper.tools.cli.commands</code>. Each command group has its own subpackage and each command will be a class file under that command-group subpackage.
+Doing this provides better testability, since the command logic is limited in one file rather than in a gaint shell class. Proposed layout can be found <a href="https://github.com/sijie/bookkeeper/tree/bookie_shell_refactor/bookkeeper-server/src/main/java/org/apache/bookkeeper/tools/cli/commands">here</a>.</li>
+ <li>For each command: the logic of a command will be moved out of <code class="highlighter-rouge">BookieShell</code> to its own class <code class="highlighter-rouge">org.apache.bookkeeper.tools.cli.commands.<command-group>.<CommandClass>.java</code>. The old BookieShell will use the new Command class and delegate the actual logic.</li>
+</ul>
+
+<p>An initial prototype is available: https://github.com/sijie/bookkeeper/tree/bookie_shell_refactor</p>
+
+<h3 id="compatibility-deprecation-and-migration-plan">Compatibility, Deprecation, and Migration Plan</h3>
+
+<p><code class="highlighter-rouge">bin/bookkeeper shell</code> and <code class="highlighter-rouge">bin/bookkeeper-cli</code> will co-exist for a few releases. After <code class="highlighter-rouge">bin/bookkeeper-cli</code> takes over all the functionalities of <code class="highlighter-rouge">BookieShell</code>, we will consider deprecating the old <code class="highlighter-rouge">BookieShell</code>.</p>
+
+<p>So no compatibility concern at this moment.</p>
+
+<h3 id="test-plan">Test Plan</h3>
+
+<p>When a command is moved from BookieShell to <code class="highlighter-rouge">org.apache.bookkeeper.tools.cli</code>, several unit tests should be added:</p>
+
+<ul>
+ <li>Unit tests for the command logic itself.</li>
+ <li>Unit tests in new CLI for this command.</li>
+ <li>Unit tests in old BookieShell for this command.</li>
+</ul>
+
+<h3 id="rejected-alternatives">Rejected Alternatives</h3>
+
+<p>Another proposal is to redesign the bookkeeper CLI using admin REST api. This is not considered at this moment because some of the commands are not well supported in admin REST api (for example, metaformat, bookieformat, and most of the commands
+used for troubleshooting individual bookies). If we want to support a CLI using admin REST api, we can have a separate CLI called <code class="highlighter-rouge">bookkeeper-rest-ci</code> to use admin REST api for operating the cluster.</p>
+
+ </section>
+
+
+ </div>
+ </div>
+ </div>
+</div>
+ </main>
+
+ <footer class="footer">
+ <div class="container">
+ <div class="content has-text-centered">
+ <p>
+ Copyright © 2016 - 2018 <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 a62cc52..6b9a6d7 100644
--- a/content/community/bookkeeper_proposals/index.html
+++ b/content/community/bookkeeper_proposals/index.html
@@ -347,7 +347,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: 27</em></p>
+<p><em>Next Proposal Number: 28</em></p>
<h3 id="inprogress">Inprogress</h3>
@@ -387,6 +387,10 @@ of the thread is of the format <code class="highlighter-rouge">[DISCUSS] BP-<
<td style="text-align: left"><a href="../../bps/BP-26-move-distributedlog-core-library">BP-26: Move distributedlog library as part of bookkeeper</a></td>
<td style="text-align: left">Accepted</td>
</tr>
+ <tr>
+ <td style="text-align: left"><a href="../../bps/BP-27-new-bookkeeper-cli">BP-27: New BookKeeper CLI</a></td>
+ <td style="text-align: left">Draft</td>
+ </tr>
</tbody>
</table>
--
To stop receiving notification emails like this one, please contact
git-site-role@apache.org.