kafka-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ij...@apache.org
Subject kafka git commit: MINOR: Javadoc for ExtendedSerializer and ExtendedDeserializer
Date Wed, 14 Jun 2017 03:36:21 GMT
Repository: kafka
Updated Branches:
  refs/heads/0.11.0 bd58d6ef3 -> 1625d5d9d


MINOR: Javadoc for ExtendedSerializer and ExtendedDeserializer

And add warning about usage.

Author: Ismael Juma <ismael@juma.me.uk>

Reviewers: Jason Gustafson <jason@confluent.io>

Closes #3330 from ijuma/extended-serializer-javadoc

(cherry picked from commit 0082066c56676cbc6721d7ea1d0b6b3c011d7083)
Signed-off-by: Ismael Juma <ismael@juma.me.uk>


Project: http://git-wip-us.apache.org/repos/asf/kafka/repo
Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/1625d5d9
Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/1625d5d9
Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/1625d5d9

Branch: refs/heads/0.11.0
Commit: 1625d5d9df71b55312def277e8311654c449a5b9
Parents: bd58d6e
Author: Ismael Juma <ismael@juma.me.uk>
Authored: Wed Jun 14 04:35:08 2017 +0100
Committer: Ismael Juma <ismael@juma.me.uk>
Committed: Wed Jun 14 04:36:18 2017 +0100

----------------------------------------------------------------------
 .../kafka/common/serialization/Deserializer.java | 15 ++++++++-------
 .../serialization/ExtendedDeserializer.java      | 19 ++++++++++++++++++-
 .../common/serialization/ExtendedSerializer.java | 18 ++++++++++++++++++
 .../kafka/common/serialization/Serializer.java   | 17 ++++++++++-------
 4 files changed, 54 insertions(+), 15 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kafka/blob/1625d5d9/clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java
----------------------------------------------------------------------
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 53c3ba2..f9eb398 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
@@ -20,12 +20,13 @@ import java.io.Closeable;
 import java.util.Map;
 
 /**
+ * An interface for converting bytes to objects.
  *
- * @param <T> Type to be deserialized into.
- *
- * A class that implements this interface is expected to have a constructor with no parameter.
+ * 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.
+ *
+ * @param <T> Type to be deserialized into.
  */
 public interface Deserializer<T> extends Closeable {
 
@@ -34,16 +35,16 @@ public interface Deserializer<T> extends Closeable {
      * @param configs configs in key/value pairs
      * @param isKey whether is for key or value
      */
-    public void configure(Map<String, ?> configs, boolean isKey);
+    void configure(Map<String, ?> configs, boolean isKey);
 
     /**
-     * Deserialize a record value from a bytearray into a value or object.
+     * 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
      */
-    public T deserialize(String topic, byte[] data);
+    T deserialize(String topic, byte[] data);
 
     @Override
-    public void close();
+    void close();
 }

http://git-wip-us.apache.org/repos/asf/kafka/blob/1625d5d9/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedDeserializer.java
----------------------------------------------------------------------
diff --git a/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedDeserializer.java
b/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedDeserializer.java
index 8e95d8d..2d5be4a 100644
--- a/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedDeserializer.java
+++ b/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedDeserializer.java
@@ -20,8 +20,25 @@ import java.util.Map;
 
 import org.apache.kafka.common.header.Headers;
 
+/**
+ * A Deserializer that has access to the headers associated with the record.
+ *
+ * Prefer {@link Deserializer} if access to the headers is not required. Once Kafka drops
support for Java 7, the
+ * {@code deserialize()} method introduced by this interface will be added to Deserializer
with a default implementation
+ * so that backwards compatibility is maintained. This interface may be deprecated once that
happens.
+ *
+ * A class that implements this interface is expected to have a constructor with no parameters.
+ * @param <T>
+ */
 public interface ExtendedDeserializer<T> extends Deserializer<T> {
-    
+
+    /**
+     * 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
+     */
     T deserialize(String topic, Headers headers, byte[] data);
 
     class Wrapper<T> implements ExtendedDeserializer<T> {

http://git-wip-us.apache.org/repos/asf/kafka/blob/1625d5d9/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedSerializer.java
----------------------------------------------------------------------
diff --git a/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedSerializer.java
b/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedSerializer.java
index 32659b4..14fbb47 100644
--- a/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedSerializer.java
+++ b/clients/src/main/java/org/apache/kafka/common/serialization/ExtendedSerializer.java
@@ -20,8 +20,26 @@ import java.util.Map;
 
 import org.apache.kafka.common.header.Headers;
 
+/**
+ * A Serializer that has access to the headers associated with the record.
+ *
+ * Prefer {@link Serializer} if access to the headers is not required. Once Kafka drops support
for Java 7, the
+ * {@code serialize()} method introduced by this interface will be added to Serializer with
a default implementation
+ * so that backwards compatibility is maintained. This interface may be deprecated once that
happens.
+ *
+ * A class that implements this interface is expected to have a constructor with no parameters.
+ * @param <T>
+ */
 public interface ExtendedSerializer<T> extends Serializer<T> {
 
+    /**
+     * 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
+     */
     byte[] serialize(String topic, Headers headers, T data);
 
     class Wrapper<T> implements ExtendedSerializer<T> {

http://git-wip-us.apache.org/repos/asf/kafka/blob/1625d5d9/clients/src/main/java/org/apache/kafka/common/serialization/Serializer.java
----------------------------------------------------------------------
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 43d234c..96fe86b 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
@@ -20,12 +20,13 @@ import java.io.Closeable;
 import java.util.Map;
 
 /**
- *
- * @param <T> Type to be serialized from.
+ * 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.
+ *
+ * @param <T> Type to be serialized from.
  */
 public interface Serializer<T> extends Closeable {
 
@@ -34,20 +35,22 @@ public interface Serializer<T> extends Closeable {
      * @param configs configs in key/value pairs
      * @param isKey whether is for key or value
      */
-    public void configure(Map<String, ?> configs, boolean isKey);
+    void configure(Map<String, ?> configs, boolean isKey);
 
     /**
+     * Convert {@code data} into a byte array.
+     *
      * @param topic topic associated with data
      * @param data typed data
      * @return serialized bytes
      */
-    public byte[] serialize(String topic, T data);
+    byte[] serialize(String topic, T data);
 
     /**
      * Close this serializer.
-     * This method has to be idempotent if the serializer is used in KafkaProducer because
it might be called
-     * multiple times.
+     *
+     * This method must be idempotent as it may be called multiple times.
      */
     @Override
-    public void close();
+    void close();
 }


Mime
View raw message