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 3b38b016c8c KAFKA-17825: Update docs for ByteBufferDeserializer
changes in 3.6 release (#18466)
3b38b016c8c is described below
commit 3b38b016c8c0868c91238d78bbaffb77893274f6
Author: Matthias J. Sax <[email protected]>
AuthorDate: Fri Jan 10 15:32:51 2025 -0800
KAFKA-17825: Update docs for ByteBufferDeserializer changes in 3.6 release
(#18466)
KIP-863 introduced a change to ByteBufferDeserializer which is not
properly documented, but should be called out because it could surface
bugs in application code which using ByteBufferDeserializer.
Reviewers: Lianet Magrans <[email protected]>, Kirk True
<[email protected]>, Chia-Ping Tsai <[email protected]>
---
.../org/apache/kafka/common/serialization/Deserializer.java | 10 +++++++++-
docs/upgrade.html | 8 ++++++--
2 files changed, 15 insertions(+), 3 deletions(-)
diff --git
a/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
b/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
index 9fd8d50be74..ad8d2bfe4d4 100644
---
a/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
+++
b/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
@@ -63,7 +63,15 @@ public interface Deserializer<T> extends Closeable {
}
/**
- * Deserialize a record value from a ByteBuffer into a value or object.
+ * Deserialize a record value from a {@link ByteBuffer} into a value or
object.
+ *
+ * <p>If {@code ByteBufferDeserializer} is used by an application, the
application code cannot make any assumptions
+ * about the returned {@link ByteBuffer} like the position, limit,
capacity, etc., or if it is backed by
+ * {@link ByteBuffer#hasArray() an array or not}.
+ *
+ * <p>Similarly, if this method is overridden, the implementation cannot
make any assumptions about the
+ * passed in {@link ByteBuffer} either.
+ *
* @param topic topic associated with the data
* @param headers headers associated with the record; may be empty.
* @param data serialized ByteBuffer; may be null; implementations are
recommended to handle null by returning a value or null rather than throwing an
exception.
diff --git a/docs/upgrade.html b/docs/upgrade.html
index 24e28868220..56efaffbd04 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -656,9 +656,9 @@
<li>The Apache Zookeeper dependency has been upgraded to 3.8.1 due to
3.6 reaching end-of-life. To bring both your
Kafka and Zookeeper clusters to the latest versions:
<ul>
- <li><b>>=2.4</b> Kafka clusters can be updated directly.
+ <li><b>>=2.4</b> Kafka clusters can be updated directly.
Zookeeper clusters which are running binaries bundled with
Kafka versions 2.4 or above can be updated directly.</li>
- <li><b><2.4</b> Kafka clusters first need to be updated to a
version greater than 2.4 and smaller than 3.6.
+ <li><b><2.4</b> Kafka clusters first need to be updated to
a version greater than 2.4 and smaller than 3.6.
Zookeeper clusters which are running binaries bundled with
Kafka versions below 2.4 need to be updated to any
binaries bundled with Kafka versions greater than 2.4 and
smaller than 3.6. You can then follow the first bullet-point.</li>
</ul>
@@ -688,6 +688,10 @@
The configuration can also be updated dynamically and is applied
to the broker. Workloads running on version 3.6.0 with compression can
experience
InvalidRecordExceptions and UnknownServerExceptions. Upgrading to
3.6.1 or newer or disabling the feature fixes the issue.
</li>
+ <li>The <code>ByteBufferDeserializer</code> (<a
href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=225152035";>KIP-863</a>)
+ was changed to avoid unnecessary deep-copies of data. This changes
the behavior of the deserializer as user code cannot make any assumptions
+ about buffer position, limit, capacity any longer.
+ </li>
</ul>
<h4><a id="upgrade_3_5_2" href="#upgrade_3_5_2">Upgrading to 3.5.2 from any
version 0.8.x through 3.4.x</a></h4>
