kowshik commented on a change in pull request #9001:
URL: https://github.com/apache/kafka/pull/9001#discussion_r494180305
##########
File path: clients/src/main/java/org/apache/kafka/clients/admin/Admin.java
##########
@@ -1214,6 +1216,71 @@ default AlterClientQuotasResult
alterClientQuotas(Collection<ClientQuotaAlterati
*/
AlterClientQuotasResult
alterClientQuotas(Collection<ClientQuotaAlteration> entries,
AlterClientQuotasOptions options);
+ /**
+ * Describes finalized as well as supported features. By default, the
request is issued to any
+ * broker. It can be optionally directed only to the controller via
DescribeFeaturesOptions
+ * parameter. This is particularly useful if the user requires strongly
consistent reads of
+ * finalized features.
+ * <p>
+ * The following exceptions can be anticipated when calling {@code get()}
on the future from the
+ * returned {@link DescribeFeaturesResult}:
+ * <ul>
+ * <li>{@link org.apache.kafka.common.errors.TimeoutException}
+ * If the request timed out before the describe operation could
finish.</li>
+ * </ul>
+ * <p>
+ * @param options the options to use
+ *
+ * @return the {@link DescribeFeaturesResult} containing the
result
+ */
+ DescribeFeaturesResult describeFeatures(DescribeFeaturesOptions options);
+
+ /**
+ * Applies specified updates to finalized features. This operation is not
transactional so it
+ * may succeed for some features while fail for others.
+ * <p>
+ * The API takes in a map of finalized feature names to {@link
FeatureUpdate} that needs to be
+ * applied. Each entry in the map specifies the finalized feature to be
added or updated or
+ * deleted, along with the new max feature version level value. This
request is issued only to
+ * the controller since the API is only served by the controller. The
return value contains an
+ * error code for each supplied {@link FeatureUpdate}, and the code
indicates if the update
+ * succeeded or failed in the controller.
+ * <ul>
+ * <li>Downgrade of feature version level is not a regular
operation/intent. It is only allowed
+ * in the controller if the {@link FeatureUpdate} has the allowDowngrade
flag set - setting this
+ * flag conveys user intent to attempt downgrade of a feature max version
level. Note that
+ * despite the allowDowngrade flag being set, certain downgrades may be
rejected by the
+ * controller if it is deemed impossible.</li>
+ * <li>Deletion of a finalized feature version is not a regular
operation/intent. It could be
+ * done by setting the allowDowngrade flag to true in the {@link
FeatureUpdate}, and, setting
+ * the max version level to be less than 1.</li>
+ * </ul>
+ *<p>
+ * The following exceptions can be anticipated when calling {@code get()}
on the futures
+ * obtained from the returned {@link UpdateFeaturesResult}:
+ * <ul>
+ * <li>{@link
org.apache.kafka.common.errors.ClusterAuthorizationException}
+ * If the authenticated user didn't have alter access to the
cluster.</li>
+ * <li>{@link org.apache.kafka.common.errors.InvalidRequestException}
+ * If the request details are invalid. e.g., a non-existing finalized
feature is attempted
+ * to be deleted or downgraded.</li>
+ * <li>{@link org.apache.kafka.common.errors.TimeoutException}
+ * If the request timed out before the updates could finish. It cannot
be guaranteed whether
+ * the updates succeeded or not.</li>
+ * <li>{@link FeatureUpdateFailedException}
+ * If the updates could not be applied on the controller, despite the
request being valid.
+ * This may be a temporary problem.</li>
+ * </ul>
+ * <p>
+ * This operation is supported by brokers with version 2.7.0 or higher.
+
+ * @param featureUpdates the map of finalized feature name to {@link
FeatureUpdate}
+ * @param options the options to use
+ *
+ * @return the {@link UpdateFeaturesResult} containing the
result
+ */
+ UpdateFeaturesResult updateFeatures(Map<String, FeatureUpdate>
featureUpdates, UpdateFeaturesOptions options);
Review comment:
Done. I've updated the KIP to align with whats used here.
##########
File path: clients/src/main/java/org/apache/kafka/clients/admin/Admin.java
##########
@@ -1214,6 +1216,71 @@ default AlterClientQuotasResult
alterClientQuotas(Collection<ClientQuotaAlterati
*/
AlterClientQuotasResult
alterClientQuotas(Collection<ClientQuotaAlteration> entries,
AlterClientQuotasOptions options);
+ /**
+ * Describes finalized as well as supported features. By default, the
request is issued to any
+ * broker. It can be optionally directed only to the controller via
DescribeFeaturesOptions
+ * parameter. This is particularly useful if the user requires strongly
consistent reads of
+ * finalized features.
+ * <p>
+ * The following exceptions can be anticipated when calling {@code get()}
on the future from the
+ * returned {@link DescribeFeaturesResult}:
+ * <ul>
+ * <li>{@link org.apache.kafka.common.errors.TimeoutException}
+ * If the request timed out before the describe operation could
finish.</li>
+ * </ul>
+ * <p>
+ * @param options the options to use
+ *
+ * @return the {@link DescribeFeaturesResult} containing the
result
+ */
+ DescribeFeaturesResult describeFeatures(DescribeFeaturesOptions options);
+
+ /**
+ * Applies specified updates to finalized features. This operation is not
transactional so it
+ * may succeed for some features while fail for others.
+ * <p>
+ * The API takes in a map of finalized feature names to {@link
FeatureUpdate} that needs to be
+ * applied. Each entry in the map specifies the finalized feature to be
added or updated or
+ * deleted, along with the new max feature version level value. This
request is issued only to
+ * the controller since the API is only served by the controller. The
return value contains an
+ * error code for each supplied {@link FeatureUpdate}, and the code
indicates if the update
+ * succeeded or failed in the controller.
+ * <ul>
+ * <li>Downgrade of feature version level is not a regular
operation/intent. It is only allowed
+ * in the controller if the {@link FeatureUpdate} has the allowDowngrade
flag set - setting this
+ * flag conveys user intent to attempt downgrade of a feature max version
level. Note that
+ * despite the allowDowngrade flag being set, certain downgrades may be
rejected by the
+ * controller if it is deemed impossible.</li>
+ * <li>Deletion of a finalized feature version is not a regular
operation/intent. It could be
+ * done by setting the allowDowngrade flag to true in the {@link
FeatureUpdate}, and, setting
+ * the max version level to be less than 1.</li>
+ * </ul>
+ *<p>
+ * The following exceptions can be anticipated when calling {@code get()}
on the futures
+ * obtained from the returned {@link UpdateFeaturesResult}:
+ * <ul>
+ * <li>{@link
org.apache.kafka.common.errors.ClusterAuthorizationException}
+ * If the authenticated user didn't have alter access to the
cluster.</li>
+ * <li>{@link org.apache.kafka.common.errors.InvalidRequestException}
+ * If the request details are invalid. e.g., a non-existing finalized
feature is attempted
+ * to be deleted or downgraded.</li>
+ * <li>{@link org.apache.kafka.common.errors.TimeoutException}
+ * If the request timed out before the updates could finish. It cannot
be guaranteed whether
+ * the updates succeeded or not.</li>
+ * <li>{@link FeatureUpdateFailedException}
+ * If the updates could not be applied on the controller, despite the
request being valid.
+ * This may be a temporary problem.</li>
+ * </ul>
+ * <p>
+ * This operation is supported by brokers with version 2.7.0 or higher.
+
+ * @param featureUpdates the map of finalized feature name to {@link
FeatureUpdate}
+ * @param options the options to use
+ *
+ * @return the {@link UpdateFeaturesResult} containing the
result
+ */
+ UpdateFeaturesResult updateFeatures(Map<String, FeatureUpdate>
featureUpdates, UpdateFeaturesOptions options);
Review comment:
Done. I've updated the KIP to align with whats used here, so both are
the same now.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
