Updated Branches: refs/heads/master c64dfda7f -> 21c07c8e3
SAMZA-129: Added Javadoc for various API classes/interfaces Project: http://git-wip-us.apache.org/repos/asf/incubator-samza/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-samza/commit/21c07c8e Tree: http://git-wip-us.apache.org/repos/asf/incubator-samza/tree/21c07c8e Diff: http://git-wip-us.apache.org/repos/asf/incubator-samza/diff/21c07c8e Branch: refs/heads/master Commit: 21c07c8e3b061149ebb4c097d7e02f1b6c2c5e4c Parents: c64dfda Author: Jonathan Poltak Samosir <jonathan dot samosir at gmail dot com> Authored: Thu Jan 16 14:47:52 2014 -0800 Committer: Jakob Homan <[email protected]> Committed: Thu Jan 16 14:47:52 2014 -0800 ---------------------------------------------------------------------- .../samza/system/IncomingMessageEnvelope.java | 12 ++++++++++++ .../samza/system/SystemStreamPartition.java | 20 +++++++++++++++++++- .../org/apache/samza/task/InitableTask.java | 10 ++++++++++ .../org/apache/samza/task/MessageCollector.java | 7 +++++++ .../java/org/apache/samza/task/StreamTask.java | 10 ++++++++++ .../org/apache/samza/task/WindowableTask.java | 9 +++++++++ 6 files changed, 67 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/21c07c8e/samza-api/src/main/java/org/apache/samza/system/IncomingMessageEnvelope.java ---------------------------------------------------------------------- diff --git a/samza-api/src/main/java/org/apache/samza/system/IncomingMessageEnvelope.java b/samza-api/src/main/java/org/apache/samza/system/IncomingMessageEnvelope.java index f70dfea..4b14312 100644 --- a/samza-api/src/main/java/org/apache/samza/system/IncomingMessageEnvelope.java +++ b/samza-api/src/main/java/org/apache/samza/system/IncomingMessageEnvelope.java @@ -19,12 +19,24 @@ package org.apache.samza.system; +/** + * This class represents a message envelope that is received by a StreamTask for each message that is received from a + * partition of a specific input stream. + */ public class IncomingMessageEnvelope { private final SystemStreamPartition systemStreamPartition; private final String offset; private final Object key; private final Object message; + /** + * Constructs a new IncomingMessageEnvelope from specified components. + * @param systemStreamPartition The aggregate object representing the incoming stream name, the name of the cluster + * from which the stream came, and the partition of the stream from which the message was received. + * @param offset The offset in the partition that the message was received from. + * @param key A deserialized key received from the partition offset. + * @param message A deserialized message received from the partition offset. + */ public IncomingMessageEnvelope(SystemStreamPartition systemStreamPartition, String offset, Object key, Object message) { this.systemStreamPartition = systemStreamPartition; this.offset = offset; http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/21c07c8e/samza-api/src/main/java/org/apache/samza/system/SystemStreamPartition.java ---------------------------------------------------------------------- diff --git a/samza-api/src/main/java/org/apache/samza/system/SystemStreamPartition.java b/samza-api/src/main/java/org/apache/samza/system/SystemStreamPartition.java index 9fdfb1d..6b7ef5e 100644 --- a/samza-api/src/main/java/org/apache/samza/system/SystemStreamPartition.java +++ b/samza-api/src/main/java/org/apache/samza/system/SystemStreamPartition.java @@ -21,20 +21,38 @@ package org.apache.samza.system; import org.apache.samza.Partition; +/** + * Aggregate object representing a partition of a Samza stream. + */ public class SystemStreamPartition extends SystemStream { protected final Partition partition; protected final int hash; - + + /** + * Constructs a Samza stream partition object from specified components. + * @param system The name of the system of which this stream is associated with. + * @param stream The name of the stream as specified in the stream configuration file. + * @param partition The partition in the stream of which this object is associated with. + */ public SystemStreamPartition(String system, String stream, Partition partition) { super(system, stream); this.partition = partition; this.hash = computeHashCode(); } + /** + * Constructs a Samza stream partition object based upon another Samza stream partition. + * @param other Reference to an already existing Samza stream partition. + */ public SystemStreamPartition(SystemStreamPartition other) { this(other.getSystem(), other.getStream(), other.getPartition()); } + /** + * Constructs a Samza stream partition object based upon another Samza stream and a specified partition. + * @param other Reference to an already existing Samza stream. + * @param partition Reference to an already existing Samza partition. + */ public SystemStreamPartition(SystemStream other, Partition partition) { this(other.getSystem(), other.getStream(), partition); } http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/21c07c8e/samza-api/src/main/java/org/apache/samza/task/InitableTask.java ---------------------------------------------------------------------- diff --git a/samza-api/src/main/java/org/apache/samza/task/InitableTask.java b/samza-api/src/main/java/org/apache/samza/task/InitableTask.java index c7721bb..6926f16 100644 --- a/samza-api/src/main/java/org/apache/samza/task/InitableTask.java +++ b/samza-api/src/main/java/org/apache/samza/task/InitableTask.java @@ -21,6 +21,16 @@ package org.apache.samza.task; import org.apache.samza.config.Config; +/** + * Used as an interface for user processing StreamTasks that need to have specific functionality performed as their StreamTasks + * are instantiated by TaskRunner. + */ public interface InitableTask { + /** + * Called by TaskRunner each time an implementing task is created. + * @param config Allows accessing of fields in the configuration files that this StreamTask is specified in. + * @param context Allows accessing of contextual data of this StreamTask. + * @throws Exception Any exception types encountered during the execution of the processing task. + */ void init(Config config, TaskContext context) throws Exception; } http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/21c07c8e/samza-api/src/main/java/org/apache/samza/task/MessageCollector.java ---------------------------------------------------------------------- diff --git a/samza-api/src/main/java/org/apache/samza/task/MessageCollector.java b/samza-api/src/main/java/org/apache/samza/task/MessageCollector.java index 1755529..0da816e 100644 --- a/samza-api/src/main/java/org/apache/samza/task/MessageCollector.java +++ b/samza-api/src/main/java/org/apache/samza/task/MessageCollector.java @@ -21,6 +21,13 @@ package org.apache.samza.task; import org.apache.samza.system.OutgoingMessageEnvelope; +/** + * Used as an interface for the means of sending message envelopes. + */ public interface MessageCollector { + /** + * Sends message envelope out onto specified stream. + * @param envelope Self contained envelope containing message, key and specified stream to be sent to. + */ void send(OutgoingMessageEnvelope envelope); } http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/21c07c8e/samza-api/src/main/java/org/apache/samza/task/StreamTask.java ---------------------------------------------------------------------- diff --git a/samza-api/src/main/java/org/apache/samza/task/StreamTask.java b/samza-api/src/main/java/org/apache/samza/task/StreamTask.java index 04b12c2..d552514 100644 --- a/samza-api/src/main/java/org/apache/samza/task/StreamTask.java +++ b/samza-api/src/main/java/org/apache/samza/task/StreamTask.java @@ -21,6 +21,16 @@ package org.apache.samza.task; import org.apache.samza.system.IncomingMessageEnvelope; +/** + * Used as a standard interface for all user processing tasks. Receives messages from a partition of a specified input stream. + */ public interface StreamTask { + /** + * Called once for each message that this StreamTask receives. + * @param envelope Contains the received deserialized message and key, and also information regarding the stream and partition of which the message was received from. + * @param collector Contains the means of sending message envelopes to the output stream. + * @param coordinator Manages execution of tasks. + * @throws Exception Any exception types encountered during the execution of the processing task. + */ void process(IncomingMessageEnvelope envelope, MessageCollector collector, TaskCoordinator coordinator) throws Exception; } http://git-wip-us.apache.org/repos/asf/incubator-samza/blob/21c07c8e/samza-api/src/main/java/org/apache/samza/task/WindowableTask.java ---------------------------------------------------------------------- diff --git a/samza-api/src/main/java/org/apache/samza/task/WindowableTask.java b/samza-api/src/main/java/org/apache/samza/task/WindowableTask.java index 2155ed1..be22f24 100644 --- a/samza-api/src/main/java/org/apache/samza/task/WindowableTask.java +++ b/samza-api/src/main/java/org/apache/samza/task/WindowableTask.java @@ -19,6 +19,15 @@ package org.apache.samza.task; +/** + * Used as a standard interface to allow user processing tasks to operate on specified time intervals, or "windows". + */ public interface WindowableTask { + /** + * Called by TaskRunner for each implementing task at the end of every specified window. + * @param collector Contains the means of sending message envelopes to the output stream. + * @param coordinator Manages execution of tasks. + * @throws Exception Any exception types encountered during the execution of the processing task. + */ void window(MessageCollector collector, TaskCoordinator coordinator) throws Exception; }
