Top Description Fields Constructors Methods
com.fasterxml.jackson.core.util

public final Class ByteArrayBuilder

extends OutputStream
implements Gettable
Class Inheritance
All Implemented Interfaces
com.fasterxml.jackson.core.util.BufferRecycler.Gettable
Imports
java.io.OutputStream, java.util.*
Helper class that is similar to java.io.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 java.io.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 java.io.ByteArrayOutputStream works, but somewhat more efficiently for many use cases.

Note

maximum size limited to Java Array maximum, 2 gigabytes: this because usage pattern is to collect content for a `byte[]` and so although theoretically this builder can aggregate more content it will not be usable as things are. Behavior may be improved if we solve the access problem.

Field Summary

Modifier and TypeField and Description
private final BufferRecycler
_bufferRecycler

private byte[]
_currBlock

private int
_currBlockPtr

private final LinkedList<byte[]>
_pastBlocks

private int
_pastLen

pack-priv static final int
DEFAULT_BLOCK_ARRAY_SIZE

private static final int
INITIAL_BLOCK_SIZE

private static final int
MAX_BLOCK_SIZE

public static final byte[]
NO_BYTES

Constructor Summary

AccessConstructor and Description
public
ByteArrayBuilder()

public
ByteArrayBuilder(BufferRecycler br)

public
ByteArrayBuilder(int firstBlockSize)

public
ByteArrayBuilder(BufferRecycler br, int firstBlockSize)

private
ByteArrayBuilder(BufferRecycler br, byte[] initialBlock, int initialLen)

Method Summary

Modifier and TypeMethod and Description
private void
_allocMore()

public void
append(int i)

public void
appendFourBytes(int b32)

public void
appendThreeBytes(int b24)

public void
appendTwoBytes(int b16)

public BufferRecycler
bufferRecycler()

Implements com.fasterxml.jackson.core.util.BufferRecycler.Gettable.bufferRecycler.

public void
close()

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Closes this output stream and releases any system resources associated with this stream.

public byte[]

Returns:

Coalesced contents
completeAndCoalesce(int
Amount of content in the current segment buffer.
lastBlockLength)

Method that will complete "manual" output process, coalesce content (if necessary) and return results as a contiguous buffer.

public byte[]

Returns:

Segment to use for writing
finishCurrentSegment()

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

public void
flush()

Overrides java.io.OutputStream.flush.

Implements java.io.Flushable.flush.

Flushes this output stream and forces any buffered output bytes to be written out.

public static ByteArrayBuilder
fromInitial(byte[] initialBlock, int length)

public byte[]

Returns:

Content in byte array
getClearAndRelease()

Method functionally same as calling: 

  byte[] bytes = toByteArray();
  release();
  return bytes;
public byte[]
getCurrentSegment()

public int
getCurrentSegmentLength()

public void
release()

Clean up method to call to release all buffers this object may be using.

public void
reset()

public byte[]

Returns:

Segment to use for writing
resetAndGetFirstSegment()

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

public void
setCurrentSegmentLength(int len)

public int

Returns:

Number of bytes aggregated so far
size()

public byte[]

Returns:

Aggregated contents as a byte[]
toByteArray()

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

public void
write(byte[]
the data.
b)

Overrides java.io.OutputStream.write.

Writes b.length bytes from the specified byte array to this output stream.

public void
write(byte[]
the data.
b, int
the start offset in the data.
off, int
the number of bytes to write.
len)

Overrides java.io.OutputStream.write.

Writes len bytes from the specified byte array starting at offset off to this output stream.

public void
write(int
the byte.
b)

Implements abstract java.io.OutputStream.write.

Writes the specified byte to this output stream.

Inherited from java.io.OutputStream:
nullOutputStream

Field Detail

_bufferRecyclerback to summary
private final BufferRecycler _bufferRecycler
_currBlockback to summary
private byte[] _currBlock
_currBlockPtrback to summary
private int _currBlockPtr
_pastBlocksback to summary
private final LinkedList<byte[]> _pastBlocks
_pastLenback to summary
private int _pastLen
DEFAULT_BLOCK_ARRAY_SIZEback to summary
pack-priv static final int DEFAULT_BLOCK_ARRAY_SIZE
INITIAL_BLOCK_SIZEback to summary
private static final int INITIAL_BLOCK_SIZE
MAX_BLOCK_SIZEback to summary
private static final int MAX_BLOCK_SIZE
NO_BYTESback to summary
public static final byte[] NO_BYTES

