From 28dab08cc09706351ecc4b7836b1f99dc029ba7f Mon Sep 17 00:00:00 2001 From: Dong Lin Date: Sun, 3 Sep 2017 12:09:43 -0700 Subject: [PATCH 1/2] MINOR: Improve documentation of AdminClient --- .../kafka/clients/admin/AdminClient.java | 65 ++++++++++++++----- .../kafka/clients/admin/KafkaAdminClient.java | 8 +-- docs/upgrade.html | 2 +- 3 files changed, 53 insertions(+), 22 deletions(-) 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 3f4a07c8b01da..d0cfbaa43bfed 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 @@ -87,6 +87,9 @@ public void close() { /** * Create a batch of new topics with the default options. * + * Similar to #{@link AdminClient#createTopics(Collection, CreateTopicsOptions)}, + * but uses the default options. See {@link #createTopics(Collection, CreateTopicsOptions)} for more details. + * * This operation is supported by brokers with version 0.10.1.0 or higher. * * @param newTopics The new topics to create. @@ -99,6 +102,8 @@ public CreateTopicsResult createTopics(Collection newTopics) { /** * Create a batch of new topics. * + * This operation is not transactional so it may succeed for some topics while fail for others. + * * It may take several seconds after AdminClient#createTopics returns * success for all the brokers to become aware that the topics have been created. * During this time, AdminClient#listTopics and AdminClient#describeTopics @@ -115,8 +120,8 @@ public abstract CreateTopicsResult createTopics(Collection newTopics, CreateTopicsOptions options); /** - * Similar to #{@link AdminClient#deleteTopics(Collection, DeleteTopicsOptions)}, - * but uses the default options. + * Similar to #{@link AdminClient#deleteTopics(Collection, DeleteTopicsOptions)}, + * but uses the default options. See {@link #deleteTopics(Collection, DeleteTopicsOptions)} for more details. * * This operation is supported by brokers with version 0.10.1.0 or higher. * @@ -130,6 +135,8 @@ public DeleteTopicsResult deleteTopics(Collection topics) { /** * 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 @@ -150,6 +157,8 @@ public DeleteTopicsResult deleteTopics(Collection topics) { /** * List the topics available in the cluster with the default options. * + * Similar to #{@link AdminClient#listTopics(ListTopicsOptions)}, but uses the default options. + * * @return The ListTopicsResult. */ public ListTopicsResult listTopics() { @@ -167,7 +176,7 @@ public ListTopicsResult listTopics() { /** * Describe some topics in the cluster, with the default options. * - * See {@link AdminClient#describeTopics(Collection, DescribeTopicsOptions)} + * Similar to #{@link AdminClient#describeTopics(Collection, DescribeTopicsOptions)}, but uses the default options. * * @param topicNames The names of the topics to describe. * @@ -191,6 +200,8 @@ public abstract DescribeTopicsResult describeTopics(Collection topicName /** * Get information about the nodes in the cluster, using the default options. * + * Similar to #{@link AdminClient#describeCluster(DescribeClusterOptions)}, but uses the default options. + * * @return The DescribeClusterResult. */ public DescribeClusterResult describeCluster() { @@ -207,7 +218,7 @@ public DescribeClusterResult describeCluster() { /** * Similar to #{@link AdminClient#describeAcls(AclBindingFilter, DescribeAclsOptions)}, - * but uses the default options. + * but uses the default options. See {@link #describeAcls(AclBindingFilter, DescribeAclsOptions)} for more details * * This operation is supported by brokers with version 0.11.0.0 or higher. * @@ -234,7 +245,7 @@ public DescribeAclsResult describeAcls(AclBindingFilter filter) { /** * Similar to #{@link AdminClient#createAcls(Collection, CreateAclsOptions)}, - * but uses the default options. + * but uses the default options. See {@link #createAcls(Collection, CreateAclsOptions)} for more details. * * This operation is supported by brokers with version 0.11.0.0 or higher. * @@ -248,6 +259,8 @@ public CreateAclsResult createAcls(Collection acls) { /** * 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. * @@ -261,7 +274,7 @@ public CreateAclsResult createAcls(Collection acls) { /** * Similar to #{@link AdminClient#deleteAcls(Collection, DeleteAclsOptions)}, - * but uses the default options. + * but uses the default options. See {@link #deleteAcls(Collection, DeleteAclsOptions)} for more details. * * This operation is supported by brokers with version 0.11.0.0 or higher. * @@ -275,6 +288,8 @@ public DeleteAclsResult deleteAcls(Collection filters) { /** * 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. @@ -284,12 +299,13 @@ public DeleteAclsResult deleteAcls(Collection filters) { public abstract DeleteAclsResult deleteAcls(Collection 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. + * Similar to #{@link AdminClient#describeConfigs(Collection, DescribeConfigsOptions)}, + * but uses 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. * * @param resources The resources (topic and broker resource types are currently supported) * @return The DescribeConfigsResult @@ -321,7 +337,8 @@ public abstract DescribeConfigsResult describeConfigs(Collection /** * Update the configuration for the specified resources with the default options. * - * See {@link #alterConfigs(Map, AlterConfigsOptions)} for more details. + * Similar to #{@link AdminClient#alterConfigs(Map, AlterConfigsOptions)}, + * but uses the default options. See {@link #alterConfigs(Map, AlterConfigsOptions)} for more details * * This operation is supported by brokers with version 0.11.0.0 or higher. * @@ -336,6 +353,9 @@ public AlterConfigsResult alterConfigs(Map configs) { /** * 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 @@ -350,7 +370,10 @@ public AlterConfigsResult alterConfigs(Map configs) { * 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 supported by brokers with version 1.0.0 or higher. + * Similar to #{@link AdminClient#alterReplicaDir(Map, AlterReplicaDirOptions)}, + * but uses the default options. See {@link #alterReplicaDir(Map, AlterReplicaDirOptions)} for more details + * + * This operation is supported by brokers with version 1.0 or higher. * * @param replicaAssignment The replicas with their log directory absolute path * @return The AlterReplicaDirResult @@ -364,7 +387,9 @@ public AlterReplicaDirResult alterReplicaDir(Map * 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 supported by brokers with version 1.0.0 or higher. + * 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 or higher. * * @param replicaAssignment The replicas with their log directory absolute path * @param options The options to use when changing replica dir @@ -375,7 +400,10 @@ public AlterReplicaDirResult alterReplicaDir(Map /** * Query the information of all log directories on the given set of brokers * - * This operation is supported by brokers with version 1.0.0 or higher. + * Similar to #{@link AdminClient#describeLogDirs(Collection, DescribeLogDirsOptions)}, + * but uses the default options. + * + * This operation is supported by brokers with version 1.0 or higher. * * @param brokers A list of brokers * @return The DescribeLogDirsResult @@ -387,7 +415,7 @@ public DescribeLogDirsResult describeLogDirs(Collection brokers) { /** * Query the information of all log directories on the given set of brokers * - * This operation is supported by brokers with version 1.0.0 or higher. + * This operation is supported by brokers with version 1.0 or higher. * * @param brokers A list of brokers * @param options The options to use when querying log dir info @@ -398,7 +426,10 @@ public DescribeLogDirsResult describeLogDirs(Collection brokers) { /** * Query the replica log directory information for the specified replicas. * - * This operation is supported by brokers with version 1.0.0 or higher. + * Similar to #{@link AdminClient#describeReplicaLogDir(Collection, DescribeReplicaLogDirOptions)}, + * but uses the default options. + * + * This operation is supported by brokers with version 1.0 or higher. * * @param replicas The replicas to query * @return The DescribeReplicaLogDirResult @@ -410,7 +441,7 @@ public DescribeReplicaLogDirResult describeReplicaLogDir(Collection 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); @@ -1759,8 +1759,8 @@ public void handleResponse(AbstractResponse abstractResponse) { // 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 replicaInfoEntry: logDirInfo.replicaInfos.entrySet()) { @@ -1768,7 +1768,7 @@ else if (logDirInfo.error != Errors.NONE) 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(), diff --git a/docs/upgrade.html b/docs/upgrade.html index ed0f9cfa16a8f..103795ef730b5 100644 --- a/docs/upgrade.html +++ b/docs/upgrade.html @@ -33,7 +33,7 @@

Upgrading from 0.8.x, 0.9.x, 0.1
  • Upgrade the brokers one at a time: shut down the broker, update the code, and restart it.
    • -
  • Once the entire cluster is upgraded, bump the protocol version by editing inter.broker.protocol.version and setting it to 1.0.0. +
  • Once the entire cluster is upgraded, bump the protocol version by editing inter.broker.protocol.version and setting it to 1.0.
  • Restart the brokers one by one for the new protocol version to take effect.
    • From 09c6ab3a422112cc90f03c19c0d84d6ba89a301c Mon Sep 17 00:00:00 2001 From: Dong Lin Date: Tue, 19 Sep 2017 11:04:47 -0700 Subject: [PATCH 2/2] Address comments --- .../kafka/clients/admin/AdminClient.java | 63 ++++++++++--------- docs/upgrade.html | 2 +- 2 files changed, 35 insertions(+), 30 deletions(-) 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 d0cfbaa43bfed..db066c3f2debc 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 @@ -87,8 +87,10 @@ public void close() { /** * Create a batch of new topics with the default options. * - * Similar to #{@link AdminClient#createTopics(Collection, CreateTopicsOptions)}, - * but uses the default options. See {@link #createTopics(Collection, CreateTopicsOptions)} for more details. + * @see AdminClient#createTopics(Collection, CreateTopicsOptions) + * + * This is a convenience method for #{@link AdminClient#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. * @@ -120,8 +122,8 @@ public abstract CreateTopicsResult createTopics(Collection newTopics, CreateTopicsOptions options); /** - * Similar to #{@link AdminClient#deleteTopics(Collection, DeleteTopicsOptions)}, - * but uses the default options. See {@link #deleteTopics(Collection, DeleteTopicsOptions)} for more details. + * 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. * @@ -157,7 +159,8 @@ public DeleteTopicsResult deleteTopics(Collection topics) { /** * List the topics available in the cluster with the default options. * - * Similar to #{@link AdminClient#listTopics(ListTopicsOptions)}, but uses 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. */ @@ -176,7 +179,8 @@ public ListTopicsResult listTopics() { /** * Describe some topics in the cluster, with the default options. * - * Similar to #{@link AdminClient#describeTopics(Collection, DescribeTopicsOptions)}, but uses the default options. + * 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. * @@ -200,7 +204,8 @@ public abstract DescribeTopicsResult describeTopics(Collection topicName /** * Get information about the nodes in the cluster, using the default options. * - * Similar to #{@link AdminClient#describeCluster(DescribeClusterOptions)}, but uses 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. */ @@ -217,8 +222,8 @@ public DescribeClusterResult describeCluster() { public abstract DescribeClusterResult describeCluster(DescribeClusterOptions options); /** - * Similar to #{@link AdminClient#describeAcls(AclBindingFilter, DescribeAclsOptions)}, - * but uses the default options. See {@link #describeAcls(AclBindingFilter, DescribeAclsOptions)} for more details + * 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. * @@ -244,8 +249,8 @@ public DescribeAclsResult describeAcls(AclBindingFilter filter) { public abstract DescribeAclsResult describeAcls(AclBindingFilter filter, DescribeAclsOptions options); /** - * Similar to #{@link AdminClient#createAcls(Collection, CreateAclsOptions)}, - * but uses the default options. See {@link #createAcls(Collection, CreateAclsOptions)} for more details. + * This is a convenience method for #{@link AdminClient#createAcls(Collection, CreateAclsOptions)} with default options. + * See the overload for more details. * * This operation is supported by brokers with version 0.11.0.0 or higher. * @@ -273,8 +278,8 @@ public CreateAclsResult createAcls(Collection acls) { public abstract CreateAclsResult createAcls(Collection acls, CreateAclsOptions options); /** - * Similar to #{@link AdminClient#deleteAcls(Collection, DeleteAclsOptions)}, - * but uses the default options. See {@link #deleteAcls(Collection, DeleteAclsOptions)} for more details. + * This is a convenience method for #{@link AdminClient#deleteAcls(Collection, DeleteAclsOptions)} with default options. + * See the overload for more details. * * This operation is supported by brokers with version 0.11.0.0 or higher. * @@ -302,8 +307,8 @@ public DeleteAclsResult deleteAcls(Collection filters) { /** * Get the configuration for the specified resources with the default options. * - * Similar to #{@link AdminClient#describeConfigs(Collection, DescribeConfigsOptions)}, - * but uses the default options. See {@link #describeConfigs(Collection, DescribeConfigsOptions)} for more details + * 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. * @@ -337,8 +342,8 @@ public abstract DescribeConfigsResult describeConfigs(Collection /** * Update the configuration for the specified resources with the default options. * - * Similar to #{@link AdminClient#alterConfigs(Map, AlterConfigsOptions)}, - * but uses 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. * @@ -370,10 +375,10 @@ public AlterConfigsResult alterConfigs(Map configs) { * 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. * - * Similar to #{@link AdminClient#alterReplicaDir(Map, AlterReplicaDirOptions)}, - * but uses the default options. See {@link #alterReplicaDir(Map, AlterReplicaDirOptions)} for more details + * 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 or higher. + * This operation is supported by brokers with version 1.0.0 or higher. * * @param replicaAssignment The replicas with their log directory absolute path * @return The AlterReplicaDirResult @@ -389,7 +394,7 @@ public AlterReplicaDirResult alterReplicaDir(Map * * 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 or higher. + * This operation is supported by brokers with version 1.0.0 or higher. * * @param replicaAssignment The replicas with their log directory absolute path * @param options The options to use when changing replica dir @@ -400,10 +405,10 @@ public AlterReplicaDirResult alterReplicaDir(Map /** * Query the information of all log directories on the given set of brokers * - * Similar to #{@link AdminClient#describeLogDirs(Collection, DescribeLogDirsOptions)}, - * but uses the default options. + * 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 or higher. + * This operation is supported by brokers with version 1.0.0 or higher. * * @param brokers A list of brokers * @return The DescribeLogDirsResult @@ -415,7 +420,7 @@ public DescribeLogDirsResult describeLogDirs(Collection brokers) { /** * Query the information of all log directories on the given set of brokers * - * This operation is supported by brokers with version 1.0 or higher. + * This operation is supported by brokers with version 1.0.0 or higher. * * @param brokers A list of brokers * @param options The options to use when querying log dir info @@ -426,10 +431,10 @@ public DescribeLogDirsResult describeLogDirs(Collection brokers) { /** * Query the replica log directory information for the specified replicas. * - * Similar to #{@link AdminClient#describeReplicaLogDir(Collection, DescribeReplicaLogDirOptions)}, - * but uses the default options. + * 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 or higher. + * This operation is supported by brokers with version 1.0.0 or higher. * * @param replicas The replicas to query * @return The DescribeReplicaLogDirResult @@ -441,7 +446,7 @@ public DescribeReplicaLogDirResult describeReplicaLogDir(Collection    Notable changes in 1 to retain the previous behavior should set the broker config delete.topic.enable to false. Keep in mind that topic deletion removes data and the operation is not reversible (i.e. there is no "undelete" operation)
  • 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. -
  • If the inter.broker.protocol.version is 0.11.1 or later, a broker will now stay online to serve replicas +
  • If the inter.broker.protocol.version 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 offlineLogDirectoryCount to check whether there is offline log directory.