aliehsaeedii commented on code in PR #22729: URL: https://github.com/apache/kafka/pull/22729#discussion_r3528385824
########## streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyRecordIterator.java: ########## @@ -0,0 +1,45 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.kafka.streams.state; + +import org.apache.kafka.common.annotation.InterfaceStability.Evolving; +import org.apache.kafka.streams.processor.api.ReadOnlyRecord; + +import java.io.Closeable; +import java.util.Iterator; + + +/** + * Iterator interface of {@link ReadOnlyRecord ReadOnlyRecord<K, V>}. Review Comment: This breaks the javadoc build: the `<K, V>` inside the `{@link}` label is treated as malformed HTML, and Kafka runs javadoc with `-Werror` — `./gradlew :streams:javadoc` fails with `warning: invalid input: '<'` on this line. Simplest fix is to match `KeyValueIterator`'s wording: `Iterator interface of {@link ReadOnlyRecord}.` (or escape it as `ReadOnlyRecord<K, V>` if you want to keep the generics in the rendered text). ########## streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyRecordIterator.java: ########## @@ -0,0 +1,45 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.kafka.streams.state; + +import org.apache.kafka.common.annotation.InterfaceStability.Evolving; +import org.apache.kafka.streams.processor.api.ReadOnlyRecord; + +import java.io.Closeable; +import java.util.Iterator; + + +/** + * Iterator interface of {@link ReadOnlyRecord ReadOnlyRecord<K, V>}. + * <p> + * This is the result type of the headers-aware range/window/session IQv2 query types: it yields + * {@link ReadOnlyRecord} elements directly, so each element carries its own key, value, timestamp, + * and headers. + * <p> + * Users must call its {@code close} method explicitly upon completeness to release resources, + * or use try-with-resources statement (available since JDK7) for this {@link Closeable} class. + * Note that {@code remove()} is not supported. + * + * @param <K> Type of keys + * @param <V> Type of values + */ +@Evolving Review Comment: Should this also carry `@InterfaceAudience.Public`? Its element type `ReadOnlyRecord` is annotated `@InterfaceAudience.Public @Evolving`, and the sibling iterators in this package (`KeyValueIterator`, `WindowStoreIterator`) are `@InterfaceAudience.Public` — since this is a public IQv2 result type, it seems it should follow the same convention. ########## streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyRecordIterator.java: ########## @@ -0,0 +1,45 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.kafka.streams.state; + +import org.apache.kafka.common.annotation.InterfaceStability.Evolving; +import org.apache.kafka.streams.processor.api.ReadOnlyRecord; + +import java.io.Closeable; +import java.util.Iterator; + + +/** + * Iterator interface of {@link ReadOnlyRecord ReadOnlyRecord<K, V>}. + * <p> + * This is the result type of the headers-aware range/window/session IQv2 query types: it yields + * {@link ReadOnlyRecord} elements directly, so each element carries its own key, value, timestamp, + * and headers. + * <p> + * Users must call its {@code close} method explicitly upon completeness to release resources, + * or use try-with-resources statement (available since JDK7) for this {@link Closeable} class. + * Note that {@code remove()} is not supported. + * + * @param <K> Type of keys + * @param <V> Type of values + */ +@Evolving +public interface ReadOnlyRecordIterator<K, V> extends Iterator<ReadOnlyRecord<K, V>>, Closeable { Review Comment: Question: `KeyValueIterator` offers `peekNextKey()`; is omitting it here a deliberate choice in KIP-1356? It's defensible either way — each `ReadOnlyRecord` carries its own key, so `peek`-style lookahead is less essential — but worth confirming the interface matches what the KIP specifies, since adding it later to an `@Evolving` interface is easy but implementors would then need to change. ########## streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyRecordIterator.java: ########## @@ -0,0 +1,45 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.kafka.streams.state; + +import org.apache.kafka.common.annotation.InterfaceStability.Evolving; +import org.apache.kafka.streams.processor.api.ReadOnlyRecord; + +import java.io.Closeable; +import java.util.Iterator; + + Review Comment: Nit: double blank line before the javadoc — one blank line after the imports is the convention in this package. -- 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. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
