update output collector javadocs

Nathan Marz · Nathan Marz · commit a942da607265 · 2012-04-28T23:04:57.000-07:00
diff --git a/src/jvm/backtype/storm/spout/SpoutOutputCollector.java b/src/jvm/backtype/storm/spout/SpoutOutputCollector.java
@@ -23,7 +23,8 @@ public SpoutOutputCollector(ISpoutOutputCollector delegate) {
      * When Storm detects that this tuple has been fully processed, or has failed
      * to be fully processed, the spout will receive an ack or fail callback respectively
      * with the messageId as long as the messageId was not null. If the messageId was null,
-     * Storm will not track the tuple and no callback will be received.
+     * Storm will not track the tuple and no callback will be received. The emitted values must be 
+     * immutable.
      *
      * @return the list of task ids that this tuple was sent to
      */
@@ -36,7 +37,8 @@ public List<Integer> emit(String streamId, List<Object> tuple, Object messageId)
      * When Storm detects that this tuple has been fully processed, or has failed
      * to be fully processed, the spout will receive an ack or fail callback respectively
      * with the messageId as long as the messageId was not null. If the messageId was null,
-     * Storm will not track the tuple and no callback will be received.
+     * Storm will not track the tuple and no callback will be received. The emitted values must be 
+     * immutable.
      *
      * @return the list of task ids that this tuple was sent to
      */
@@ -46,15 +48,17 @@ public List<Integer> emit(List<Object> tuple, Object messageId) {
 
     /**
      * Emits a tuple to the default output stream with a null message id. Storm will
-     * not track this message so ack and fail will never be called for this tuple.
+     * not track this message so ack and fail will never be called for this tuple. The
+     * emitted values must be immutable.
      */
     public List<Integer> emit(List<Object> tuple) {
         return emit(tuple, null);
     }
 
     /**
      * Emits a tuple to the specified output stream with a null message id. Storm will
-     * not track this message so ack and fail will never be called for this tuple.
+     * not track this message so ack and fail will never be called for this tuple. The
+     * emitted values must be immutable.
      */
     public List<Integer> emit(String streamId, List<Object> tuple) {
         return emit(streamId, tuple, null);
@@ -63,7 +67,8 @@ public List<Integer> emit(String streamId, List<Object> tuple) {
     /**
      * Emits a tuple to the specified task on the specified output stream. This output
      * stream must have been declared as a direct stream, and the specified task must
-     * use a direct grouping on this stream to receive the message. 
+     * use a direct grouping on this stream to receive the message. The emitted values must be 
+     * immutable.
      */
     public void emitDirect(int taskId, String streamId, List<Object> tuple, Object messageId) {
         _delegate.emitDirect(taskId, streamId, tuple, messageId);
@@ -72,7 +77,8 @@ public void emitDirect(int taskId, String streamId, List<Object> tuple, Object m
     /**
      * Emits a tuple to the specified task on the default output stream. This output
      * stream must have been declared as a direct stream, and the specified task must
-     * use a direct grouping on this stream to receive the message.
+     * use a direct grouping on this stream to receive the message. The emitted values must be 
+     * immutable.
      */
     public void emitDirect(int taskId, List<Object> tuple, Object messageId) {
         emitDirect(taskId, Utils.DEFAULT_STREAM_ID, tuple, messageId);
@@ -81,7 +87,8 @@ public void emitDirect(int taskId, List<Object> tuple, Object messageId) {
     /**
      * Emits a tuple to the specified task on the specified output stream. This output
      * stream must have been declared as a direct stream, and the specified task must
-     * use a direct grouping on this stream to receive the message.
+     * use a direct grouping on this stream to receive the message. The emitted values must be 
+     * immutable.
      *
      * <p> Because no message id is specified, Storm will not track this message
      * so ack and fail will never be called for this tuple.</p>
@@ -93,7 +100,8 @@ public void emitDirect(int taskId, String streamId, List<Object> tuple) {
     /**
      * Emits a tuple to the specified task on the default output stream. This output
      * stream must have been declared as a direct stream, and the specified task must
-     * use a direct grouping on this stream to receive the message.
+     * use a direct grouping on this stream to receive the message. The emitted values must be 
+     * immutable.
      *
      * <p> Because no message id is specified, Storm will not track this message
      * so ack and fail will never be called for this tuple.</p>
diff --git a/src/jvm/backtype/storm/task/OutputCollector.java b/src/jvm/backtype/storm/task/OutputCollector.java
@@ -20,7 +20,8 @@ public OutputCollector(IOutputCollector delegate) {
     }
     
     /**
-     * Emits a new tuple to a specific stream with a single anchor.
+     * Emits a new tuple to a specific stream with a single anchor. The emitted values must be 
+     * immutable.
      *
      * @param streamId the stream to emit to
      * @param anchor the tuple to anchor to
@@ -34,7 +35,8 @@ public List<Integer> emit(String streamId, Tuple anchor, List<Object> tuple) {
     /**
      * Emits a new unanchored tuple to the specified stream. Because it's unanchored,
      * if a failure happens downstream, this new tuple won't affect whether any
-     * spout tuples are considered failed or not.
+     * spout tuples are considered failed or not. The emitted values must be 
+     * immutable.
      * 
      * @param streamId the stream to emit to
      * @param tuple the new output tuple from this bolt
@@ -45,7 +47,8 @@ public List<Integer> emit(String streamId, List<Object> tuple) {
     }
 
     /**
-     * Emits a new tuple to the default stream anchored on a group of input tuples.
+     * Emits a new tuple to the default stream anchored on a group of input tuples. The emitted
+     * values must be immutable.
      * 
      * @param anchors the tuples to anchor to
      * @param tuple the new output tuple from this bolt
@@ -57,7 +60,8 @@ public List<Integer> emit(Collection<Tuple> anchors, List<Object> tuple) {
 
 
     /**
-     * Emits a new tuple to the default stream anchored on a single tuple.
+     * Emits a new tuple to the default stream anchored on a single tuple. The emitted values must be 
+     * immutable.
      * 
      * @param anchor the tuple to anchor to
      * @param tuple the new output tuple from this bolt
@@ -70,7 +74,8 @@ public List<Integer> emit(Tuple anchor, List<Object> tuple) {
     /**
      * Emits a new unanchored tuple to the default stream. Beacuse it's unanchored,
      * if a failure happens downstream, this new tuple won't affect whether any
-     * spout tuples are considered failed or not.
+     * spout tuples are considered failed or not. The emitted values must be 
+     * immutable.
      *
      * @param tuple the new output tuple from this bolt
      * @return the list of task ids that this new tuple was sent to
@@ -84,7 +89,8 @@ public List<Integer> emit(List<Object> tuple) {
      * If the target bolt does not subscribe to this bolt using a direct grouping,
      * the tuple will not be sent. If the specified output stream is not declared
      * as direct, or the target bolt subscribes with a non-direct grouping,
-     * an error will occur at runtime.
+     * an error will occur at runtime. The emitted values must be 
+     * immutable.
      *
      * @param taskId the taskId to send the new tuple to
      * @param streamId the stream to send the tuple on. It must be declared as a direct stream in the topology definition.
@@ -102,6 +108,7 @@ public void emitDirect(int taskId, String streamId, Tuple anchor, List<Object> t
      * as direct, or the target bolt subscribes with a non-direct grouping,
      * an error will occur at runtime. Note that this method does not use anchors,
      * so downstream failures won't affect the failure status of any spout tuples.
+     * The emitted values must be immutable.
      *
      * @param taskId the taskId to send the new tuple to
      * @param streamId the stream to send the tuple on. It must be declared as a direct stream in the topology definition.
@@ -116,7 +123,8 @@ public void emitDirect(int taskId, String streamId, List<Object> tuple) {
      * If the target bolt does not subscribe to this bolt using a direct grouping,
      * the tuple will not be sent. If the specified output stream is not declared
      * as direct, or the target bolt subscribes with a non-direct grouping,
-     * an error will occur at runtime.
+     * an error will occur at runtime. The emitted values must be 
+     * immutable.
      *
      * <p>The default stream must be declared as direct in the topology definition.
      * See OutputDeclarer#declare for how this is done when defining topologies
@@ -135,7 +143,8 @@ public void emitDirect(int taskId, Collection<Tuple> anchors, List<Object> tuple
      * If the target bolt does not subscribe to this bolt using a direct grouping,
      * the tuple will not be sent. If the specified output stream is not declared
      * as direct, or the target bolt subscribes with a non-direct grouping,
-     * an error will occur at runtime.
+     * an error will occur at runtime. The emitted values must be 
+     * immutable.
      *
      * <p>The default stream must be declared as direct in the topology definition.
      * See OutputDeclarer#declare for how this is done when defining topologies
@@ -155,7 +164,8 @@ public void emitDirect(int taskId, Tuple anchor, List<Object> tuple) {
      * If the target bolt does not subscribe to this bolt using a direct grouping,
      * the tuple will not be sent. If the specified output stream is not declared
      * as direct, or the target bolt subscribes with a non-direct grouping,
-     * an error will occur at runtime.
+     * an error will occur at runtime. The emitted values must be 
+     * immutable.
      *
      * <p>The default stream must be declared as direct in the topology definition.
      * See OutputDeclarer#declare for how this is done when defining topologies
