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

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

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

void	clear() Clear the buffer and reset size and write position
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.
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

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The default initial buffer size if nothing is specified

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

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