Constructor Detail

ByteArrayBuilderback to summary
public ByteArrayBuilder()
ByteArrayBuilderback to summary
public ByteArrayBuilder(BufferRecycler br)
ByteArrayBuilderback to summary
public ByteArrayBuilder(int firstBlockSize)
ByteArrayBuilderback to summary
public ByteArrayBuilder(BufferRecycler br, int firstBlockSize)
ByteArrayBuilderback to summary
private ByteArrayBuilder(BufferRecycler br, byte[] initialBlock, int initialLen)

Method Detail

_allocMoreback to summary
private void _allocMore()
appendback to summary
public void append(int i)
appendFourBytesback to summary
public void appendFourBytes(int b32)
appendThreeBytesback to summary
public void appendThreeBytes(int b24)
appendTwoBytesback to summary
public void appendTwoBytes(int b16)
bufferRecyclerback to summary
public BufferRecycler bufferRecycler()

Implements com.fasterxml.jackson.core.util.BufferRecycler.Gettable.bufferRecycler.

Returns:BufferRecycler

Doc from com.fasterxml.jackson.core.util.BufferRecycler.Gettable.bufferRecycler.

Buffer recycler instance object is configured with, if any; whether this can be null depends on type of object

Annotations
@Override
closeback to summary
public void close()

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Doc from java.io.OutputStream.close.

Closes this output stream and releases any system resources associated with this stream. The general contract of close is that it closes the output stream. A closed stream cannot perform output operations and cannot be reopened.

Annotations
@Override
completeAndCoalesceback to summary
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:int

Amount of content in the current segment buffer.

Returns:byte[]

Coalesced contents

finishCurrentSegmentback to summary
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

Returns:byte[]

Segment to use for writing

flushback to summary
public void flush()

Overrides java.io.OutputStream.flush.

Implements java.io.Flushable.flush.

Doc from java.io.OutputStream.flush.

Flushes this output stream and forces any buffered output bytes to be written out. The general contract of flush is that calling it is an indication that, if any bytes previously written have been buffered by the implementation of the output stream, such bytes should immediately be written to their intended destination.

If the intended destination of this stream is an abstraction provided by the underlying operating system, for example a file, then flushing the stream guarantees only that bytes previously written to the stream are passed to the operating system for writing; it does not guarantee that they are actually written to a physical device such as a disk drive.

Annotations
@Override
fromInitialback to summary
public static ByteArrayBuilder fromInitial(byte[] initialBlock, int length)
getClearAndReleaseback to summary
public byte[] getClearAndRelease()

Method functionally same as calling: 

  byte[] bytes = toByteArray();
  release();
  return bytes;
that is; aggregates output contained in the builder (if any), clear state; returns buffer(s) to BufferRecycler configured, if any, and returns output to caller.
Returns:byte[]

Content in byte array

Since
2.17
getCurrentSegmentback to summary
public byte[] getCurrentSegment()
getCurrentSegmentLengthback to summary
public int getCurrentSegmentLength()
releaseback to summary
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).

resetback to summary
public void reset()
resetAndGetFirstSegmentback to summary
public byte[] resetAndGetFirstSegment()

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

Returns:byte[]

Segment to use for writing

setCurrentSegmentLengthback to summary
public void setCurrentSegmentLength(int len)
sizeback to summary
public int size()
Returns:int

Number of bytes aggregated so far

Since
2.9
toByteArrayback to summary
public byte[] toByteArray()

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

Returns:byte[]

Aggregated contents as a byte[]

writeback to summary
public void write(byte[] b)

Overrides java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes b.length bytes from the specified byte array to this output stream. The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length).

Parameters
b:byte[]

the data.

Annotations
@Override
writeback to summary
public void write(byte[] b, int off, int len)

Overrides java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes len bytes from the specified byte array starting at offset off to this output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation.

If b is null, a NullPointerException is thrown.

If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown.

Parameters
b:byte[]

the data.

off:int

the start offset in the data.

len:int

the number of bytes to write.

Annotations
@Override
writeback to summary
public void write(int b)

Implements abstract java.io.OutputStream.write.

Doc from java.io.OutputStream.write.

Writes the specified byte to this output stream. The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored.

Parameters
b:int

the byte.

Annotations
@Override