svn commit: r1138710 - /cassandra/branches/cassandra-0.7/src/java/org/apache/cassandra/streaming/StreamOut.java

[jb...@apache.org]

Author: jbellis
Date: Thu Jun 23 02:14:00 2011
New Revision: 1138710

URL: http://svn.apache.org/viewvc?rev=1138710&view=rev
Log:
improve streaming comments

Modified:
    cassandra/branches/cassandra-0.7/src/java/org/apache/cassandra/streaming/StreamOut.java

Modified: cassandra/branches/cassandra-0.7/src/java/org/apache/cassandra/streaming/StreamOut.java
URL: http://svn.apache.org/viewvc/cassandra/branches/cassandra-0.7/src/java/org/apache/cassandra/streaming/StreamOut.java?rev=1138710&r1=1138709&r2=1138710&view=diff
==============================================================================
--- cassandra/branches/cassandra-0.7/src/java/org/apache/cassandra/streaming/StreamOut.java (original)
+++ cassandra/branches/cassandra-0.7/src/java/org/apache/cassandra/streaming/StreamOut.java Thu Jun 23 02:14:00 2011
@@ -42,18 +42,31 @@ import org.apache.cassandra.utils.Pair;
 /**
  * This class handles streaming data from one node to another.
  *
- * The source node is in charge of the streaming session.  It begins the stream by sending
+ * The source node [the Out side] is always in charge of the streaming session.  Streams may
+ * be initiated either directly by the source via the methods in this class,
+ * or on demand from the target (via StreamRequest).
+ *
+ * Files to stream are grouped into sessions, which can have callbacks associated
+ * with them so that (for instance) we can mark a new node a full member of the
+ * cluster after all the data it needs has been streamed.
+ *
+ * The source begins a session by sending
  * a Message with the stream bit flag in the Header turned on.  Part of that Message
  * will include a StreamHeader that includes the files that will be streamed as part
  * of that session, as well as the first file-to-be-streamed. (Combining session list
  * and first file like this is inconvenient, but not as inconvenient as the old
  * three-part send-file-list, wait-for-ack, start-first-file dance.)
  *
- * After each file, the target will send a StreamReply indicating success
+ * This is done over a separate TCP connection to avoid blocking ordinary intra-node
+ * traffic during the stream.  So there is no Handler for the main stream of data --
+ * when a connection sets the Stream bit, IncomingTcpConnection knows what to expect
+ * without any further Messages.
+ *
+ * After each file, the target node [the In side] will send a StreamReply indicating success
  * (FILE_FINISHED) or failure (FILE_RETRY).
  *
- * When all files have been successfully transferred and integrated the source will send
- * SESSION_FINISHED and the session is complete.
+ * When all files have been successfully transferred and integrated the target will
+ * send an additional SESSION_FINISHED reply and the session is complete.
  *
  * For Stream requests (for bootstrap), one subtlety is that we always have to
  * create at least one stream reply, even if the list of files is empty, otherwise the