This is an automated email from the ASF dual-hosted git repository.
mjsax pushed a commit to branch 3.8
in repository https://gitbox.apache.org/repos/asf/kafka.git
The following commit(s) were added to refs/heads/3.8 by this push:
new d6a66d33d59 KAFKA-17825: Update docs for ByteBufferDeserializer
changes in 3.6 release (#18466)
d6a66d33d59 is described below
commit d6a66d33d593a2d4b593d1a4eb2bd79f7ff4a0c0
Author: Matthias J. Sax <matth...@confluent.io>
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 <lmagr...@confluent.io>, Kirk True
<kt...@confluent.io>, Chia-Ping Tsai <chia7...@gmail.com>
---
.../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 4c202fb1e67..d9a732c083c 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -291,9 +291,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>
@@ -323,6 +323,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>
