Skip to content

MINOR: cleanup JavaDocs for deprecation warnings #18402

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
clolov merged 2 commits into from
Jan 7, 2025
Merged

MINOR: cleanup JavaDocs for deprecation warnings #18402

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ba2b88
MINOR: cleanup JavaDocs for deprecation warnings
mjsax Jan 6, 2025
f6ad945
spotless
mjsax Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupDescription.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ public class ConsumerGroupDescription {
private final Optional<Integer> 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,
Expand All @@ -60,7 +60,7 @@ public ConsumerGroupDescription(String groupId,
}

/**
* @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,
Expand All @@ -74,7 +74,7 @@ public ConsumerGroupDescription(String groupId,
}

/**
* @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,
Expand Down
6 changes: 3 additions & 3 deletions clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupListing.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ public ConsumerGroupListing(String groupId, boolean isSimpleConsumerGroup) {
* @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<ConsumerGroupState> state) {
Expand All @@ -63,7 +63,7 @@ public ConsumerGroupListing(String groupId, boolean isSimpleConsumerGroup, Optio
* @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(
Expand Down Expand Up @@ -133,7 +133,7 @@ public Optional<GroupState> groupState() {

/**
* Consumer Group state
* @deprecated Since 4.0. Use {@link #groupState()}.
* @deprecated Since 4.0. Use {@link #groupState()} instead.
*/
@Deprecated
public Optional<ConsumerGroupState> state() {
Expand Down
4 changes: 2 additions & 2 deletions clients/src/main/java/org/apache/kafka/clients/admin/CreateDelegationTokenOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ public Optional<KafkaPrincipal> owner() {
}

/**
* @deprecated since 4.0 and should not be used any longer.
* @deprecated Since 4.0 and should not be used any longer.
*/
@Deprecated
public CreateDelegationTokenOptions maxlifeTimeMs(long maxLifetimeMs) {
Expand All @@ -68,7 +68,7 @@ public CreateDelegationTokenOptions maxLifetimeMs(long maxLifetimeMs) {
}

/**
* @deprecated since 4.0 and should not be used any longer.
* @deprecated Since 4.0 and should not be used any longer.
*/
@Deprecated
public long maxlifeTimeMs() {
Expand Down
4 changes: 2 additions & 2 deletions clients/src/main/java/org/apache/kafka/clients/admin/ListConsumerGroupsOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ public ListConsumerGroupsOptions inGroupStates(Set<GroupState> groupStates) {
* If states is set, only groups in these states will be returned by listConsumerGroups().
* Otherwise, all groups are returned.
* This operation is supported by brokers with version 2.6.0 or later.
* @deprecated Since 4.0. Use {@link #inGroupStates(Set)}.
* @deprecated Since 4.0. Use {@link #inGroupStates(Set)} instead.
*/
@Deprecated
public ListConsumerGroupsOptions inStates(Set<ConsumerGroupState> states) {
Expand Down Expand Up @@ -80,7 +80,7 @@ public Set<GroupState> groupStates() {

/**
* Returns the list of States that are requested or empty if no states have been specified.
* @deprecated Since 4.0. Use {@link #inGroupStates(Set)}.
* @deprecated Since 4.0. Use {@link #inGroupStates(Set)} instead.
*/
@Deprecated
public Set<ConsumerGroupState> states() {
Expand Down
6 changes: 3 additions & 3 deletions clients/src/main/java/org/apache/kafka/clients/admin/MemberDescription.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ public 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(
Expand All @@ -81,7 +81,7 @@ public 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(
Expand All @@ -102,7 +102,7 @@ public 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,
Expand Down
3 changes: 3 additions & 0 deletions clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecords.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@ public class ConsumerRecords<K, V> implements Iterable<ConsumerRecord<K, V>> {
private final Map<TopicPartition, List<ConsumerRecord<K, V>>> records;
private final Map<TopicPartition, OffsetAndMetadata> nextOffsets;

/**
* @deprecated Since 4.0. Use {@link #ConsumerRecords(Map, Map)} instead.
*/
@Deprecated
public ConsumerRecords(Map<TopicPartition, List<ConsumerRecord<K, V>>> records) {
this(records, Map.of());
Expand Down
2 changes: 1 addition & 1 deletion clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ public class MockConsumer<K, V> implements Consumer<K, V> {
private final List<KafkaMetric> 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) {
Expand Down
2 changes: 1 addition & 1 deletion clients/src/main/java/org/apache/kafka/clients/consumer/OffsetResetStrategy.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
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 {
Expand Down
3 changes: 3 additions & 0 deletions clients/src/main/java/org/apache/kafka/common/errors/RecordDeserializationException.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,9 @@ public enum DeserializationExceptionOrigin {
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,
Expand Down
16 changes: 10 additions & 6 deletions streams/src/main/java/org/apache/kafka/streams/StreamsConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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";
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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 <code>org.apache.kafka.streams.errors.ProductionExceptionHandler</code> 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";
Expand Down Expand Up @@ -2032,7 +2036,7 @@ public DeserializationExceptionHandler deserializationExceptionHandler() {
}

/**
* @deprecated since kafka 4.0; use {@link #deserializationExceptionHandler()} instead
* @deprecated Since 4.0. Use {@link #deserializationExceptionHandler()} instead.
*/
@Deprecated
@SuppressWarnings("WeakerAccess")
Expand All @@ -2054,7 +2058,7 @@ public ProductionExceptionHandler productionExceptionHandler() {
}

/**
* @deprecated since kafka 4.0; use {@link #productionExceptionHandler()} instead
* @deprecated Since 4.0. Use {@link #productionExceptionHandler()} instead.
*/
@Deprecated
@SuppressWarnings("WeakerAccess")
Expand Down
3 changes: 3 additions & 0 deletions streams/src/main/java/org/apache/kafka/streams/errors/DefaultProductionExceptionHandler.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@
* 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
Expand Down
3 changes: 3 additions & 0 deletions streams/src/main/java/org/apache/kafka/streams/errors/LogAndContinueExceptionHandler.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@
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
Expand Down
3 changes: 3 additions & 0 deletions streams/src/main/java/org/apache/kafka/streams/errors/LogAndFailExceptionHandler.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@
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
Expand Down
2 changes: 1 addition & 1 deletion streams/src/main/java/org/apache/kafka/streams/kstream/ForeachProcessor.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
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<K, V> implements Processor<K, V, Void, Void> {
Expand Down
4 changes: 2 additions & 2 deletions streams/src/main/java/org/apache/kafka/streams/kstream/JoinWindows.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ public static JoinWindows ofTimeDifferenceWithNoGrace(final Duration timeDiffere
* @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 {
Expand Down Expand Up @@ -221,7 +221,7 @@ public long size() {
* @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.

@frankvicky frankvicky Mar 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @mjsax
I notice that this has been deprecated since 3.0 which is passed one year since it was deprecated.
Do we need to delete this one in 4.0?

@mjsax mjsax Mar 7, 2025

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for paying attention! We decided to keep this old API on purpose and not remove with 4.0.

Cf https://issues.apache.org/jira/browse/KAFKA-13813

*/
@Deprecated
public JoinWindows grace(final Duration afterWindowEnd) throws IllegalArgumentException {
Expand Down
8 changes: 4 additions & 4 deletions streams/src/main/java/org/apache/kafka/streams/kstream/Joined.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -273,31 +273,31 @@ public Joined<K, VLeft, VRight> withGracePeriod(final Duration gracePeriod) {


/**
* @deprecated since 4.0 and should not be used any longer.
* @deprecated Since 4.0 and should not be used any longer.
*/
@Deprecated
public Duration gracePeriod() {
return gracePeriod;
}

/**
* @deprecated since 4.0 and should not be used any longer.
* @deprecated Since 4.0 and should not be used any longer.
*/
@Deprecated
public Serde<K> keySerde() {
return keySerde;
}

/**
* @deprecated since 4.0 and should not be used any longer.
* @deprecated Since 4.0 and should not be used any longer.
*/
@Deprecated
public Serde<VLeft> valueSerde() {
return leftValueSerde;
}

/**
* @deprecated since 4.0 and should not be used any longer.
* @deprecated Since 4.0 and should not be used any longer.
*/
@Deprecated
public Serde<VRight> otherValueSerde() {
Expand Down
2 changes: 1 addition & 1 deletion tools/src/main/java/org/apache/kafka/tools/TopicCommand.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -709,7 +709,7 @@ public static final class TopicCommandOptions extends CommandDefaultOptions {
private final ArgumentAcceptingOptionSpec<String> 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<String> deleteConfigOpt;
Expand Down