de.undercouch.bson4jackson.io

Class DynamicOutputBuffer

java.lang.Object

de.undercouch.bson4jackson.io.DynamicOutputBuffer

public class DynamicOutputBuffer
extends java.lang.Object

A random-access buffer that resizes itself. This buffer differentiates from ByteArrayOutputStream in the following points:

• It allows specifying the byte order.
• It assigns several internal buffers instead of one and therefore saves garbage collection cycles.
• It is able to flush some of its internal buffers to an output stream or to a writable channel.

The buffer has an initial size. This is also the size of each internal buffer, so if a new buffer has to be allocated it will take exactly that many bytes.

By calling flushTo(OutputStream) or flushTo(WritableByteChannel) some of this buffer's internal buffers are flushed and then deallocated. The buffer maintains an internal counter for all flushed buffers. This allows the writeTo(OutputStream) and writeTo(WritableByteChannel) methods to only write non-flushed buffers. So, this class can be used for streaming by flushing internal buffers from time to time and at the end writing the rest:

 ...
 buf.flushTo(out);
 ...
 buf.flushTo(out);
 ...
 buf.flushTo(out);
 ...
 buf.writeTo(out);

If flushing is never used a single call to one of the writeTo methods is enough to write the whole buffer.

Once the buffer has been written to an output stream or channel, putting elements into it is not possible anymore and will lead to an IndexOutOfBoundsException.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<java.nio.ByteBuffer>	_buffers A linked list of internal buffers
protected int	_bufferSize The size of each internal buffer (also the initial buffer size)
protected java.util.Queue<java.nio.ByteBuffer>	_buffersToReuse A queue of buffers that have already been flushed and are free to reuse.
protected int	_flushPosition The position of the first byte that has not been already flushed.
protected java.nio.ByteOrder	_order The byte order of this buffer
protected int	_position The current write position
protected int	_reuseBuffersCount The number of buffers to reuse
protected int	_size The current buffer size (changes dynamically)
protected java.nio.charset.Charset	_utf8 The character set used in putUTF8(String).
protected java.nio.charset.CharsetEncoder	_utf8Encoder The encoder used in putUTF8(String).
protected static StaticBuffers.Key	BUFFER_KEY A unique key to make the first buffer re-usable
static int	DEFAULT_BUFFER_SIZE The default initial buffer size if nothing is specified
static java.nio.ByteOrder	DEFAULT_BYTE_ORDER The default byte order if nothing is specified

Constructor Summary

Constructors

Constructor and Description
DynamicOutputBuffer() Creates a dynamic buffer with BIG_ENDIAN byte order and a default initial buffer size of DEFAULT_BUFFER_SIZE bytes.
DynamicOutputBuffer(java.nio.ByteOrder order) Creates a dynamic buffer with the given byte order and a default initial buffer size of DEFAULT_BUFFER_SIZE bytes.
DynamicOutputBuffer(java.nio.ByteOrder order, int initialSize) Creates a dynamic buffer with the given byte order and the given initial buffer size.
DynamicOutputBuffer(int initialSize) Creates a dynamic buffer with BIG_ENDIAN byte order and the given initial buffer size.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	adaptSize(int size) Adapts the buffer size so it is at least equal to the given number of bytes.
protected java.nio.ByteBuffer	addNewBuffer() Adds a new buffer to the list of internal buffers
protected java.nio.ByteBuffer	allocateBuffer() Allocates a new buffer or attempts to reuse an existing one.
void	clear() Clear the buffer and reset size and write position
protected void	deallocateBuffer(int n) Removes a buffer from the list of internal buffers and saves it for reuse if this feature is enabled.
void	flushTo(java.io.OutputStream out) Tries to copy as much bytes as possible from this buffer to the given channel.
void	flushTo(java.nio.channels.WritableByteChannel out) Tries to copy as much bytes as possible from this buffer to the given channel.
protected java.nio.ByteBuffer	getBuffer(int position) Gets the buffer that holds the byte at the given absolute position.
protected java.nio.charset.Charset	getUTF8Charset()
protected java.nio.charset.CharsetEncoder	getUTF8Encoder()
void	putByte(byte b) Puts a byte into the buffer at the current write position and increases the write position accordingly.
void	putByte(int pos, byte b) Puts a byte into the buffer at the given position.
void	putBytes(byte... bs) Puts several bytes into the buffer at the given position and increases the write position accordingly.
void	putBytes(int pos, byte... bs) Puts several bytes into the buffer at the given position.
void	putDouble(double d) Puts a 64-bit floating point number into the buffer at the current write position and increases the write position accordingly.
void	putDouble(int pos, double d) Puts a 64-bit floating point number into the buffer at the given position.
void	putFloat(float f) Puts a 32-bit floating point number into the buffer at the current write position and increases the write position accordingly.
void	putFloat(int pos, float f) Puts a 32-bit floating point number into the buffer at the given position.
void	putInt(int i) Puts a 32-bit integer into the buffer at the current write position and increases write position accordingly.
void	putInt(int pos, int i) Puts a 32-bit integer into the buffer at the given position.
void	putLong(int pos, long l) Puts a 64-bit integer into the buffer at the given position.
void	putLong(long l) Puts a 64-bit integer into the buffer at the current write position and increases the write position accordingly.
void	putString(java.lang.CharSequence s) Puts a character sequence into the buffer at the current write position and increases the write position accordingly.
void	putString(int pos, java.lang.CharSequence s) Puts a character sequence into the buffer at the given position.
int	putUTF8(int pos, java.lang.String s) Puts the given string as UTF-8 into the buffer at the given position.
int	putUTF8(java.lang.String s) Encodes the given string as UTF-8, puts it into the buffer and increases the write position accordingly.
void	setReuseBuffersCount(int count) Sets the number of buffers to save for reuse after they have been invalidated by flushTo(OutputStream) or flushTo(WritableByteChannel).
int	size()
void	writeTo(java.io.OutputStream out) Writes all non-flushed internal buffers to the given output stream.
void	writeTo(java.nio.channels.WritableByteChannel out) Writes all non-flushed internal buffers to the given channel.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BYTE_ORDER

