Issue #5499 - add javadoc for ByteBufferAccumulator

Signed-off-by: Lachlan Roberts <lachlan@webtide.com>

jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferAccumulator.java

@@ -26,6 +26,15 @@
 
 import org.eclipse.jetty.util.BufferUtil;
 
+/**
+ * Accumulates data into a list of ByteBuffers which can then be combined into a single buffer or written to an OutputStream.
+ * The buffer list automatically grows as data is written to it, the buffers are taken from the
+ * supplied {@link ByteBufferPool} or freshly allocated if one is not supplied.
+ *
+ * The method {@link #ensureBuffer(int, int)} is used to write directly to the last buffer stored in the buffer list,
+ * if there is less than a certain amount of space available in that buffer then a new one will be allocated and returned instead.
+ * @see #ensureBuffer(int, int)
+ */
 public class ByteBufferAccumulator implements AutoCloseable
 {
     private final List<ByteBuffer> _buffers = new ArrayList<>();
@@ -49,6 +58,17 @@ public int getLength()
         return length;
     }
 
+    public ByteBufferPool getByteBufferPool()
+    {
+        return _bufferPool;
+    }
+
+    /**
+     * Get the last buffer of the accumulator, this can be written to directly to avoid copying into the accumulator.
+     * @param minSize the smallest amount of remaining space before a new buffer is allocated.
+     * @param minAllocationSize new buffers will be allocated to have at least this size.
+     * @return a buffer with at least {@code minSize} space to write into.
+     */
     public ByteBuffer ensureBuffer(int minSize, int minAllocationSize)
     {
         ByteBuffer buffer = _buffers.isEmpty() ? BufferUtil.EMPTY_BUFFER : _buffers.get(_buffers.size() - 1);
@@ -77,6 +97,12 @@ public void copyBuffer(ByteBuffer buffer)
         }
     }
 
+    /**
+     * Take the combined buffer containing all content written to the accumulator.
+     * The caller is responsible for releasing this {@link ByteBuffer} back into the {@link ByteBufferPool}.
+     * @return a buffer containing all content written to the accumulator.
+     * @see #toByteBuffer()
+     */
     public ByteBuffer takeByteBuffer()
     {
         ByteBuffer combinedBuffer;
@@ -98,13 +124,24 @@ public ByteBuffer takeByteBuffer()
         return combinedBuffer;
     }
 
+    /**
+     * Take the combined buffer containing all content written to the accumulator.
+     * The returned buffer is still contained within the accumulator and will be released back to the {@link ByteBufferPool}
+     * when the accumulator is closed.
+     * @return a buffer containing all content written to the accumulator.
+     * @see #takeByteBuffer()
+     * @see #close()
+     */
     public ByteBuffer toByteBuffer()
     {
         ByteBuffer combinedBuffer = takeByteBuffer();
         _buffers.add(combinedBuffer);
         return combinedBuffer;
     }
 
+    /**
+     * @return a newly allocated byte array containing all content written into the accumulator.
+     */
     public byte[] toByteArray()
     {
         int length = getLength();

jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferOutputStream2.java

@@ -44,23 +44,34 @@ public ByteBufferOutputStream2(ByteBufferPool bufferPool)
         _accumulator = new ByteBufferAccumulator((bufferPool == null) ? new NullByteBufferPool() : bufferPool);
     }
 
+    public ByteBufferPool getByteBufferPool()
+    {
+        return _accumulator.getByteBufferPool();
+    }
+
+    /**
+     * Take the combined buffer containing all content written to the OutputStream.
+     * The caller is responsible for releasing this {@link ByteBuffer} back into the {@link ByteBufferPool}.
+     * @return a buffer containing all content written to the OutputStream.
+     */
     public ByteBuffer takeByteBuffer()
     {
         return _accumulator.takeByteBuffer();
     }
 
     /**
-     * Get an aggregated content written to the OutputStream in a ByteBuffer.
-     * @return the content in a ByteBuffer.
+     * Take the combined buffer containing all content written to the OutputStream.
+     * The returned buffer is still contained within the OutputStream and will be released back to the {@link ByteBufferPool}
+     * when the OutputStream is closed.
+     * @return a buffer containing all content written to the OutputStream.
      */
     public ByteBuffer toByteBuffer()
     {
         return _accumulator.toByteBuffer();
     }
 
     /**
-     * Get an aggregated content written to the OutputStream in a byte array.
-     * @return the content in a byte array.
+     * @return a newly allocated byte array containing all content written into the OutputStream.
      */
     public byte[] toByteArray()
     {