Clarify the purpose of ObjectInserter.buffer()

Recently Robin tried to increase the size of the buffer used by
ObjectInserter to fix a bug in the InputStream that handles AutoCRLF.
The purpose of this buffer is NOT to make a random InputStream work
correctly by passing it a larger buffer during read(byte[],int,int).

Clarify the Javadoc on the buffer() method to reduce the risk
someone tries to abuse it again.

While we are here, modify the method to load the field into a local
variable before returning. This should cut down 1 field load during
the common case of the buffer being already allocated.

Change-Id: Ic6898530d10fcd7e59f90397117a4a0d97e1f031
Signed-off-by: Chris Aniszczyk <zx@twitter.com>

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java
index 0355e56f5fc6bfeb8b5bbece1e9feca348cc967f..69b1e237e43ce3849a4b1ad8683489527589e335 100644 (file)
--- a/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/lib/ObjectInserter.java
@@ -102,11 +102,35 @@ public abstract class ObjectInserter {
                digest = Constants.newMessageDigest();
        }
 
-       /** @return a temporary byte array for use by the caller. */
+       /**
+        * Obtain a temporary buffer for use by the ObjectInserter or its subclass.
+        * <p>
+        * This buffer is supplied by the ObjectInserter base class to itself and
+        * its subclasses for the purposes of pulling data from a supplied
+        * InputStream, passing it through a Deflater, or formatting the canonical
+        * format of a small object like a small tree or commit.
+        * <p>
+        * <strong>This buffer IS NOT for translation such as auto-CRLF or content
+        * filtering and must not be used for such purposes.</strong>
+        * <p>
+        * The returned buffer is small, around a few KiBs, and the size may change
+        * between versions of JGit. Callers using this buffer must always check the
+        * length of the returned array to ascertain how much space was provided.
+        * <p>
+        * There is a single buffer for each ObjectInserter, repeated calls to this
+        * method will (usually) always return the same buffer. If the caller needs
+        * more than one buffer, or needs a buffer of a larger size, it must manage
+        * that buffer on its own.
+        * <p>
+        * The buffer is usually on first demand for a buffer.
+        *
+        * @return a temporary byte array for use by the caller.
+        */
        protected byte[] buffer() {
-               if (tempBuffer == null)
-                       tempBuffer = new byte[8192];
-               return tempBuffer;
+               byte[] b = tempBuffer;
+               if (b == null)
+                       tempBuffer = b = new byte[8192];
+               return b;
        }
 
        /** @return digest to help compute an ObjectId */