kafka-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j...@apache.org
Subject kafka git commit: KAFKA-3283; Remove beta from new consumer documentation
Date Mon, 19 Sep 2016 21:26:34 GMT
Repository: kafka
Updated Branches:
  refs/heads/trunk 57ee6ffc8 -> 3281b3c90


KAFKA-3283; Remove beta from new consumer documentation

Include a few clean-ups (also in producer section), mention deprecation plans and reorder
so that the new consumer documentation is before the old consumers.

Author: Ismael Juma <ismael@juma.me.uk>

Reviewers: Jason Gustafson <jason@confluent.io>

Closes #1880 from ijuma/remove-beta-from-new-consumer-documentation


Project: http://git-wip-us.apache.org/repos/asf/kafka/repo
Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/3281b3c9
Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/3281b3c9
Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/3281b3c9

Branch: refs/heads/trunk
Commit: 3281b3c9043edec0b1f8cadfb137851a60d509ef
Parents: 57ee6ff
Author: Ismael Juma <ismael@juma.me.uk>
Authored: Mon Sep 19 14:26:26 2016 -0700
Committer: Jason Gustafson <jason@confluent.io>
Committed: Mon Sep 19 14:26:26 2016 -0700

----------------------------------------------------------------------
 docs/api.html           | 50 +++++++++++++++++++++++---------------------
 docs/documentation.html |  6 +++---
 docs/upgrade.html       |  2 ++
 3 files changed, 31 insertions(+), 27 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kafka/blob/3281b3c9/docs/api.html
----------------------------------------------------------------------
diff --git a/docs/api.html b/docs/api.html
index 2cb9d86..8e4409d 100644
--- a/docs/api.html
+++ b/docs/api.html
@@ -19,7 +19,9 @@ Apache Kafka includes new java clients (in the org.apache.kafka.clients
package)
 
 <h3><a id="producerapi" href="#producerapi">2.1 Producer API</a></h3>
 
-We encourage all new development to use the new Java producer. This client is production
tested and generally both faster and more fully featured than the previous Scala client. You
can use this client by adding a dependency on the client jar using the following example maven
co-ordinates (you can change the version numbers with new releases):
+We recommend the new Java producer for all new development. The old Scala producers have
been deprecated and will be removed in a future major release.
+The new Java producer is production tested and generally faster and more fully featured than
the previous Scala clients. You can use this client by adding a dependency on
+the client jar using the following example maven co-ordinates (you can change the version
numbers with new releases):
 <pre>
 	&lt;dependency&gt;
 	    &lt;groupId&gt;org.apache.kafka&lt;/groupId&gt;
@@ -38,14 +40,28 @@ here</a>.
 
 <h3><a id="consumerapi" href="#consumerapi">2.2 Consumer API</a></h3>
 
-As of the 0.9.0 release we have added a new Java consumer to replace our existing high-level
ZooKeeper-based consumer
-and low-level consumer APIs. This client is considered beta quality. To ensure a smooth upgrade
path
-for users, we still maintain the old 0.8 consumer clients that continue to work on an 0.9
Kafka cluster.
+We recommend the new Java consumer for all new development. The new Java consumer replaces
the high-level ZooKeeper-based consumer and
+low-level consumer APIs (also known as old Scala consumers).
 
-In the following sections we introduce both the old 0.8 consumer APIs (both high-level ConsumerConnector
and low-level SimpleConsumer)
-and the new Java consumer API respectively.
+To ensure a smooth upgrade path, the old Scala consumers are still maintained (although lacking
features like security) and continue to work
+with the current Kafka clusters. The current plan is to deprecate them in the release after
0.10.1.0 and to remove them in a future major release.
 
