ByteArrayBuilder
Date: 2016-12-03

com.fasterxml.jackson.core.util

## Class ByteArrayBuilder

- java.lang.Object
- - java.io.OutputStream
  - - com.fasterxml.jackson.core.util.ByteArrayBuilder

- All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

      public final class ByteArrayBuilder
      extends java.io.OutputStream

  Helper class that is similar to `ByteArrayOutputStream` in usage, but more geared to Jackson use cases internally. Specific changes include segment storage (no need to have linear backing buffer, can avoid reallocations, copying), as well API not based on `OutputStream`. In short, a very much specialized builder object.

  Also implements `OutputStream` to allow efficient aggregation of output content as a byte array, similar to how `ByteArrayOutputStream` works, but somewhat more efficiently for many use cases.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte[]` | `NO_BYTES`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ByteArrayBuilder()`
    `ByteArrayBuilder(BufferRecycler br)`
    `ByteArrayBuilder(BufferRecycler br, int firstBlockSize)`
    `ByteArrayBuilder(int firstBlockSize)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `append(int i)`
    `void` | `appendThreeBytes(int b24)`
    `void` | `appendTwoBytes(int b16)`
    `void` | `close()`
    `byte[]` | `completeAndCoalesce(int lastBlockLength)` Method that will complete "manual" output process, coalesce content (if necessary) and return results as a contiguous buffer.
    `byte[]` | `finishCurrentSegment()` Method called when the current segment buffer is full; will append to current contents, allocate a new segment buffer and return it
    `void` | `flush()`
    `byte[]` | `getCurrentSegment()`
    `int` | `getCurrentSegmentLength()`
    `void` | `release()` Clean up method to call to release all buffers this object may be using.
    `void` | `reset()`
    `byte[]` | `resetAndGetFirstSegment()` Method called when starting "manual" output: will clear out current state and return the first segment buffer to fill
    `void` | `setCurrentSegmentLength(int len)`
    `byte[]` | `toByteArray()` Method called when results are finalized and we can get the full aggregated result buffer to return to the caller
    `void` | `write(byte[] b)`
    `void` | `write(byte[] b, int off, int len)`
    `void` | `write(int b)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### NO_BYTES

          public static final byte[] NO_BYTES

  - ### Constructor Detail

    - #### ByteArrayBuilder

          public ByteArrayBuilder()

    - #### ByteArrayBuilder

          public ByteArrayBuilder(BufferRecycler br)

    - #### ByteArrayBuilder

          public ByteArrayBuilder(int firstBlockSize)

    - #### ByteArrayBuilder

          public ByteArrayBuilder(BufferRecycler br,
                          int firstBlockSize)

  - ### Method Detail

    - #### reset

          public void reset()

    - #### release

          public void release()

      Clean up method to call to release all buffers this object may be using. After calling the method, no other accessors can be used (and attempt to do so may result in an exception)

    - #### append

          public void append(int i)

    - #### appendTwoBytes

          public void appendTwoBytes(int b16)

    - #### appendThreeBytes

          public void appendThreeBytes(int b24)

    - #### toByteArray

          public byte[] toByteArray()

      Method called when results are finalized and we can get the full aggregated result buffer to return to the caller

    - #### resetAndGetFirstSegment

          public byte[] resetAndGetFirstSegment()

      Method called when starting "manual" output: will clear out current state and return the first segment buffer to fill

    - #### finishCurrentSegment

          public byte[] finishCurrentSegment()

      Method called when the current segment buffer is full; will append to current contents, allocate a new segment buffer and return it

    - #### completeAndCoalesce

          public byte[] completeAndCoalesce(int lastBlockLength)

      Method that will complete "manual" output process, coalesce content (if necessary) and return results as a contiguous buffer.
      Parameters:
        `lastBlockLength` - Amount of content in the current segment buffer.
      Returns:
        Coalesced contents

    - #### getCurrentSegment

          public byte[] getCurrentSegment()

    - #### setCurrentSegmentLength

          public void setCurrentSegmentLength(int len)

    - #### getCurrentSegmentLength

          public int getCurrentSegmentLength()

    - #### write

          public void write(byte[] b)

      Overrides:
        `write` in class `java.io.OutputStream`

    - #### write

          public void write(byte[] b,
                   int off,
                   int len)

      Overrides:
        `write` in class `java.io.OutputStream`

    - #### write

          public void write(int b)

      Specified by:
        `write` in class `java.io.OutputStream`

    - #### close

          public void close()

      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.OutputStream`

    - #### flush

          public void flush()

      Specified by:
        `flush` in interface `java.io.Flushable`
      Overrides:
        `flush` in class `java.io.OutputStream`