public static final java.nio.ByteOrder DEFAULT_BYTE_ORDER

The default byte order if nothing is specified

BUFFER_KEY

protected static final StaticBuffers.Key BUFFER_KEY

A unique key to make the first buffer re-usable

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The default initial buffer size if nothing is specified

_order

protected final java.nio.ByteOrder _order

The byte order of this buffer

_bufferSize

protected final int _bufferSize

The size of each internal buffer (also the initial buffer size)

_position

protected int _position

The current write position

_flushPosition

protected int _flushPosition

The position of the first byte that has not been already flushed. Any attempt to put something into the buffer at a position before this first byte is invalid and causes a IndexOutOfBoundsException to be thrown.

_size

protected int _size

The current buffer size (changes dynamically)

_buffers

protected java.util.List<java.nio.ByteBuffer> _buffers

A linked list of internal buffers

_utf8

protected java.nio.charset.Charset _utf8

The character set used in putUTF8(String). Will be created lazily in getUTF8Charset()

_utf8Encoder

protected java.nio.charset.CharsetEncoder _utf8Encoder

The encoder used in putUTF8(String). Will be created lazily in getUTF8Encoder()

_buffersToReuse

protected java.util.Queue<java.nio.ByteBuffer> _buffersToReuse

A queue of buffers that have already been flushed and are free to reuse.

See Also:

_reuseBuffersCount

_reuseBuffersCount

protected int _reuseBuffersCount

The number of buffers to reuse

See Also:

_buffersToReuse

Constructor Detail

DynamicOutputBuffer

public DynamicOutputBuffer()

Creates a dynamic buffer with BIG_ENDIAN byte order and a default initial buffer size of DEFAULT_BUFFER_SIZE bytes.

DynamicOutputBuffer

public DynamicOutputBuffer(int initialSize)

Creates a dynamic buffer with BIG_ENDIAN byte order and the given initial buffer size.

Parameters:

initialSize - the initial buffer size

DynamicOutputBuffer

public DynamicOutputBuffer(java.nio.ByteOrder order)

Creates a dynamic buffer with the given byte order and a default initial buffer size of DEFAULT_BUFFER_SIZE bytes.

Parameters:

order - the byte order

DynamicOutputBuffer

public DynamicOutputBuffer(java.nio.ByteOrder order,
                   int initialSize)

Creates a dynamic buffer with the given byte order and the given initial buffer size.

Parameters:

order - the byte order

initialSize - the initial buffer size

Method Detail

setReuseBuffersCount

public void setReuseBuffersCount(int count)

Sets the number of buffers to save for reuse after they have been invalidated by flushTo(OutputStream) or flushTo(WritableByteChannel). Invalidated buffers will be saved in an internal queue. When the buffer needs a new internal buffer, it first attempts to reuse an existing one before allocating a new one.

Parameters:

count - the number of buffers to save for reuse

allocateBuffer

protected java.nio.ByteBuffer allocateBuffer()

Allocates a new buffer or attempts to reuse an existing one.

Returns:

a new buffer with the current buffer size and the current byte order

deallocateBuffer

protected void deallocateBuffer(int n)

Removes a buffer from the list of internal buffers and saves it for reuse if this feature is enabled.

Parameters:

n - the number of the buffer to remove

addNewBuffer

protected java.nio.ByteBuffer addNewBuffer()

Adds a new buffer to the list of internal buffers

Returns:

the new buffer

getBuffer

protected java.nio.ByteBuffer getBuffer(int position)

Gets the buffer that holds the byte at the given absolute position. Automatically adds new internal buffers if the position lies outside the current range of all internal buffers.

Parameters:

position - the position

Returns:

the buffer at the requested position

adaptSize

protected void adaptSize(int size)

Adapts the buffer size so it is at least equal to the given number of bytes. This method does not add new internal buffers.

