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