KAFKA-18290 Remove deprecated methods of FeatureUpdate (apache#18246)

Reviewers: Chia-Ping Tsai <[email protected]>

Author: LoganZhuZzz

clients/src/main/java/org/apache/kafka/clients/admin/Admin.java

@@ -1443,14 +1443,23 @@ default DescribeFeaturesResult describeFeatures() {
      * 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 a value less than 1.</li>
+     * <li>Downgrading a feature version level is not a common operation and should only be
+     * performed when necessary. It is permitted only if the {@link FeatureUpdate} specifies the
+     * {@code upgradeType} as either {@link FeatureUpdate.UpgradeType#SAFE_DOWNGRADE} or
+     * {@link FeatureUpdate.UpgradeType#UNSAFE_DOWNGRADE}.
+     * <ul>
+     * <li>{@code SAFE_DOWNGRADE}: Allows downgrades that do not lead to metadata loss.</li>
+     * <li>{@code UNSAFE_DOWNGRADE}: Permits downgrades that might result in metadata loss.</li>
+     * </ul>
+     * Note that even with these settings, certain downgrades may still be rejected by the controller
+     * if they are considered unsafe or impossible.</li>
+     * <li>Deleting a finalized feature version is also not a common operation. To delete a feature,
+     * set the {@code maxVersionLevel} to zero and specify the {@code upgradeType} as either
+     * {@link FeatureUpdate.UpgradeType#SAFE_DOWNGRADE} or
+     * {@link FeatureUpdate.UpgradeType#UNSAFE_DOWNGRADE}.</li>
+     * <li>The {@link FeatureUpdate.UpgradeType#UPGRADE} type cannot be used when the
+     * {@code maxVersionLevel} is zero. Attempting to do so will result in an
+     * {@link IllegalArgumentException}.</li>
      * </ul>
      * <p>
      * The following exceptions can be anticipated when calling {@code get()} on the futures

clients/src/main/java/org/apache/kafka/clients/admin/FeatureUpdate.java

@@ -54,21 +54,6 @@ public static UpgradeType fromCode(int code) {
         }
     }
 
-    /**
-     * @param maxVersionLevel   the new maximum version level for the finalized feature.
-     *                          a value of zero is special and indicates that the update is intended to
-     *                          delete the finalized feature, and should be accompanied by setting
-     *                          the allowDowngrade flag to true.
-     * @param allowDowngrade    - true, if this feature update was meant to downgrade the existing
-     *                            maximum version level of the finalized feature. Only "safe" downgrades are
-     *                            enabled with this boolean. See {@link FeatureUpdate#FeatureUpdate(short, UpgradeType)}
-     *                          - false, otherwise.
-     */
-    @Deprecated
-    public FeatureUpdate(final short maxVersionLevel, final boolean allowDowngrade) {
-        this(maxVersionLevel, allowDowngrade ? UpgradeType.SAFE_DOWNGRADE : UpgradeType.UPGRADE);
-    }
-
     /**
      * @param maxVersionLevel   The new maximum version level for the finalized feature.
      *                          a value of zero is special and indicates that the update is intended to
@@ -96,11 +81,6 @@ public short maxVersionLevel() {
         return maxVersionLevel;
     }
 
-    @Deprecated
-    public boolean allowDowngrade() {
-        return upgradeType != UpgradeType.UPGRADE;
-    }
-
     public UpgradeType upgradeType() {
         return upgradeType;
     }

docs/upgrade.html

@@ -221,6 +221,12 @@ <h5><a id="upgrade_400_notable" href="#upgrade_400_notable">Notable changes in 4
                             The deprecated <code>dryRun</code> methods were removed from the <code>org.apache.kafka.clients.admin.UpdateFeaturesOptions</code>.
                             Please use <code>validateOnly</code> instead.
                         </li>
+                        <li>The constructor <code>org.apache.kafka.clients.admin.FeatureUpdate</code> with short and boolean arguments was removed.
+                            Please use the constructor that accepts short and the specified UpgradeType enum instead.
+                        </li>
+                        <li>
+                            The <code>allowDowngrade</code> method was removed from the <code>org.apache.kafka.clients.admin.FeatureUpdate</code>.
+                        </li>
                         <li>The <code>org.apache.kafka.clients.admin.DescribeTopicsResult.DescribeTopicsResult(Map&lt;String, KafkaFuture&lt;TopicDescription&gt;&gt;)</code> method was removed.
                             Please use <code>org.apache.kafka.clients.admin.DescribeTopicsResult.DescribeTopicsResult(Map&lt;Uuid, KafkaFuture&lt;TopicDescription&gt;&gt;, Map&lt;String, KafkaFuture&lt;TopicDescription&gt;&gt;)</code> instead.
                         </li>