root
/
kafka
mirror of https://github.com/apache/kafka.git
1
0
Fork 0
Code Issues Actions 2 Packages Projects Releases Wiki Activity

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 <lmagrans@confluent.io>, Kirk True <ktrue@confluent.io>, Chia-Ping Tsai <chia7712@gmail.com>
This commit is contained in:
Matthias J. Sax 2025-01-10 15:32:51 -08:00
parent c888ab9c61
commit 9570c67b8c
2 changed files with 15 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
View File

@ -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.

8
docs/upgrade.html
View File

@ -90,9 +90,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>&gt;=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>&lt;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>
@ -122,6 +122,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>