kafka-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From guozh...@apache.org
Subject kafka git commit: MINOR: Update JavaDoc for KTable helper interfaces
Date Thu, 05 Jan 2017 19:27:28 GMT
Repository: kafka
Updated Branches:
  refs/heads/trunk 77c4eb13a -> 050288ab1


MINOR: Update JavaDoc for KTable helper interfaces

Author: Matthias J. Sax <matthias@confluent.io>

Reviewers: Damian Guy, Eno Thereska, Guozhang Wang

Closes #2315 from mjsax/javaDocImprovements2


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

Branch: refs/heads/trunk
Commit: 050288ab121bfdf486fd94d1a4926e3a819d18d0
Parents: 77c4eb1
Author: Matthias J. Sax <matthias@confluent.io>
Authored: Thu Jan 5 11:27:25 2017 -0800
Committer: Guozhang Wang <wangguoz@gmail.com>
Committed: Thu Jan 5 11:27:25 2017 -0800

----------------------------------------------------------------------
 .../kafka/streams/kstream/Aggregator.java       | 40 +++++++++++++-------
 .../kafka/streams/kstream/Initializer.java      | 17 +++++++--
 .../apache/kafka/streams/kstream/Reducer.java   | 28 ++++++++++----
 3 files changed, 61 insertions(+), 24 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kafka/blob/050288ab/streams/src/main/java/org/apache/kafka/streams/kstream/Aggregator.java
----------------------------------------------------------------------
diff --git a/streams/src/main/java/org/apache/kafka/streams/kstream/Aggregator.java b/streams/src/main/java/org/apache/kafka/streams/kstream/Aggregator.java
index 989d89f..9afce57 100644
--- a/streams/src/main/java/org/apache/kafka/streams/kstream/Aggregator.java
+++ b/streams/src/main/java/org/apache/kafka/streams/kstream/Aggregator.java
@@ -5,9 +5,9 @@
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -17,22 +17,36 @@
 
 package org.apache.kafka.streams.kstream;
 
+import org.apache.kafka.common.annotation.InterfaceStability;
+
 /**
  * The {@link Aggregator} interface for aggregating values of the given key.
- *
- * @param <K>   key type
- * @param <V>   original value type
- * @param <T>   aggregate value type
+ * This is a generalization of {@link Reducer} and allows to have different types for input
value and aggregation
+ * result.
+ * {@link Aggregator} is used in combination with {@link Initializer} that provides an initial
aggregation value.
+ * <p>
+ * {@link Aggregator} can be used to implement aggregation functions like count.
+
+ * @param <K> key type
+ * @param <V> input value type
+ * @param <VA> aggregate value type
+ * @see Initializer
+ * @see KGroupedStream#aggregate(Initializer, Aggregator, org.apache.kafka.common.serialization.Serde,
String)
+ * @see KGroupedStream#aggregate(Initializer, Aggregator, org.apache.kafka.streams.processor.StateStoreSupplier)
+ * @see KGroupedStream#aggregate(Initializer, Aggregator, Windows, org.apache.kafka.common.serialization.Serde,
String)
+ * @see KGroupedStream#aggregate(Initializer, Aggregator, Windows, org.apache.kafka.streams.processor.StateStoreSupplier)
+ * @see Reducer
  */
