From 738bd928f1d3cda974a177953410766ad93d5446 Mon Sep 17 00:00:00 2001 From: "Matthias J. Sax" Date: Tue, 7 Jan 2025 01:18:33 -0800 Subject: [PATCH] MINOR: cleanup JavaDocs for deprecation warnings (#18402) Reviewers: Bill Bejeck , Chia-Ping Tsai --- .../clients/admin/ConsumerGroupDescription.java | 6 +++--- .../clients/admin/ConsumerGroupListing.java | 6 +++--- .../admin/CreateDelegationTokenOptions.java | 4 ++-- .../clients/admin/ListConsumerGroupsOptions.java | 4 ++-- .../kafka/clients/admin/MemberDescription.java | 6 +++--- .../kafka/clients/consumer/ConsumerRecords.java | 3 +++ .../kafka/clients/consumer/MockConsumer.java | 2 +- .../clients/consumer/OffsetResetStrategy.java | 2 +- .../errors/RecordDeserializationException.java | 3 +++ .../org/apache/kafka/streams/StreamsConfig.java | 16 ++++++++++------ .../DefaultProductionExceptionHandler.java | 3 +++ .../errors/LogAndContinueExceptionHandler.java | 3 +++ .../errors/LogAndFailExceptionHandler.java | 3 +++ .../kafka/streams/kstream/ForeachProcessor.java | 2 +- .../kafka/streams/kstream/JoinWindows.java | 4 ++-- .../org/apache/kafka/streams/kstream/Joined.java | 8 ++++---- .../org/apache/kafka/tools/TopicCommand.java | 2 +- 17 files changed, 48 insertions(+), 29 deletions(-) diff --git a/clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupDescription.java b/clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupDescription.java index ed4eb2fa949..b2c44d4fbeb 100644 --- a/clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupDescription.java +++ b/clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupDescription.java @@ -47,7 +47,7 @@ public class ConsumerGroupDescription { private final Optional targetAssignmentEpoch; /** - * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)}. + * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)} instead. */ @Deprecated public ConsumerGroupDescription(String groupId, @@ -60,7 +60,7 @@ public class ConsumerGroupDescription { } /** - * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)}. + * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)} instead. */ @Deprecated public ConsumerGroupDescription(String groupId, @@ -74,7 +74,7 @@ public class ConsumerGroupDescription { } /** - * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)}. + * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)} instead. */ @Deprecated public ConsumerGroupDescription(String groupId, diff --git a/clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupListing.java b/clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupListing.java index 7081811a239..34b9f08f10e 100644 --- a/clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupListing.java +++ b/clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupListing.java @@ -49,7 +49,7 @@ public class ConsumerGroupListing { * @param groupId Group Id. * @param isSimpleConsumerGroup If consumer group is simple or not. * @param state The state of the consumer group. - * @deprecated Since 4.0. Use {@link #ConsumerGroupListing(String, Optional, boolean)}. + * @deprecated Since 4.0. Use {@link #ConsumerGroupListing(String, Optional, boolean)} instead. */ @Deprecated public ConsumerGroupListing(String groupId, boolean isSimpleConsumerGroup, Optional state) { @@ -63,7 +63,7 @@ public class ConsumerGroupListing { * @param isSimpleConsumerGroup If consumer group is simple or not. * @param state The state of the consumer group. * @param type The type of the consumer group. - * @deprecated Since 4.0. Use {@link #ConsumerGroupListing(String, Optional, Optional, boolean)}. + * @deprecated Since 4.0. Use {@link #ConsumerGroupListing(String, Optional, Optional, boolean)} instead. */ @Deprecated public ConsumerGroupListing( @@ -133,7 +133,7 @@ public class ConsumerGroupListing { /** * Consumer Group state - * @deprecated Since 4.0. Use {@link #groupState()}. + * @deprecated Since 4.0. Use {@link #groupState()} instead. */ @Deprecated public Optional state() { diff --git a/clients/src/main/java/org/apache/kafka/clients/admin/CreateDelegationTokenOptions.java b/clients/src/main/java/org/apache/kafka/clients/admin/CreateDelegationTokenOptions.java index c3899b5bd1e..8e5c24aa6fc 100644 --- a/clients/src/main/java/org/apache/kafka/clients/admin/CreateDelegationTokenOptions.java +++ b/clients/src/main/java/org/apache/kafka/clients/admin/CreateDelegationTokenOptions.java @@ -54,7 +54,7 @@ public class CreateDelegationTokenOptions extends AbstractOptions states) { @@ -80,7 +80,7 @@ public class ListConsumerGroupsOptions extends AbstractOptions states() { diff --git a/clients/src/main/java/org/apache/kafka/clients/admin/MemberDescription.java b/clients/src/main/java/org/apache/kafka/clients/admin/MemberDescription.java index 0785f2e6715..e72a48d8a62 100644 --- a/clients/src/main/java/org/apache/kafka/clients/admin/MemberDescription.java +++ b/clients/src/main/java/org/apache/kafka/clients/admin/MemberDescription.java @@ -57,7 +57,7 @@ public class MemberDescription { } /** - * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)}. + * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)} instead. */ @Deprecated public MemberDescription( @@ -81,7 +81,7 @@ public class MemberDescription { } /** - * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)}. + * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)} instead. */ @Deprecated public MemberDescription( @@ -102,7 +102,7 @@ public class MemberDescription { } /** - * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)}. + * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)} instead. */ @Deprecated public MemberDescription(String memberId, diff --git a/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecords.java b/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecords.java index 535313b1f2f..0cb3b8f9677 100644 --- a/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecords.java +++ b/clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecords.java @@ -37,6 +37,9 @@ public class ConsumerRecords implements Iterable> { private final Map>> records; private final Map nextOffsets; + /** + * @deprecated Since 4.0. Use {@link #ConsumerRecords(Map, Map)} instead. + */ @Deprecated public ConsumerRecords(Map>> records) { this(records, Map.of()); diff --git a/clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java b/clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java index 9ee66e4f320..b9e69806694 100644 --- a/clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java +++ b/clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java @@ -82,7 +82,7 @@ public class MockConsumer implements Consumer { private final List addedMetrics = new ArrayList<>(); /** - * @deprecated Since 4.0. Use {@link #MockConsumer(String)}. + * @deprecated Since 4.0. Use {@link #MockConsumer(String)} instead. */ @Deprecated public MockConsumer(OffsetResetStrategy offsetResetStrategy) { diff --git a/clients/src/main/java/org/apache/kafka/clients/consumer/OffsetResetStrategy.java b/clients/src/main/java/org/apache/kafka/clients/consumer/OffsetResetStrategy.java index 8c84863f60f..42a9c268de8 100644 --- a/clients/src/main/java/org/apache/kafka/clients/consumer/OffsetResetStrategy.java +++ b/clients/src/main/java/org/apache/kafka/clients/consumer/OffsetResetStrategy.java @@ -19,7 +19,7 @@ package org.apache.kafka.clients.consumer; import java.util.Locale; /** - * @deprecated Since 4.0. Use {@link org.apache.kafka.clients.consumer.internals.AutoOffsetResetStrategy instead.} + * @deprecated Since 4.0. Use {@link org.apache.kafka.clients.consumer.internals.AutoOffsetResetStrategy} instead. */ @Deprecated public enum OffsetResetStrategy { diff --git a/clients/src/main/java/org/apache/kafka/common/errors/RecordDeserializationException.java b/clients/src/main/java/org/apache/kafka/common/errors/RecordDeserializationException.java index aee57c47d28..6ed441d444b 100644 --- a/clients/src/main/java/org/apache/kafka/common/errors/RecordDeserializationException.java +++ b/clients/src/main/java/org/apache/kafka/common/errors/RecordDeserializationException.java @@ -45,6 +45,9 @@ public class RecordDeserializationException extends SerializationException { private final ByteBuffer valueBuffer; private final Headers headers; + /** + * @deprecated Since 3.9. Use {@link #RecordDeserializationException(DeserializationExceptionOrigin, TopicPartition, long, long, TimestampType, ByteBuffer, ByteBuffer, Headers, String, Throwable)} instead. + */ @Deprecated public RecordDeserializationException(TopicPartition partition, long offset, diff --git a/streams/src/main/java/org/apache/kafka/streams/StreamsConfig.java b/streams/src/main/java/org/apache/kafka/streams/StreamsConfig.java index e1180a320c1..1801eeab0a0 100644 --- a/streams/src/main/java/org/apache/kafka/streams/StreamsConfig.java +++ b/streams/src/main/java/org/apache/kafka/streams/StreamsConfig.java @@ -165,6 +165,7 @@ public class StreamsConfig extends AbstractConfig { @Deprecated @SuppressWarnings("unused") public static final int DUMMY_THREAD_INDEX = 1; + public static final long MAX_TASK_IDLE_MS_DISABLED = -1; // We impose these limitations because client tags are encoded into the subscription info, @@ -486,7 +487,7 @@ public class StreamsConfig extends AbstractConfig { private static final String BUILT_IN_METRICS_VERSION_DOC = "Version of the built-in metrics to use."; /** {@code cache.max.bytes.buffering} - * @deprecated since 3.4.0 Use {@link #STATESTORE_CACHE_MAX_BYTES_CONFIG "statestore.cache.max.bytes"} instead. */ + * @deprecated Since 3.4. Use {@link #STATESTORE_CACHE_MAX_BYTES_CONFIG "statestore.cache.max.bytes"} instead. */ @SuppressWarnings("WeakerAccess") @Deprecated public static final String CACHE_MAX_BYTES_BUFFERING_CONFIG = "cache.max.bytes.buffering"; @@ -520,7 +521,7 @@ public class StreamsConfig extends AbstractConfig { /** * {@code default.deserialization.exception.handler} - * @deprecated since 4.0; use {@link #DESERIALIZATION_EXCEPTION_HANDLER_CLASS_CONFIG} instead + * @deprecated Since 4.0. Use {@link #DESERIALIZATION_EXCEPTION_HANDLER_CLASS_CONFIG} instead. */ @SuppressWarnings("WeakerAccess") @Deprecated @@ -535,7 +536,7 @@ public class StreamsConfig extends AbstractConfig { /** * {@code default.production.exception.handler} - * @deprecated since 4.0; Use {@link #PRODUCTION_EXCEPTION_HANDLER_CLASS_CONFIG} instead + * @deprecated Since 4.0. Use {@link #PRODUCTION_EXCEPTION_HANDLER_CLASS_CONFIG} instead. */ @SuppressWarnings("WeakerAccess") @Deprecated @@ -546,7 +547,10 @@ public class StreamsConfig extends AbstractConfig { public static final String PRODUCTION_EXCEPTION_HANDLER_CLASS_CONFIG = "production.exception.handler"; private static final String PRODUCTION_EXCEPTION_HANDLER_CLASS_DOC = "Exception handling class that implements the org.apache.kafka.streams.errors.ProductionExceptionHandler interface."; - /** {@code default.dsl.store} */ + /** + * {@code default.dsl.store} + * @deprecated Since 3.7. Use {@link #DSL_STORE_SUPPLIERS_CLASS_CONFIG} instead. + */ @Deprecated @SuppressWarnings("WeakerAccess") public static final String DEFAULT_DSL_STORE_CONFIG = "default.dsl.store"; @@ -2021,7 +2025,7 @@ public class StreamsConfig extends AbstractConfig { } /** - * @deprecated since kafka 4.0; use {@link #deserializationExceptionHandler()} instead + * @deprecated Since 4.0. Use {@link #deserializationExceptionHandler()} instead. */ @Deprecated @SuppressWarnings("WeakerAccess") @@ -2043,7 +2047,7 @@ public class StreamsConfig extends AbstractConfig { } /** - * @deprecated since kafka 4.0; use {@link #productionExceptionHandler()} instead + * @deprecated Since 4.0. Use {@link #productionExceptionHandler()} instead. */ @Deprecated @SuppressWarnings("WeakerAccess") diff --git a/streams/src/main/java/org/apache/kafka/streams/errors/DefaultProductionExceptionHandler.java b/streams/src/main/java/org/apache/kafka/streams/errors/DefaultProductionExceptionHandler.java index 8b1562861c4..5994326770c 100644 --- a/streams/src/main/java/org/apache/kafka/streams/errors/DefaultProductionExceptionHandler.java +++ b/streams/src/main/java/org/apache/kafka/streams/errors/DefaultProductionExceptionHandler.java @@ -26,6 +26,9 @@ import java.util.Map; * happens while attempting to produce result records. */ public class DefaultProductionExceptionHandler implements ProductionExceptionHandler { + /** + * @deprecated Since 3.9. Use {@link #handle(ErrorHandlerContext, ProducerRecord, Exception)} instead. + */ @SuppressWarnings("deprecation") @Deprecated @Override diff --git a/streams/src/main/java/org/apache/kafka/streams/errors/LogAndContinueExceptionHandler.java b/streams/src/main/java/org/apache/kafka/streams/errors/LogAndContinueExceptionHandler.java index 3622da137c1..6de997be986 100644 --- a/streams/src/main/java/org/apache/kafka/streams/errors/LogAndContinueExceptionHandler.java +++ b/streams/src/main/java/org/apache/kafka/streams/errors/LogAndContinueExceptionHandler.java @@ -31,6 +31,9 @@ import java.util.Map; public class LogAndContinueExceptionHandler implements DeserializationExceptionHandler { private static final Logger log = LoggerFactory.getLogger(LogAndContinueExceptionHandler.class); + /** + * @deprecated Since 3.9. Use {@link #handle(ErrorHandlerContext, ConsumerRecord, Exception)} instead. + */ @SuppressWarnings("deprecation") @Deprecated @Override diff --git a/streams/src/main/java/org/apache/kafka/streams/errors/LogAndFailExceptionHandler.java b/streams/src/main/java/org/apache/kafka/streams/errors/LogAndFailExceptionHandler.java index aaef5ca050b..20e6b9414de 100644 --- a/streams/src/main/java/org/apache/kafka/streams/errors/LogAndFailExceptionHandler.java +++ b/streams/src/main/java/org/apache/kafka/streams/errors/LogAndFailExceptionHandler.java @@ -31,6 +31,9 @@ import java.util.Map; public class LogAndFailExceptionHandler implements DeserializationExceptionHandler { private static final Logger log = LoggerFactory.getLogger(LogAndFailExceptionHandler.class); + /** + * @deprecated Since 3.9. Use {@link #handle(ErrorHandlerContext, ConsumerRecord, Exception)} instead. + */ @SuppressWarnings("deprecation") @Deprecated @Override diff --git a/streams/src/main/java/org/apache/kafka/streams/kstream/ForeachProcessor.java b/streams/src/main/java/org/apache/kafka/streams/kstream/ForeachProcessor.java index 1555fbd7d05..da25edae651 100644 --- a/streams/src/main/java/org/apache/kafka/streams/kstream/ForeachProcessor.java +++ b/streams/src/main/java/org/apache/kafka/streams/kstream/ForeachProcessor.java @@ -20,7 +20,7 @@ import org.apache.kafka.streams.processor.api.Processor; import org.apache.kafka.streams.processor.api.Record; /** - * @deprecated since 4.0 and should not be used any longer. + * @deprecated Since 4.0 and should not be used any longer. */ @Deprecated public class ForeachProcessor implements Processor { diff --git a/streams/src/main/java/org/apache/kafka/streams/kstream/JoinWindows.java b/streams/src/main/java/org/apache/kafka/streams/kstream/JoinWindows.java index f26aee5a4a4..4690ffdfe7c 100644 --- a/streams/src/main/java/org/apache/kafka/streams/kstream/JoinWindows.java +++ b/streams/src/main/java/org/apache/kafka/streams/kstream/JoinWindows.java @@ -154,7 +154,7 @@ public class JoinWindows extends Windows { * @param timeDifference join window interval * @return a new JoinWindows object with the window definition with and grace period (default to 24 hours minus {@code timeDifference}) * @throws IllegalArgumentException if {@code timeDifference} is negative or can't be represented as {@code long milliseconds} - * @deprecated since 3.0. Use {@link #ofTimeDifferenceWithNoGrace(Duration)}} instead + * @deprecated Since 3.0. Use {@link #ofTimeDifferenceWithNoGrace(Duration)}} instead. */ @Deprecated public static JoinWindows of(final Duration timeDifference) throws IllegalArgumentException { @@ -221,7 +221,7 @@ public class JoinWindows extends Windows { * @return this updated builder * @throws IllegalArgumentException if the {@code afterWindowEnd} is negative or can't be represented as {@code long milliseconds} * @throws IllegalStateException if {@link #grace(Duration)} is called after {@link #ofTimeDifferenceAndGrace(Duration, Duration)} or {@link #ofTimeDifferenceWithNoGrace(Duration)} - * @deprecated since 3.0. Use {@link #ofTimeDifferenceAndGrace(Duration, Duration)} instead + * @deprecated Since 3.0. Use {@link #ofTimeDifferenceAndGrace(Duration, Duration)} instead. */ @Deprecated public JoinWindows grace(final Duration afterWindowEnd) throws IllegalArgumentException { diff --git a/streams/src/main/java/org/apache/kafka/streams/kstream/Joined.java b/streams/src/main/java/org/apache/kafka/streams/kstream/Joined.java index 109879579a6..f1df05fe2e5 100644 --- a/streams/src/main/java/org/apache/kafka/streams/kstream/Joined.java +++ b/streams/src/main/java/org/apache/kafka/streams/kstream/Joined.java @@ -273,7 +273,7 @@ public class Joined implements NamedOperation implements NamedOperation keySerde() { @@ -289,7 +289,7 @@ public class Joined implements NamedOperation valueSerde() { @@ -297,7 +297,7 @@ public class Joined implements NamedOperation otherValueSerde() { diff --git a/tools/src/main/java/org/apache/kafka/tools/TopicCommand.java b/tools/src/main/java/org/apache/kafka/tools/TopicCommand.java index d225749fa79..e5171057c6c 100644 --- a/tools/src/main/java/org/apache/kafka/tools/TopicCommand.java +++ b/tools/src/main/java/org/apache/kafka/tools/TopicCommand.java @@ -709,7 +709,7 @@ public abstract class TopicCommand { private final ArgumentAcceptingOptionSpec configOpt; /** - * @deprecated since 4.0 and should not be used any longer. + * @deprecated Since 4.0 and should not be used any longer. */ @Deprecated private final ArgumentAcceptingOptionSpec deleteConfigOpt;