Parameters:

size - the minimum buffer size

getUTF8Charset

protected java.nio.charset.Charset getUTF8Charset()

Returns:

the lazily created UTF-8 character set

getUTF8Encoder

protected java.nio.charset.CharsetEncoder getUTF8Encoder()

Returns:

the lazily created UTF-8 encoder

size

public int size()

Returns:

the current buffer size (changes dynamically)

clear

public void clear()

Clear the buffer and reset size and write position

putByte

public void putByte(byte b)

Puts a byte into the buffer at the current write position and increases the write position accordingly.

Parameters:

b - the byte to put

putBytes

public void putBytes(byte... bs)

Puts several bytes into the buffer at the given position and increases the write position accordingly.

Parameters:

bs - an array of bytes to put

putByte

public void putByte(int pos,
           byte b)

Puts a byte into the buffer at the given position. Does not increase the write position.

Parameters:

pos - the position where to put the byte

b - the byte to put

putBytes

public void putBytes(int pos,
            byte... bs)

Puts several bytes into the buffer at the given position. Does not increase the write position.

Parameters:

pos - the position where to put the bytes

bs - an array of bytes to put

putInt

public void putInt(int i)

Puts a 32-bit integer into the buffer at the current write position and increases write position accordingly.

Parameters:

i - the integer to put

putInt

public void putInt(int pos,
          int i)

Puts a 32-bit integer into the buffer at the given position. Does not increase the write position.

Parameters:

pos - the position where to put the integer

i - the integer to put

putLong

public void putLong(long l)

Puts a 64-bit integer into the buffer at the current write position and increases the write position accordingly.

Parameters:

l - the 64-bit integer to put

putLong

public void putLong(int pos,
           long l)

Puts a 64-bit integer into the buffer at the given position. Does not increase the write position.

Parameters:

pos - the position where to put the integer

l - the 64-bit integer to put

putFloat

public void putFloat(float f)

Puts a 32-bit floating point number into the buffer at the current write position and increases the write position accordingly.

Parameters:

f - the float to put

putFloat

public void putFloat(int pos,
            float f)

Puts a 32-bit floating point number into the buffer at the given position. Does not increase the write position.

Parameters:

pos - the position where to put the float

f - the float to put

putDouble

public void putDouble(double d)

Puts a 64-bit floating point number into the buffer at the current write position and increases the write position accordingly.

Parameters:

d - the double to put

putDouble

public void putDouble(int pos,
             double d)

Puts a 64-bit floating point number into the buffer at the given position. Does not increase the write position.

Parameters:

pos - the position where to put the double

d - the double to put

putString

public void putString(java.lang.CharSequence s)

Puts a character sequence into the buffer at the current write position and increases the write position accordingly.

Parameters:

s - the character sequence to put

putString

public void putString(int pos,
             java.lang.CharSequence s)

Puts a character sequence into the buffer at the given position. Does not increase the write position.

Parameters:

pos - the position where to put the character sequence

s - the character sequence to put

putUTF8

public int putUTF8(java.lang.String s)

Encodes the given string as UTF-8, puts it into the buffer and increases the write position accordingly.

Parameters:

s - the string to put

Returns:

the number of UTF-8 bytes put

putUTF8

public int putUTF8(int pos,
          java.lang.String s)

Puts the given string as UTF-8 into the buffer at the given position. This method does not increase the write position.

Parameters:

pos - the position where to put the string

s - the string to put

Returns:

the number of UTF-8 bytes put

flushTo

public void flushTo(java.io.OutputStream out)
             throws java.io.IOException

Tries to copy as much bytes as possible from this buffer to the given channel. See flushTo(WritableByteChannel) for further information.

Parameters:

out - the output stream to write to

Throws:

java.io.IOException - if the buffer could not be flushed

flushTo

public void flushTo(java.nio.channels.WritableByteChannel out)
             throws java.io.IOException

Tries to copy as much bytes as possible from this buffer to the given channel. This method always copies whole internal buffers and deallocates them afterwards. It does not deallocate the buffer the write position is currently pointing to nor does it deallocate buffers following the write position. The method increases an internal pointer so consecutive calls also copy consecutive bytes.

Parameters:

out - the channel to write to

Throws:

java.io.IOException - if the buffer could not be flushed

writeTo

public void writeTo(java.io.OutputStream out)
             throws java.io.IOException

Writes all non-flushed internal buffers to the given output stream. If flushTo(OutputStream) has not been called before, this method writes the whole buffer to the output stream.

Parameters:

out - the output stream to write to

Throws:

java.io.IOException - if the buffer could not be written

writeTo

public void writeTo(java.nio.channels.WritableByteChannel out)
             throws java.io.IOException

Writes all non-flushed internal buffers to the given channel. If flushTo(WritableByteChannel) has not been called before, this method writes the whole buffer to the channel.

Parameters:

out - the channel to write to

Throws:

java.io.IOException - if the buffer could not be written