kafka-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ij...@apache.org
Subject kafka git commit: MINOR: Improve documentation of AdminClient and fix exception thrown
Date Tue, 26 Sep 2017 07:20:53 GMT
Repository: kafka
Updated Branches:
  refs/heads/trunk 51611b1b7 -> 4e43a7231


MINOR: Improve documentation of AdminClient and fix exception thrown

Make documentation consistent across methods and throw
IllegalStateException instead of IllegalArgumentException in
some cases.

Also include a couple of minor fixes in upgrade.html.

Author: Dong Lin <lindong28@gmail.com>

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

Closes #3781 from lindong28/minor-admin-client-comment


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

Branch: refs/heads/trunk
Commit: 4e43a7231dafa149de908eac79c437d65a9de4fb
Parents: 51611b1
Author: Dong Lin <lindong28@gmail.com>
Authored: Tue Sep 26 08:14:18 2017 +0100
Committer: Ismael Juma <ismael@juma.me.uk>
Committed: Tue Sep 26 08:20:26 2017 +0100

----------------------------------------------------------------------
 .../apache/kafka/clients/admin/AdminClient.java | 59 +++++++++++++++-----
 .../kafka/clients/admin/KafkaAdminClient.java   |  8 +--
 docs/upgrade.html                               |  4 +-
 3 files changed, 51 insertions(+), 20 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kafka/blob/4e43a723/clients/src/main/java/org/apache/kafka/clients/admin/AdminClient.java
