This is an automated email from the ASF dual-hosted git repository.
mjsax pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/trunk by this push:
new 834f72b03de KAFKA-15527: Update docs and JavaDocs (#14600)
834f72b03de is described below
commit 834f72b03de40fb47caaad1397ed061de57c2509
Author: Hanyu Zheng <135176127+hanyuzhe...@users.noreply.github.com>
AuthorDate: Thu Oct 26 17:48:28 2023 -0700
KAFKA-15527: Update docs and JavaDocs (#14600)
Part of KIP-985.
Updates JavaDocs for `RangeQuery` and `ReadOnlyKeyValueStore` with regard
to ordering guarantees.
Updates Kafka Streams upgrade guide with KIP information.
Reviewer: Matthias J. Sax <matth...@confluent.io>
---
docs/streams/upgrade-guide.html | 6 ++++++
.../main/java/org/apache/kafka/streams/query/RangeQuery.java | 10 +++++++---
.../org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java | 8 ++++----
3 files changed, 17 insertions(+), 7 deletions(-)
diff --git a/docs/streams/upgrade-guide.html b/docs/streams/upgrade-guide.html
index 6d75d724281..71aac5c6401 100644
--- a/docs/streams/upgrade-guide.html
+++ b/docs/streams/upgrade-guide.html
@@ -133,6 +133,12 @@
More details about the new config
<code>StreamsConfig#TOPOLOGY_OPTIMIZATION</code> can be found in <a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-295%3A+Add+Streams+Configuration+Allowing+for+Optional+Topology+Optimization";>KIP-295</a>.
</p>
+ <h3><a id="streams_api_changes_370"
href="#streams_api_changes_370">Streams API changes in 3.7.0</a></h3>
+ <p>
+ IQv2 supports <code>RangeQuery</code> that allows to specify
unbounded, bounded, or half-open key-ranges, which return data in ascending
(byte[]-lexicographical) order (per partition).
+ <a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-985%3A+Add+reverseRange+and+reverseAll+query+over+kv-store+in+IQv2";>KIP-985</a>
extends this functionality by adding <code>.withDescendingKeys()<code> to
allow user to receive data in descending order.
+ </p>
+
<h3><a id="streams_api_changes_360"
href="#streams_api_changes_360">Streams API changes in 3.6.0</a></h3>
<p>
Rack aware task assignment was introduced in <a
href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-925%3A+Rack+aware+task+assignment+in+Kafka+Streams";>KIP-925</a>.
diff --git
a/streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java
b/streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java
index d44bc26b74c..325a4e457a5 100644
--- a/streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java
+++ b/streams/src/main/java/org/apache/kafka/streams/query/RangeQuery.java
@@ -30,7 +30,9 @@ import java.util.Optional;
* <p>
* A range query retrieves a set of records, specified using an upper and/or
lower bound on the keys.
* <p>
- * A scan query retrieves all records contained in the store.
+ * A scan query retrieves all records contained in the store.
+ * <p>
+ * Keys' order is based on the serialized byte[] of the keys, not the
'logical' key order.
* <p>
*/
@Evolving
@@ -60,7 +62,8 @@ public final class RangeQuery<K, V> implements
Query<KeyValueIterator<K, V>> {
}
/**
- * Determines if the query keys are in ascending order.
+ * Determines if the serialized byte[] of the keys in ascending order.
+ * Order is based on the serialized byte[] of the keys, not the 'logical'
key order.
* @return true if ascending, false otherwise.
*/
public boolean isKeyAscending() {
@@ -68,7 +71,8 @@ public final class RangeQuery<K, V> implements
Query<KeyValueIterator<K, V>> {
}
/**
- * Set the query to return keys in descending order.
+ * Set the query to return the serialized byte[] of the keys in descending
order.
+ * Order is based on the serialized byte[] of the keys, not the 'logical'
key order.
* @return a new RangeQuery instance with descending flag set.
*/
public RangeQuery<K, V> withDescendingKeys() {
diff --git
a/streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java
b/streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java
index 9be1d9eceb8..f905a296256 100644
---
a/streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java
+++
b/streams/src/main/java/org/apache/kafka/streams/state/ReadOnlyKeyValueStore.java
@@ -48,13 +48,13 @@ public interface ReadOnlyKeyValueStore<K, V> {
* Get an iterator over a given range of keys. This iterator must be
closed after use.
* The returned iterator must be safe from {@link
java.util.ConcurrentModificationException}s
* and must not return null values.
- * Order is not guaranteed as bytes lexicographical ordering might not
represent key order.
+ * Order is based on the serialized byte[] of the keys, not the 'logical'
key order.
*
* @param from The first key that could be in the range, where iteration
starts from.
* A null value indicates that the range starts with the first
element in the store.
* @param to The last key that could be in the range, where iteration
ends.
* A null value indicates that the range ends with the last
element in the store.
- * @return The iterator for this range, from smallest to largest bytes.
+ * @return The iterator for this range, from key with the smallest bytes
to the key with the largest bytes of keys.
* @throws InvalidStateStoreException if the store is not initialized
*/
KeyValueIterator<K, V> range(K from, K to);
@@ -63,13 +63,13 @@ public interface ReadOnlyKeyValueStore<K, V> {
* Get a reverse iterator over a given range of keys. This iterator must
be closed after use.
* The returned iterator must be safe from {@link
java.util.ConcurrentModificationException}s
* and must not return null values.
- * Order is not guaranteed as bytes lexicographical ordering might not
represent key order.
+ * Order is based on the serialized byte[] of the keys, not the 'logical'
key order.
*
* @param from The first key that could be in the range, where iteration
ends.
* A null value indicates that the range starts with the first
element in the store.
* @param to The last key that could be in the range, where iteration
starts from.
* A null value indicates that the range ends with the last
element in the store.
- * @return The reverse iterator for this range, from largest to smallest
key bytes.
+ * @return The iterator for this range, from key with the smallest bytes
to the key with the largest bytes of keys.
* @throws InvalidStateStoreException if the store is not initialized
*/
default KeyValueIterator<K, V> reverseRange(K from, K to) {
