Classify surviving deprecated APIs in storm-server, external modules, and utilities (#8994)

external/storm-hdfs/src/main/java/org/apache/storm/hdfs/spout/Configs.java

@@ -27,7 +27,7 @@ public class Configs implements Validated {
      * Required - chose the file type being consumed.
      * @deprecated please use {@link HdfsSpout#setReaderType(String)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsString
     @CustomValidator(validatorClass = ReaderTypeValidator.class)
     public static final String READER_TYPE = "hdfsspout.reader.type";
@@ -37,66 +37,66 @@ public class Configs implements Validated {
      * Required - HDFS name node.
      * @deprecated please use {@link HdfsSpout#setHdfsUri(String)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsString
     public static final String HDFS_URI = "hdfsspout.hdfs";
     /**
      * Required - dir from which to read files.
      * @deprecated please use {@link HdfsSpout#setSourceDir(String)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsString
     public static final String SOURCE_DIR = "hdfsspout.source.dir";
     /**
      * Required - completed files will be moved here.
      * @deprecated please use {@link HdfsSpout#setArchiveDir(String)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsString
     public static final String ARCHIVE_DIR = "hdfsspout.archive.dir";
     /**
      * Required - unparsable files will be moved here.
      * @deprecated please use {@link HdfsSpout#setBadFilesDir(String)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsString
     public static final String BAD_DIR = "hdfsspout.badfiles.dir";
     /**
      * Directory in which lock files will be created.
      * @deprecated please use {@link HdfsSpout#setLockDir(String)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsString
     public static final String LOCK_DIR = "hdfsspout.lock.dir";
     /**
      * Commit after N records. 0 disables this.
      * @deprecated please use {@link HdfsSpout#setCommitFrequencyCount(int)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsInteger
     @IsPositiveNumber(includeZero = true)
     public static final String COMMIT_FREQ_COUNT = "hdfsspout.commit.count";
     /**
      * Commit after N secs. cannot be disabled.
      * @deprecated please use {@link HdfsSpout#setCommitFrequencySec(int)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsInteger
     @IsPositiveNumber
     public static final String COMMIT_FREQ_SEC = "hdfsspout.commit.sec";
     /**
      * Max outstanding.
      * @deprecated please use {@link HdfsSpout#setMaxOutstanding(int)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsInteger
     @IsPositiveNumber(includeZero = true)
     public static final String MAX_OUTSTANDING = "hdfsspout.max.outstanding";
     /**
      * Lock timeout.
      * @deprecated please use {@link HdfsSpout#setLockTimeoutSec(int)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsInteger
     @IsPositiveNumber
     public static final String LOCK_TIMEOUT = "hdfsspout.lock.timeout.sec";
@@ -106,14 +106,14 @@ public class Configs implements Validated {
      *
      * @deprecated please use {@link HdfsSpout#setClocksInSync(boolean)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsBoolean
     public static final String CLOCKS_INSYNC = "hdfsspout.clocks.insync";
     /**
      * Ignore suffix.
      * @deprecated please use {@link HdfsSpout#setIgnoreSuffix(String)}
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     @IsString
     public static final String IGNORE_SUFFIX = "hdfsspout.ignore.suffix";
     /**

external/storm-hdfs/src/main/java/org/apache/storm/hdfs/trident/HdfsState.java

@@ -346,7 +346,14 @@ public HdfsFileOptions withBufferSize(int sizeInBytes) {
             return this;
         }
 
-        @Deprecated
+        /**
+         * Adds a rotation action.
+         *
+         * @param action the rotation action to add
+         * @return {@link HdfsFileOptions}
+         * @deprecated This method is marked for removal.
+         */
+        @Deprecated(since = "2.0.0", forRemoval = true)
         public HdfsFileOptions addRotationAction(RotationAction action) {
             this.rotationActions.add(action);
             return this;

flux/flux-core/src/main/java/org/apache/storm/flux/Flux.java

@@ -53,18 +53,18 @@
 public class Flux {
     private static final Logger LOG = LoggerFactory.getLogger(Flux.class);
 
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     private static final String OPTION_LOCAL = "local";
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     private static final String OPTION_REMOTE = "remote";
     private static final String OPTION_RESOURCE = "resource";
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     private static final String OPTION_SLEEP = "sleep";
     private static final String OPTION_DRY_RUN = "dry-run";
     private static final String OPTION_NO_DETAIL = "no-detail";
     private static final String OPTION_NO_SPLASH = "no-splash";
     private static final String OPTION_INACTIVE = "inactive";
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     private static final String OPTION_ZOOKEEPER = "zookeeper";
     private static final String OPTION_FILTER = "filter";
     private static final String OPTION_ENV_FILTER = "env-filter";

storm-client/src/jvm/org/apache/storm/drpc/LinearDRPCTopologyBuilder.java

@@ -63,7 +63,15 @@ public LinearDRPCInputDeclarer addBolt(IBatchBolt bolt) {
         return addBolt(bolt, 1);
     }
 
-    @Deprecated
+    /**
+     * Adds a bolt to the topology.
+     *
+     * @param bolt the rich bolt to add
+     * @param parallelism parallelism hint
+     * @return input declarer
+     * @deprecated please use {@link #addBolt(IBatchBolt, Number)} or {@link #addBolt(IBasicBolt, Number)} instead.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public LinearDRPCInputDeclarer addBolt(IRichBolt bolt, Number parallelism) {
         if (parallelism == null) {
             parallelism = 1;
@@ -73,7 +81,14 @@ public LinearDRPCInputDeclarer addBolt(IRichBolt bolt, Number parallelism) {
         return new InputDeclarerImpl(component);
     }
 
-    @Deprecated
+    /**
+     * Adds a bolt to the topology.
+     *
+     * @param bolt the rich bolt to add
+     * @return input declarer
+     * @deprecated please use {@link #addBolt(IBatchBolt)} or {@link #addBolt(IBasicBolt)} instead.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public LinearDRPCInputDeclarer addBolt(IRichBolt bolt) {
         return addBolt(bolt, null);
     }

storm-client/src/jvm/org/apache/storm/metrics2/StormMetricRegistry.java

@@ -93,7 +93,21 @@ public <T> Gauge<T> gauge(String name, Gauge<T> gauge, TopologyContext context)
         return gauge;
     }
 
-    @Deprecated
+    /**
+     * Registers a gauge metric.
+     *
+     * @param <T> the value type
+     * @param name metric name
+     * @param gauge gauge instance
+     * @param topologyId topology id
+     * @param componentId component id
+     * @param taskId task id
+     * @param port worker port
+     * @return registered gauge
+     * @deprecated please use {@link #gauge(String, Gauge, String, Integer)} or
+     *     {@link #gauge(String, Gauge, TopologyContext)} instead.
+     */
+    @Deprecated(since = "2.3.0", forRemoval = true)
     public <T> Gauge<T> gauge(String name, Gauge<T> gauge, String topologyId, String componentId, Integer taskId, Integer port) {
         MetricNames metricNames = workerMetricName(name, topologyId, componentId, taskId, port);
         gauge = registerGauge(metricNames, gauge, taskId, componentId, null);

storm-client/src/jvm/org/apache/storm/metrics2/reporters/StormReporter.java

@@ -23,7 +23,15 @@ public interface StormReporter extends Reporter {
     String REPORT_PERIOD_UNITS = "report.period.units";
     String REPORT_DIMENSIONS_ENABLED = "report.dimensions.enabled";
 
-    @Deprecated
+    /**
+     * Prepares the reporter with a metric registry.
+     *
+     * @param metricsRegistry metric registry
+     * @param topoConf topology configuration
+     * @param reporterConf reporter configuration
+     * @deprecated please use {@link #prepare(MetricRegistryProvider, Map, Map)} instead.
+     */
+    @Deprecated(since = "2.3.0", forRemoval = true)
     void prepare(MetricRegistry metricsRegistry, Map<String, Object> topoConf, Map<String, Object> reporterConf);
 
     default void prepare(MetricRegistryProvider metricRegistryProvider, Map<String, Object> topoConf,

storm-client/src/jvm/org/apache/storm/security/auth/plain/PlainClientCallbackHandler.java

@@ -17,8 +17,9 @@
 /**
  * This should only ever be used for testing.  It provides no security at all. DO NOT USE THIS.  The user name is the current user and the
  * password is "password".
+ * @deprecated This should only ever be used for testing as it provides no security.
  */
-@Deprecated
+@Deprecated(since = "2.0.0", forRemoval = true)
 public class PlainClientCallbackHandler extends SimpleSaslClientCallbackHandler {
 
     /**

storm-client/src/jvm/org/apache/storm/security/auth/plain/PlainSaslTransportPlugin.java

@@ -30,8 +30,9 @@
 /**
  * This should never be used except for testing.  It provides no security at all. The password is hard coded, and even if it were not it is
  * sent in plain text.
+ * @deprecated This should never be used except for testing as it provides no security.
  */
-@Deprecated
+@Deprecated(since = "2.0.0", forRemoval = true)
 public class PlainSaslTransportPlugin extends SaslTransportPlugin {
     public static final String PLAIN = "PLAIN";
     private static final Logger LOG = LoggerFactory.getLogger(PlainSaslTransportPlugin.class);

storm-client/src/jvm/org/apache/storm/security/auth/plain/SaslPlainServer.java

@@ -24,7 +24,11 @@
 import javax.security.sasl.SaslServer;
 import javax.security.sasl.SaslServerFactory;
 
-@Deprecated
+/**
+ * Plain SASL server implementation for testing.
+ * @deprecated This should never be used except for testing as it provides no security.
+ */
+@Deprecated(since = "2.0.0", forRemoval = true)
 public class SaslPlainServer implements SaslServer {
     private CallbackHandler cbh;
     private boolean completed;

storm-server/src/main/java/org/apache/storm/Testing.java

@@ -129,7 +129,7 @@ public static <T> boolean isEvery(Collection<T> data, Predicate<T> pred) {
      *     ```
      * @param code what to run
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static void withSimulatedTime(Runnable code) {
         try (SimulatedTime st = new SimulatedTime()) {
             code.run();
@@ -177,7 +177,7 @@ private static LocalCluster cluster(MkClusterParam param, String id, boolean sim
      *     ```
      * @param code what to run
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static void withLocalCluster(TestJob code) {
         withLocalCluster(new MkClusterParam(), code);
     }
@@ -193,7 +193,7 @@ public static void withLocalCluster(TestJob code) {
      * @param param configs to set in the cluster
      * @param code what to run
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static void withLocalCluster(MkClusterParam param, TestJob code) {
         try (LocalCluster lc = cluster(param)) {
             code.run(lc);
@@ -212,7 +212,7 @@ public static void withLocalCluster(MkClusterParam param, TestJob code) {
      *     ```
      * @param clusterConf some configs to set in the cluster
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static ILocalCluster getLocalCluster(Map<String, Object> clusterConf) {
         @SuppressWarnings("unchecked")
         Map<String, Object> conf = (Map<String, Object>) clusterConf.get("daemon-conf");
@@ -248,7 +248,7 @@ public static ILocalCluster getLocalCluster(Map<String, Object> clusterConf) {
      *     ```
      * @param code what to run
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static void withSimulatedTimeLocalCluster(TestJob code) {
         withSimulatedTimeLocalCluster(new MkClusterParam(), code);
     }
@@ -264,7 +264,7 @@ public static void withSimulatedTimeLocalCluster(TestJob code) {
      * @param param configs to set in the cluster
      * @param code what to run
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static void withSimulatedTimeLocalCluster(MkClusterParam param, TestJob code) {
         try (LocalCluster lc = cluster(param, true)) {
             code.run(lc);
@@ -283,7 +283,7 @@ public static void withSimulatedTimeLocalCluster(MkClusterParam param, TestJob c
      *     ```
      * @param code what to run
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static void withTrackedCluster(TestJob code) {
         withTrackedCluster(new MkClusterParam(), code);
     }
@@ -299,7 +299,7 @@ public static void withTrackedCluster(TestJob code) {
      * @param param configs to set in the cluster
      * @param code what to run
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static void withTrackedCluster(MkClusterParam param, TestJob code) {
         try (LocalCluster lc = cluster(param, Utils.uuid(), true)) {
             code.run(lc);
@@ -315,9 +315,10 @@ public static void withTrackedCluster(MkClusterParam param, TestJob code) {
      * @param id the id of the tracked cluster
      * @param key the name of the metric to get.
      * @return the metric
+     * @deprecated internal test utility; use {@link org.apache.storm.testing.TrackedTopology} instead.
      */
     @SuppressWarnings("unchecked")
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static int globalAmt(String id, String key) {
         LOG.warn("Reading tracked metrics for ID {}", id);
         return ((ConcurrentHashMap<String, AtomicInteger>) RegisteredGlobalState.getState(id)).get(key).get();
@@ -523,7 +524,7 @@ public static List<List<Object>> readTuples(Map<String, List<FixedTuple>> result
      * Create a tracked topology.
      * @deprecated use {@link org.apache.storm.testing.TrackedTopology} directly.
      */
-    @Deprecated
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public static TrackedTopology mkTrackedTopology(ILocalCluster cluster, StormTopology topology) {
         return new TrackedTopology(topology, cluster);
     }

storm-server/src/main/java/org/apache/storm/scheduler/SchedulerAssignmentImpl.java

@@ -138,7 +138,12 @@ public Set<WorkerSlot> getSlots() {
         return new HashSet<>(executorToSlot.values());
     }
 
-    @Deprecated
+    /**
+     * Assign the slot to executors without worker resources.
+     *
+     * @deprecated use {@link #assign(WorkerSlot, Collection, WorkerResources)} instead.
+     */
+    @Deprecated(since = "2.0.0", forRemoval = true)
     public void assign(WorkerSlot slot, Collection<ExecutorDetails> executors) {
         assign(slot, executors, null);
     }

storm-server/src/main/java/org/apache/storm/scheduler/resource/strategies/scheduling/BaseResourceAwareStrategy.java

@@ -61,16 +61,16 @@ public abstract class BaseResourceAwareStrategy implements IStrategy {
     public enum NodeSortType {
         /**
          * Generic Resource Aware Strategy sorting type.
-         * @deprecated used by GenericResourceAwareStrategyOld only. Use {link #COMMON} instead.
+         * @deprecated used by GenericResourceAwareStrategyOld only. Use {@link #COMMON} instead.
          */
-        @Deprecated
+        @Deprecated(since = "2.3.0", forRemoval = true)
         GENERIC_RAS,
 
         /**
          * Default Resource Aware Strategy sorting type.
-         * @deprecated used by DefaultResourceAwareStrategyOld only. Use {link #COMMON} instead.
+         * @deprecated used by DefaultResourceAwareStrategyOld only. Use {@link #COMMON} instead.
          */
-        @Deprecated
+        @Deprecated(since = "2.3.0", forRemoval = true)
         DEFAULT_RAS,
 
         /**

storm-server/src/main/java/org/apache/storm/scheduler/resource/strategies/scheduling/sorter/NodeSorter.java

@@ -250,8 +250,9 @@ private List<ObjectResourcesItem> sortObjectResourcesCommon(
      * @param exec                 executor for which the sorting is done
      * @param existingScheduleFunc a function to get existing executors already scheduled on this object
      * @return a sorted list of ObjectResources
+     * @deprecated used by GenericResourceAwareStrategyOld only; use COMMON node sorting instead.
      */
-    @Deprecated
+    @Deprecated(since = "2.3.0", forRemoval = true)
     private List<ObjectResourcesItem> sortObjectResourcesGeneric(
             final ObjectResourcesSummary allResources, ExecutorDetails exec,
             final ExistingScheduleFunc existingScheduleFunc) {
@@ -302,8 +303,9 @@ private List<ObjectResourcesItem> sortObjectResourcesGeneric(
      * @param allResources         contains all individual ObjectResources as well as cumulative stats
      * @param existingScheduleFunc a function to get existing executors already scheduled on this object
      * @return a sorted list of ObjectResources
+     * @deprecated used by DefaultResourceAwareStrategyOld only; use COMMON node sorting instead.
      */
-    @Deprecated
+    @Deprecated(since = "2.3.0", forRemoval = true)
     private List<ObjectResourcesItem> sortObjectResourcesDefault(
             final ObjectResourcesSummary allResources,
             final ExistingScheduleFunc existingScheduleFunc) {