----------------------------------------------------------------------
diff --git a/clients/src/main/java/org/apache/kafka/clients/admin/AdminClient.java b/clients/src/main/java/org/apache/kafka/clients/admin/AdminClient.java
index 0276fc3..61d6db0 100644
--- a/clients/src/main/java/org/apache/kafka/clients/admin/AdminClient.java
+++ b/clients/src/main/java/org/apache/kafka/clients/admin/AdminClient.java
@@ -90,6 +90,8 @@ public abstract class AdminClient implements AutoCloseable {
      * This is a convenience method for #{@link #createTopics(Collection, CreateTopicsOptions)}
with default options.
      * See the overload for more details.
      *
+     * This operation is supported by brokers with version 0.10.1.0 or higher.
+     *
      * @param newTopics         The new topics to create.
      * @return                  The CreateTopicsResult.
      */
@@ -118,8 +120,8 @@ public abstract class AdminClient implements AutoCloseable {
                                                     CreateTopicsOptions options);
 
     /**
-     * Similar to #{@link AdminClient#deleteTopics(Collection<String>, DeleteTopicsOptions)},
-     * but uses the default options.
+     * This is a convenience method for #{@link AdminClient#deleteTopics(Collection, DeleteTopicsOptions)}
+     * with default options. See the overload for more details.
      *
      * This operation is supported by brokers with version 0.10.1.0 or higher.
      *
@@ -133,6 +135,8 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Delete a batch of topics.
      *
+     * This operation is not transactional so it may succeed for some topics while fail for
others.
+     *
      * It may take several seconds after AdminClient#deleteTopics returns
      * success for all the brokers to become aware that the topics are gone.
      * During this time, AdminClient#listTopics and AdminClient#describeTopics
@@ -153,6 +157,9 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * List the topics available in the cluster with the default options.
      *
+     * This is a convenience method for #{@link AdminClient#listTopics(ListTopicsOptions)}
with default options.
+     * See the overload for more details.
+     *
      * @return                  The ListTopicsResult.
      */
     public ListTopicsResult listTopics() {
@@ -170,7 +177,8 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Describe some topics in the cluster, with the default options.
      *
-     * See {@link AdminClient#describeTopics(Collection<String>, DescribeTopicsOptions)}
+     * This is a convenience method for #{@link AdminClient#describeTopics(Collection, DescribeTopicsOptions)}
with
+     * default options. See the overload for more details.
      *
      * @param topicNames        The names of the topics to describe.
      *
@@ -194,6 +202,9 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Get information about the nodes in the cluster, using the default options.
      *
+     * This is a convenience method for #{@link AdminClient#describeCluster(DescribeClusterOptions)}
with default options.
+     * See the overload for more details.
+     *
      * @return                  The DescribeClusterResult.
      */
     public DescribeClusterResult describeCluster() {
@@ -209,8 +220,8 @@ public abstract class AdminClient implements AutoCloseable {
     public abstract DescribeClusterResult describeCluster(DescribeClusterOptions options);
 
     /**
-     * Similar to #{@link AdminClient#describeAcls(AclBindingFilter, DescribeAclsOptions)},
-     * but uses the default options.
+     * This is a convenience method for #{@link AdminClient#describeAcls(AclBindingFilter,
DescribeAclsOptions)} with
+     * default options. See the overload for more details.
      *
      * This operation is supported by brokers with version 0.11.0.0 or higher.
      *
@@ -236,8 +247,8 @@ public abstract class AdminClient implements AutoCloseable {
     public abstract DescribeAclsResult describeAcls(AclBindingFilter filter, DescribeAclsOptions
options);
 
     /**
-     * Similar to #{@link AdminClient#createAcls(Collection<AclBinding>, CreateAclsOptions)},
-     * but uses the default options.
+     * This is a convenience method for #{@link AdminClient#createAcls(Collection<AclBinding>,
CreateAclsOptions)} with
+     * default options. See the overload for more details.
      *
      * This operation is supported by brokers with version 0.11.0.0 or higher.
      *
@@ -251,6 +262,8 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Creates access control lists (ACLs) which are bound to specific resources.
      *
+     * This operation is not transactional so it may succeed for some ACLs while fail for
others.
+     *
      * If you attempt to add an ACL that duplicates an existing ACL, no error will be raised,
but
      * no changes will be made.
      *
@@ -263,8 +276,8 @@ public abstract class AdminClient implements AutoCloseable {
     public abstract CreateAclsResult createAcls(Collection<AclBinding> acls, CreateAclsOptions
options);
 
     /**
-     * Similar to #{@link AdminClient#deleteAcls(Collection<AclBinding>, DeleteAclsOptions)},
-     * but uses the default options.
+     * This is a convenience method for #{@link AdminClient#deleteAcls(Collection<AclBinding>,
DeleteAclsOptions)} with default options.
+     * See the overload for more details.
      *
      * This operation is supported by brokers with version 0.11.0.0 or higher.
      *
@@ -278,6 +291,8 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Deletes access control lists (ACLs) according to the supplied filters.
      *
+     * This operation is not transactional so it may succeed for some ACLs while fail for
others.
+     *
      * This operation is supported by brokers with version 0.11.0.0 or higher.
      *
      * @param filters           The filters to use.
@@ -287,12 +302,13 @@ public abstract class AdminClient implements AutoCloseable {
     public abstract DeleteAclsResult deleteAcls(Collection<AclBindingFilter> filters,
DeleteAclsOptions options);
 
 
-     /**
+    /**
      * Get the configuration for the specified resources with the default options.
      *
-     * See {@link #describeConfigs(Collection, DescribeConfigsOptions)} for more details.
-      *
-      * This operation is supported by brokers with version 0.11.0.0 or higher.
+     * This is a convenience method for #{@link AdminClient#describeConfigs(Collection, DescribeConfigsOptions)}
with default options.
+     * See the overload for more details.
+     *
+     * This operation is supported by brokers with version 0.11.0.0 or higher.
      *
      * @param resources         The resources (topic and broker resource types are currently
supported)
      * @return                  The DescribeConfigsResult
@@ -324,7 +340,8 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Update the configuration for the specified resources with the default options.
      *
-     * See {@link #alterConfigs(Map, AlterConfigsOptions)} for more details.
+     * This is a convenience method for #{@link AdminClient#alterConfigs(Map, AlterConfigsOptions)}
with default options.
+     * See the overload for more details.
      *
      * This operation is supported by brokers with version 0.11.0.0 or higher.
      *
@@ -339,6 +356,9 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Update the configuration for the specified resources with the default options.
      *
+     * Updates are not transactional so they may succeed for some resources while fail for
others. The configs for
+     * a particular resource are updated atomically.
+     *
      * This operation is supported by brokers with version 0.11.0.0 or higher.
      *
      * @param configs         The resources with their configs (topic is the only resource
type with configs that can
@@ -353,6 +373,9 @@ public abstract class AdminClient implements AutoCloseable {
      * before the replica has been created on the broker. It will support moving replicas
that have already been created after
      * KIP-113 is fully implemented.
      *
+     * This is a convenience method for #{@link AdminClient#alterReplicaDir(Map, AlterReplicaDirOptions)}
with default options.
+     * See the overload for more details.
+     *
      * This operation is supported by brokers with version 1.0.0 or higher.
      *
      * @param replicaAssignment  The replicas with their log directory absolute path
@@ -367,6 +390,8 @@ public abstract class AdminClient implements AutoCloseable {
      * before the replica has been created on the broker. It will support moving replicas
that have already been created after
      * KIP-113 is fully implemented.
      *
+     * This operation is not transactional so it may succeed for some replicas while fail
for others.
+     *
      * This operation is supported by brokers with version 1.0.0 or higher.
      *
      * @param replicaAssignment  The replicas with their log directory absolute path
@@ -378,6 +403,9 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Query the information of all log directories on the given set of brokers
      *
+     * This is a convenience method for #{@link AdminClient#describeLogDirs(Collection, DescribeLogDirsOptions)}
with default options.
+     * See the overload for more details.
+     *
      * This operation is supported by brokers with version 1.0.0 or higher.
      *
      * @param brokers     A list of brokers
@@ -401,6 +429,9 @@ public abstract class AdminClient implements AutoCloseable {
     /**
      * Query the replica log directory information for the specified replicas.
      *
+     * This is a convenience method for #{@link AdminClient#describeReplicaLogDir(Collection,
DescribeReplicaLogDirOptions)}
+     * with default options. See the overload for more details.
+     *
      * This operation is supported by brokers with version 1.0.0 or higher.
      *
      * @param replicas      The replicas to query

http://git-wip-us.apache.org/repos/asf/kafka/blob/4e43a723/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
----------------------------------------------------------------------
diff --git a/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java b/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
index 2447909..88339bf 100644
--- a/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
+++ b/clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java
@@ -1694,7 +1694,7 @@ public class KafkaAdminClient extends AdminClient {
                         TopicPartitionReplica replica = new TopicPartitionReplica(tp.topic(),
tp.partition(), brokerId);
                         KafkaFutureImpl<Void> future = futures.get(replica);
                         if (future == null) {
-                            handleFailure(new IllegalArgumentException(
+                            handleFailure(new IllegalStateException(
                                 "The partition " + tp + " in the response from broker " +
brokerId + " is not in the request"));
                         } else if (error == Errors.NONE) {
                             future.complete(null);
@@ -1796,8 +1796,8 @@ public class KafkaAdminClient extends AdminClient {
                         // No replica info will be provided if the log directory is offline
                         if (logDirInfo.error == Errors.KAFKA_STORAGE_ERROR)
                             continue;
-                        else if (logDirInfo.error != Errors.NONE)
-                            handleFailure(new IllegalArgumentException(
+                        if (logDirInfo.error != Errors.NONE)
+                            handleFailure(new IllegalStateException(
                                 "The error " + logDirInfo.error + " for log directory " +
logDir + " in the response from broker " + brokerId + " is illegal"));
 
                         for (Map.Entry<TopicPartition, DescribeLogDirsResponse.ReplicaInfo>
replicaInfoEntry: logDirInfo.replicaInfos.entrySet()) {
@@ -1805,7 +1805,7 @@ public class KafkaAdminClient extends AdminClient {
                             DescribeLogDirsResponse.ReplicaInfo replicaInfo = replicaInfoEntry.getValue();
                             ReplicaLogDirInfo replicaLogDirInfo = replicaDirInfoByPartition.get(tp);
                             if (replicaLogDirInfo == null) {
-                                handleFailure(new IllegalArgumentException(
+                                handleFailure(new IllegalStateException(
                                     "The partition " + tp + " in the response from broker
" + brokerId + " is not in the request"));
                             } else if (replicaInfo.isFuture) {
                                 replicaDirInfoByPartition.put(tp, new ReplicaLogDirInfo(replicaLogDirInfo.getCurrentReplicaLogDir(),

http://git-wip-us.apache.org/repos/asf/kafka/blob/4e43a723/docs/upgrade.html
----------------------------------------------------------------------
diff --git a/docs/upgrade.html b/docs/upgrade.html
index ce750ea..d265bc9 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -33,7 +33,7 @@
         </ul>
     </li>
     <li> Upgrade the brokers one at a time: shut down the broker, update the code,
and restart it. </li>
-    <li> Once the entire cluster is upgraded, bump the protocol version by editing
<code>inter.broker.protocol.version</code> and setting it to 1.0.0.
+    <li> Once the entire cluster is upgraded, bump the protocol version by editing
<code>inter.broker.protocol.version</code> and setting it to 1.0.
     <li> Restart the brokers one by one for the new protocol version to take effect.
</li>
 </ol>
 
@@ -52,7 +52,7 @@
         to retain the previous behavior should set the broker config <code>delete.topic.enable</code>
to <code>false</code>. Keep in mind that topic deletion removes data and the operation
is not reversible (i.e. there is no "undelete" operation)</li>
     <li>For topics that support timestamp search if no offset can be found for a partition,
that partition is now included in the search result with a null offset value. Previously,
the partition was not included in the map.
         This change was made to make the search behavior consistent with the case of topics
not supporting timestamp search.
-    <li>If the <code>inter.broker.protocol.version</code> is 0.11.1 or
later, a broker will now stay online to serve replicas
+    <li>If the <code>inter.broker.protocol.version</code> is 1.0 or later,
a broker will now stay online to serve replicas
         on live log directories even if there are offline log directories. A log directory
may become offline due to IOException
         caused by hardware failure. Users need to monitor the per-broker metric <code>offlineLogDirectoryCount</code>
to check
         whether there is offline log directory. </li>


Mime
View raw message