-public interface Aggregator<K, V, T> {
+@InterfaceStability.Unstable
+public interface Aggregator<K, V, VA> {
 
     /**
      * Compute a new aggregate from the key and value of a record and the current aggregate
of the same key.
      *
-     * @param aggKey     the key of the record
-     * @param value      the value of the record
-     * @param aggregate  the current aggregate value
-     * @return           the new aggregate value
+     * @param key       the key of the record
+     * @param value     the value of the record
+     * @param aggregate the current aggregate value
+     * @return the new aggregate value
      */
-    T apply(K aggKey, V value, T aggregate);
+    VA apply(K key, V value, VA aggregate);
 }

http://git-wip-us.apache.org/repos/asf/kafka/blob/050288ab/streams/src/main/java/org/apache/kafka/streams/kstream/Initializer.java
----------------------------------------------------------------------
diff --git a/streams/src/main/java/org/apache/kafka/streams/kstream/Initializer.java b/streams/src/main/java/org/apache/kafka/streams/kstream/Initializer.java
index 39bc40d..bee598a 100644
--- a/streams/src/main/java/org/apache/kafka/streams/kstream/Initializer.java
+++ b/streams/src/main/java/org/apache/kafka/streams/kstream/Initializer.java
@@ -17,17 +17,26 @@
 
 package org.apache.kafka.streams.kstream;
 
+import org.apache.kafka.common.annotation.InterfaceStability;
+
 /**
  * The {@link Initializer} interface for creating an initial value in aggregations.
+ * {@link Initializer} is used in combination with {@link Aggregator}.
  *
- * @param <T>   aggregate value type
+ * @param <VA> aggregate value type
+ * @see Aggregator
+ * @see KGroupedStream#aggregate(Initializer, Aggregator, org.apache.kafka.common.serialization.Serde,
String)
+ * @see KGroupedStream#aggregate(Initializer, Aggregator, org.apache.kafka.streams.processor.StateStoreSupplier)
+ * @see KGroupedStream#aggregate(Initializer, Aggregator, Windows, org.apache.kafka.common.serialization.Serde,
String)
+ * @see KGroupedStream#aggregate(Initializer, Aggregator, Windows, org.apache.kafka.streams.processor.StateStoreSupplier)
  */
-public interface Initializer<T> {
+@InterfaceStability.Unstable
+public interface Initializer<VA> {
 
     /**
      * Return the initial value for an aggregation.
      *
-     * @return  the initial value for an aggregation
+     * @return the initial value for an aggregation
      */
-    T apply();
+    VA apply();
 }

http://git-wip-us.apache.org/repos/asf/kafka/blob/050288ab/streams/src/main/java/org/apache/kafka/streams/kstream/Reducer.java
----------------------------------------------------------------------
diff --git a/streams/src/main/java/org/apache/kafka/streams/kstream/Reducer.java b/streams/src/main/java/org/apache/kafka/streams/kstream/Reducer.java
index e7cfa0e..5791d9c 100644
--- a/streams/src/main/java/org/apache/kafka/streams/kstream/Reducer.java
+++ b/streams/src/main/java/org/apache/kafka/streams/kstream/Reducer.java
@@ -5,9 +5,9 @@
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -17,19 +17,33 @@
 
 package org.apache.kafka.streams.kstream;
 
+import org.apache.kafka.common.annotation.InterfaceStability;
+
 /**
  * The {@link Reducer} interface for combining two values of the same type into a new value.
+ * In contrast to {@link Aggregator} the result type must be the same as the input type.
+ * <p>
+ * The provided values can be either original values from input {@link org.apache.kafka.streams.KeyValue
KeyValue} pair
+ * records or be a previously computed result from {@link Reducer#apply(Object, Object)}.
+ * <p>
+ * {@link Reducer} can be used to implement aggregation functions like sum, min, or max.
  *
- * @param <V>   value type
+ * @param <V> value type
+ * @see KGroupedStream#reduce(Reducer, String)
+ * @see KGroupedStream#reduce(Reducer, org.apache.kafka.streams.processor.StateStoreSupplier)
+ * @see KGroupedStream#reduce(Reducer, Windows, String)
+ * @see KGroupedStream#reduce(Reducer, org.apache.kafka.streams.processor.StateStoreSupplier)
+ * @see Aggregator
  */
+@InterfaceStability.Unstable
 public interface Reducer<V> {
 
     /**
      * Aggregate the two given values into a single one.
      *
-     * @param value1  the first value for the aggregation
-     * @param value2  the second value for the aggregation
-     * @return        the aggregated value
+     * @param value1 the first value for the aggregation
+     * @param value2 the second value for the aggregation
+     * @return the aggregated value
      */
     V apply(V value1, V value2);
 }


Mime
View raw message