-<h4><a id="highlevelconsumerapi" href="#highlevelconsumerapi">2.2.1 Old High
Level Consumer API</a></h4>
+In the following sections we introduce new Java consumer API and the old Scala consumer APIs
(both high-level ConsumerConnector and low-level SimpleConsumer).
+
+<h4><a id="newconsumerapi" href="#newconsumerapi">2.2.1 New Consumer API</a></h4>
+This new unified consumer API removes the distinction between the 0.8 high-level and low-level
consumer APIs. You can use this client by adding a dependency on the client jar using the
following example maven co-ordinates (you can change the version numbers with new releases):
+<pre>
+	&lt;dependency&gt;
+	    &lt;groupId&gt;org.apache.kafka&lt;/groupId&gt;
+	    &lt;artifactId&gt;kafka-clients&lt;/artifactId&gt;
+	    &lt;version&gt;0.10.0.0&lt;/version&gt;
+	&lt;/dependency&gt;
+</pre>
+
+Examples showing how to use the consumer are given in the
+<a href="http://kafka.apache.org/0100/javadoc/index.html?org/apache/kafka/clients/consumer/KafkaConsumer.html"
title="Kafka 0.10.0 Javadoc">javadocs</a>.
+
+<h4><a id="highlevelconsumerapi" href="#highlevelconsumerapi">2.2.2 Old High
Level Consumer API</a></h4>
 <pre>
 class Consumer {
   /**
@@ -117,7 +133,7 @@ public interface kafka.javaapi.consumer.ConsumerConnector {
 </pre>
 You can follow
 <a href="https://cwiki.apache.org/confluence/display/KAFKA/Consumer+Group+Example" title="Kafka
0.8 consumer example">this example</a> to learn how to use the high level consumer
api.
-<h4><a id="simpleconsumerapi" href="#simpleconsumerapi">2.2.2 Old Simple Consumer
API</a></h4>
+<h4><a id="simpleconsumerapi" href="#simpleconsumerapi">2.2.3 Old Simple Consumer
API</a></h4>
 <pre>
 class kafka.javaapi.consumer.SimpleConsumer {
   /**
@@ -150,21 +166,7 @@ class kafka.javaapi.consumer.SimpleConsumer {
   public void close();
 }
 </pre>
-For most applications, the high level consumer Api is good enough. Some applications want
features not exposed to the high level consumer yet (e.g., set initial offset when restarting
the consumer). They can instead use our low level SimpleConsumer Api. The logic will be a
bit more complicated and you can follow the example in
-<a href="https://cwiki.apache.org/confluence/display/KAFKA/0.8.0+SimpleConsumer+Example"
title="Kafka 0.8 SimpleConsumer example">here</a>.
-
-<h4><a id="newconsumerapi" href="#newconsumerapi">2.2.3 New Consumer API</a></h4>
-This new unified consumer API removes the distinction between the 0.8 high-level and low-level
consumer APIs. You can use this client by adding a dependency on the client jar using the
following example maven co-ordinates (you can change the version numbers with new releases):
-<pre>
-	&lt;dependency&gt;
-	    &lt;groupId&gt;org.apache.kafka&lt;/groupId&gt;
-	    &lt;artifactId&gt;kafka-clients&lt;/artifactId&gt;
-	    &lt;version&gt;0.10.0.0&lt;/version&gt;
-	&lt;/dependency&gt;
-</pre>
-
-Examples showing how to use the consumer are given in the
-<a href="http://kafka.apache.org/0100/javadoc/index.html?org/apache/kafka/clients/consumer/KafkaConsumer.html"
title="Kafka 0.9.0 Javadoc">javadocs</a>.
+For most applications, the new Java Consumer API is the best option and it's the API we intend
to support going forward. However, if you need to use the SimpleConsumer API, the logic will
be a bit more complicated and you can follow the example <a href="https://cwiki.apache.org/confluence/display/KAFKA/0.8.0+SimpleConsumer+Example"
title="Kafka 0.8 SimpleConsumer example">here</a>.
 
 <h3><a id="streamsapi" href="#streamsapi">2.3 Streams API</a></h3>
 
@@ -184,4 +186,4 @@ Examples showing how to use this library are given in the
 <p>
     Please note that Kafka Streams is a new component of Kafka, and its public APIs may change
in future releases.
     We use the <b>@InterfaceStability.Unstable</b> annotation to denote classes
whose APIs may change without backward-compatibility in future releases.
-</p>
\ No newline at end of file
+</p>

http://git-wip-us.apache.org/repos/asf/kafka/blob/3281b3c9/docs/documentation.html
----------------------------------------------------------------------
diff --git a/docs/documentation.html b/docs/documentation.html
index c3425c0..95d1251 100644
--- a/docs/documentation.html
+++ b/docs/documentation.html
@@ -36,9 +36,9 @@ Prior releases: <a href="/07/documentation.html">0.7.x</a>,
<a href="/08/documen
               <li><a href="#producerapi">2.1 Producer API</a>
               <li><a href="#consumerapi">2.2 Consumer API</a>
                   <ul>
-                      <li><a href="#highlevelconsumerapi">2.2.1 Old High Level
Consumer API</a>
-                      <li><a href="#simpleconsumerapi">2.2.2 Old Simple Consumer
API</a>
-                      <li><a href="#newconsumerapi">2.2.3 New Consumer API</a>
+                      <li><a href="#newconsumerapi">2.2.1 New Consumer API</a>
+                      <li><a href="#highlevelconsumerapi">2.2.2 Old High Level
Consumer API</a>
+                      <li><a href="#simpleconsumerapi">2.2.3 Old Simple Consumer
API</a>
                   </ul>
               <li><a href="#streamsapi">2.3 Streams API</a>
           </ul>

http://git-wip-us.apache.org/repos/asf/kafka/blob/3281b3c9/docs/upgrade.html
----------------------------------------------------------------------
diff --git a/docs/upgrade.html b/docs/upgrade.html
index d4ba71a..d8c2b4e 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -34,6 +34,8 @@ However, please notice the <a href="#upgrade_10_1_breaking">Potential
breaking c
 
 <h5><a id="upgrade_1010_notable" href="#upgrade_1010_notable">Notable changes
in 0.10.1.0</a></h5>
 <ul>
+    <li> The new Java consumer is no longer in beta and we recommend it for all new
development. The old Scala consumers are still supported, but they will be deprecated in the
next release
+         and will be removed in a future major release. </li>
     <li> The BrokerState "RunningAsController" (value 4) has been removed. Due to a
bug, a broker would only be in this state briefly before transitioning out of it and hence
the impact of the removal should be minimal. The recommended way to detect if a given broker
is the controller is via the kafka.controller:type=KafkaController,name=ActiveControllerCount
metric. </li>
 </ul>
 


Mime
View raw message