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 810beef50e1 MINOR: improve (De)Serializer JavaDocs (#19467)
810beef50e1 is described below
commit 810beef50e189cc9d1a0839961dffd14930ffe2e
Author: Matthias J. Sax <[email protected]>
AuthorDate: Thu Apr 17 11:23:15 2025 -0700
MINOR: improve (De)Serializer JavaDocs (#19467)
Reviewers: Kirk True <[email protected]>, Lianet Magrans
<[email protected]>
---
.../kafka/common/serialization/Deserializer.java | 72 ++++++++++++++++------
.../kafka/common/serialization/Serializer.java | 52 +++++++++++-----
2 files changed, 88 insertions(+), 36 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 1997e66aad2..d48574b54fa 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
@@ -25,20 +25,25 @@ import java.util.Map;
/**
* An interface for converting bytes to objects.
- *
* A class that implements this interface is expected to have a constructor
with no parameters.
- * <p>
- * Implement {@link org.apache.kafka.common.ClusterResourceListener} to
receive cluster metadata once it's available. Please see the class
documentation for ClusterResourceListener for more information.
- * Implement {@link org.apache.kafka.common.metrics.Monitorable} to enable the
deserializer to register metrics. The following tags are automatically added to
- * all metrics registered: <code>config</code> set to either
<code>key.deserializer</code> or <code>value.deserializer</code>, and
<code>class</code> set to the Deserializer class name.
+ *
+ * <p>This interface can be combined with {@link
org.apache.kafka.common.ClusterResourceListener ClusterResourceListener}
+ * to receive cluster metadata once it's available, as well as {@link
org.apache.kafka.common.metrics.Monitorable Monitorable}
+ * to enable the deserializer to register metrics. For the latter, the
following tags are automatically added to
+ * all metrics registered: {@code config} set to either {@code
key.deserializer} or {@code value.deserializer},
+ * and {@code class} set to the deserializer class name.
+ *
* @param <T> Type to be deserialized into.
*/
public interface Deserializer<T> extends Closeable {
/**
* Configure this class.
- * @param configs configs in key/value pairs
- * @param isKey whether is for key or value
+ *
+ * @param configs
+ * configs in key/value pairs
+ * @param isKey
+ * whether the deserializer is used for the key or the value
*/
default void configure(Map<String, ?> configs, boolean isKey) {
// intentionally left blank
@@ -46,18 +51,35 @@ public interface Deserializer<T> extends Closeable {
/**
* Deserialize a record value from a byte array into a value or object.
- * @param topic topic associated with the data
- * @param data serialized bytes; may be null; implementations are
recommended to handle null by returning a value or null rather than throwing an
exception.
- * @return deserialized typed data; may be null
+ *
+ * <p>It is recommended to deserialize a {@code null} byte array to a
{@code null} object.
+ *
+ * @param topic
+ * topic associated with the data
+ * @param data
+ * serialized bytes; may be {@code null}
+ *
+ * @return deserialized typed data; may be {@code null}
*/
T deserialize(String topic, byte[] data);
/**
* Deserialize a record value from a byte array into a value or object.
- * @param topic topic associated with the data
- * @param headers headers associated with the record; may be empty.
- * @param data serialized bytes; may be null; implementations are
recommended to handle null by returning a value or null rather than throwing an
exception.
- * @return deserialized typed data; may be null
+ *
+ * <p>It is recommended to deserialize a {@code null} byte array to a
{@code null} object.
+ *
+ * <p>Note that the passed in {@link Headers} may be empty, but never
{@code null}.
+ * The implementation is allowed to modify the passed in headers, as a
side effect of deserialization.
+ * It is considered best practice to not delete or modify existing
headers, but rather only add new ones.
+ *
+ * @param topic
+ * topic associated with the data
+ * @param headers
+ * headers associated with the record
+ * @param data
+ * serialized bytes; may be {@code null}
+ *
+ * @return deserialized typed data; may be {@code null}
*/
default T deserialize(String topic, Headers headers, byte[] data) {
return deserialize(topic, data);
@@ -73,10 +95,20 @@ public interface Deserializer<T> extends Closeable {
* <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.
- * @return deserialized typed data; may be null
+ * <p>It is recommended to deserialize a {@code null} {@link ByteBuffer}
to a {@code null} object.
+ *
+ * <p>Note that the passed in {@link Headers} may be empty, but never
{@code null}.
+ * The implementation is allowed to modify the passed in headers, as a
side effect of deserialization.
+ * It is considered best practice to not delete or modify existing
headers, but rather only add new ones.
+ *
+ * @param topic
+ * topic associated with the data
+ * @param headers
+ * headers associated with the record
+ * @param data
+ * serialized ByteBuffer; may be {@code null}
+ *
+ * @return deserialized typed data; may be {@code null}
*/
default T deserialize(String topic, Headers headers, ByteBuffer data) {
return deserialize(topic, headers, Utils.toNullableArray(data));
@@ -84,8 +116,8 @@ public interface Deserializer<T> extends Closeable {
/**
* Close this deserializer.
- * <p>
- * This method must be idempotent as it may be called multiple times.
+ *
+ * <p>This method must be idempotent as it may be called multiple times.
*/
@Override
default void close() {
diff --git
a/clients/src/main/java/org/apache/kafka/common/serialization/Serializer.java
b/clients/src/main/java/org/apache/kafka/common/serialization/Serializer.java
index 03eab512aa7..0730b71bcad 100644
---
a/clients/src/main/java/org/apache/kafka/common/serialization/Serializer.java
+++
b/clients/src/main/java/org/apache/kafka/common/serialization/Serializer.java
@@ -23,20 +23,25 @@ import java.util.Map;
/**
* An interface for converting objects to bytes.
- *
* A class that implements this interface is expected to have a constructor
with no parameter.
- * <p>
- * Implement {@link org.apache.kafka.common.ClusterResourceListener} to
receive cluster metadata once it's available. Please see the class
documentation for ClusterResourceListener for more information.
- * Implement {@link org.apache.kafka.common.metrics.Monitorable} to enable the
serializer to register metrics. The following tags ae automatically added to
- * all metrics registered: <code>config</code> set to either
<code>key.serializer</code> or <code>value.serializer</code>, and
<code>class</code> set to the Serializer class name.
+ *
+ * <p>This interface can be combined with {@link
org.apache.kafka.common.ClusterResourceListener ClusterResourceListener}
+ * to receive cluster metadata once it's available, as well as {@link
org.apache.kafka.common.metrics.Monitorable Monitorable}
+ * to enable the serializer to register metrics. For the latter, the following
tags are automatically added to all
+ * metrics registered: {@code config} set to either {@code key.serializer} or
{@code value.serializer},
+ * and {@code class} set to the serializer class name.
+ *
* @param <T> Type to be serialized from.
*/
public interface Serializer<T> extends Closeable {
/**
* Configure this class.
- * @param configs configs in key/value pairs
- * @param isKey whether is for key or value
+ *
+ * @param configs
+ * configs in key/value pairs
+ * @param isKey
+ * whether the serializer is used for the key or the value
*/
default void configure(Map<String, ?> configs, boolean isKey) {
// intentionally left blank
@@ -45,19 +50,34 @@ public interface Serializer<T> extends Closeable {
/**
* Convert {@code data} into a byte array.
*
- * @param topic topic associated with data
- * @param data typed data
- * @return serialized bytes
+ * <p>It is recommended to serialize {@code null} data to the {@code null}
byte array.
+ *
+ * @param topic
+ * topic associated with data
+ * @param data
+ * typed data; may be {@code null}
+ *
+ * @return serialized bytes; may be {@code null}
*/
byte[] serialize(String topic, T data);
/**
* Convert {@code data} into a byte array.
*
- * @param topic topic associated with data
- * @param headers headers associated with the record
- * @param data typed data
- * @return serialized bytes
+ * <p>It is recommended to serialize {@code null} data to the {@code null}
byte array.
+ *
+ * <p>Note that the passed in {@link Headers} may be empty, but never
{@code null}.
+ * The implementation is allowed to modify the passed in headers, as a
side effect of serialization.
+ * It is considered best practice to not delete or modify existing
headers, but rather only add new ones.
+ *
+ * @param topic
+ * topic associated with data
+ * @param headers
+ * headers associated with the record
+ * @param data
+ * typed data; may be {@code null}
+ *
+ * @return serialized bytes; may be {@code null}
*/
default byte[] serialize(String topic, Headers headers, T data) {
return serialize(topic, data);
@@ -65,8 +85,8 @@ public interface Serializer<T> extends Closeable {
/**
* Close this serializer.
- * <p>
- * This method must be idempotent as it may be called multiple times.
+ *
+ * <p>This method must be idempotent as it may be called multiple times.
*/
@Override
default void close() {
