svn commit: r1769818 - /jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentWriter.java

[md...@apache.org]

Author: mduerig
Date: Tue Nov 15 12:55:35 2016
New Revision: 1769818

URL: http://svn.apache.org/viewvc?rev=1769818&view=rev
Log:
@trivial: clarify Javadoc of SegmentWriter.writeNode()

Modified:
    jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentWriter.java

Modified: jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentWriter.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentWriter.java?rev=1769818&r1=1769817&r2=1769818&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentWriter.java (original)
+++ jackrabbit/oak/trunk/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentWriter.java Tue Nov 15 12:55:35 2016
@@ -332,7 +332,14 @@ public class SegmentWriter {
     }
 
     /**
-     * Write a node state
+     * Write a node state.
+     * <p>
+     * <em>Note:</em> the returned {@code SegmentNodeState} instance is bound to this
+     * {@code SegmentWriter} instance. That is, future calls to {@code #builder()}
+     * return a {@code NodeBuilder} that is also bound to the same {@code SegmentWriter}
+     * instance and uses it for writing any changes. This might not always be desired
+     * and callers of this method need to take care not to proliferate this writer
+     * through the returned node states beyond the intended bounds.
      * @param state node state to write
      * @return segment node state equal to {@code state}
      * @throws IOException
@@ -349,7 +356,14 @@ public class SegmentWriter {
     }
 
     /**
-     * Write a node state, unless cancelled using a dedicated write operation handler.
+     * Write a node state, unless cancelled.
+     * <p>
+     * <em>Note:</em> the returned {@code SegmentNodeState} instance is bound to this
+     * {@code SegmentWriter} instance. That is, future calls to {@code #builder()}
+     * return a {@code NodeBuilder} that is also bound to the same {@code SegmentWriter}
+     * instance and uses it for writing any changes. This might not always be desired
+     * and callers of this method need to take care not to proliferate this writer
+     * through the returned node states beyond the intended bounds.
      * @param state   node state to write
      * @param cancel  supplier to signal cancellation of this write operation
      * @return segment node state equal to {@code state} or {@code null} if cancelled.