From e7bed39239e6e4b8309803a14fa0702380d65bd9 Mon Sep 17 00:00:00 2001
From: Lachlan Roberts <lachlan@webtide.com>
Date: Fri, 13 Nov 2020 09:56:32 +1100
Subject: [PATCH] Issue #5499 - add javadoc for ByteBufferAccumulator

Signed-off-by: Lachlan Roberts <lachlan@webtide.com>
---
 .../jetty/io/ByteBufferAccumulator.java       | 37 +++++++++++++++++++
 .../jetty/io/ByteBufferOutputStream2.java     | 19 ++++++++--
 2 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferAccumulator.java b/jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferAccumulator.java
index 569ac9727bff..ab551e5e1f6c 100644
--- a/jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferAccumulator.java
+++ b/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,6 +124,14 @@ 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();
@@ -105,6 +139,9 @@ public ByteBuffer toByteBuffer()
         return combinedBuffer;
     }
 
+    /**
+     * @return a newly allocated byte array containing all content written into the accumulator.
+     */
     public byte[] toByteArray()
     {
         int length = getLength();
diff --git a/jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferOutputStream2.java b/jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferOutputStream2.java
index 7801063c196e..2ce77fab6459 100644
--- a/jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferOutputStream2.java
+++ b/jetty-io/src/main/java/org/eclipse/jetty/io/ByteBufferOutputStream2.java
@@ -44,14 +44,26 @@ 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()
     {
@@ -59,8 +71,7 @@ public ByteBuffer 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()
     {