com.allanbank.mongodb.bson.io

Class BufferingBsonOutputStream

java.lang.Object

java.io.OutputStream

java.io.FilterOutputStream

com.allanbank.mongodb.bson.io.BufferingBsonOutputStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class BufferingBsonOutputStream
extends FilterOutputStream

BufferingBsonOutputStream provides a class to write BSON documents based on the BSON specification.

Users of this class must make sure that the flushBuffer() method is called after calling any of the writeXXX() methods.

API Notice:

This class is part of the driver's API. Public and protected members will be deprecated for at least 1 non-bugfix release (version numbers are <major>.<minor>.<bugfix>) before being removed or modified.

Copyright ©:

2011-2013, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

Constructors

Constructor and Description
BufferingBsonOutputStream(OutputStream output) Creates a new BufferingBsonOutputStream.
BufferingBsonOutputStream(OutputStream output, StringEncoderCache cache) Creates a new BufferingBsonOutputStream.
BufferingBsonOutputStream(RandomAccessOutputStream output) Creates a new BufferingBsonOutputStream.

Method Summary

Methods

Modifier and Type	Method and Description
void	flushBuffer() Writes any pending data to the underlying stream.
int	getMaxCachedStringEntries() Deprecated. The cache StringEncoderCache should be controlled directory. This method will be removed after the 2.1.0 release.
int	getMaxCachedStringLength() Deprecated. The cache StringEncoderCache should be controlled directory. This method will be removed after the 2.1.0 release.
RandomAccessOutputStream	getOutput() Returns the output buffer.
long	getPosition() Returns the current position in the stream.
void	setMaxCachedStringEntries(int maxCacheEntries) Deprecated. The cache StringEncoderCache should be controlled directory. This method will be removed after the 2.1.0 release.
void	setMaxCachedStringLength(int maxlength) Deprecated. The cache StringEncoderCache should be controlled directory. This method will be removed after the 2.1.0 release.
void	write(byte[] b) Writes b.length bytes to this output stream.
void	write(byte[] b, int off, int len) Writes len bytes from the specified byte array starting at offset off to this output stream.
long	write(Document doc) Writes the Document in BSON format to the underlying stream.
void	writeByte(byte b) Writes a single byte to the output buffer.
void	writeBytes(byte[] data) Writes a sequence of bytes to the output buffer.
void	writeCString(String... strings) Writes a "Cstring" to the output buffer.
void	writeDocument(Document doc) Writes the Document in BSON format to the underlying stream.
void	writeInt(int value) Writes the integer value in little-endian byte order to the output buffer.
void	writeIntAt(long position, int value) Similar to writeInt(int) but allows a portion of the already written buffer to be re-written.
void	writeLong(long value) Write the long value in little-endian byte order to the output buffer.
void	writeString(String string) Writes a "string" to the output buffer.

Methods inherited from class java.io.FilterOutputStream

close, flush, write

Methods inherited from class java.lang.Object

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

Constructor Detail

BufferingBsonOutputStream

public BufferingBsonOutputStream(OutputStream output)

Creates a new BufferingBsonOutputStream.

Parameters:

output - The stream to write to.

BufferingBsonOutputStream

public BufferingBsonOutputStream(OutputStream output,
                         StringEncoderCache cache)

Creates a new BufferingBsonOutputStream.

Parameters:

output - The stream to write to.

cache - The cache for encoding strings.

BufferingBsonOutputStream

public BufferingBsonOutputStream(RandomAccessOutputStream output)

Creates a new BufferingBsonOutputStream.

Parameters:

output - The stream to write to.

Method Detail

flushBuffer

public void flushBuffer()
                 throws IOException

Writes any pending data to the underlying stream.

Users should call this method after calling any of the writeXXX(...) methods.

Throws:

IOException - On a failure to write to the underlying document.

getMaxCachedStringEntries

@Deprecated
public int getMaxCachedStringEntries()

Deprecated. The cache StringEncoderCache should be controlled directory. This method will be removed after the 2.1.0 release.

Returns the maximum number of strings that may have their encoded form cached.

Returns:

The maximum number of strings that may have their encoded form cached.

getMaxCachedStringLength

@Deprecated
public int getMaxCachedStringLength()

Deprecated. The cache StringEncoderCache should be controlled directory. This method will be removed after the 2.1.0 release.

Returns the maximum length for a string that the stream is allowed to cache.

Returns:

The maximum length for a string that the stream is allowed to cache.

getOutput

public RandomAccessOutputStream getOutput()

Returns the output buffer.

Returns:

The output buffer.

getPosition

public long getPosition()

Returns the current position in the stream.

Returns:

The current position in the stream.

setMaxCachedStringEntries

@Deprecated
public void setMaxCachedStringEntries(int maxCacheEntries)

Deprecated. The cache StringEncoderCache should be controlled directory. This method will be removed after the 2.1.0 release.

Sets the value of maximum number of strings that may have their encoded form cached.

Parameters:

maxCacheEntries - The new value for the maximum number of strings that may have their encoded form cached.

setMaxCachedStringLength

@Deprecated
public void setMaxCachedStringLength(int maxlength)

Deprecated. The cache StringEncoderCache should be controlled directory. This method will be removed after the 2.1.0 release.

Sets the value of length for a string that the stream is allowed to cache to the new value. This can be used to stop a single long string from pushing useful values out of the cache.

Parameters:

maxlength - The new value for the length for a string that the encoder is allowed to cache.

write

public void write(byte[] b)
           throws IOException

Writes b.length bytes to this output stream.

Calls the write(byte[]) of the underlying stream.

Overrides:

write in class FilterOutputStream

Parameters:

b - the data to be written.

Throws:

IOException - if an I/O error occurs.

See Also:

FilterOutputStream.write(byte[], int, int)

write

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

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

Calls the write(byte[],int,int) of the underlying stream.

Overrides:

write in class FilterOutputStream

Parameters:

b - the data.

off - the start offset in the data.

len - the number of bytes to write.

Throws:

IOException - if an I/O error occurs.

See Also:

FilterOutputStream.write(int)

write

public long write(Document doc)
           throws IOException

Writes the Document in BSON format to the underlying stream.

This method automatically calls flushBuffer().

Parameters:

doc - The document to write.

Returns:

The number of bytes written for the document.

Throws:

IOException - On a failure to write to the underlying document.

writeByte

public void writeByte(byte b)

Writes a single byte to the output buffer.

Users of this method must call flushBuffer() or the contents will not be written to the wrapped stream.

Parameters:

b - The byte to write.

writeBytes

public void writeBytes(byte[] data)

Writes a sequence of bytes to the output buffer.

Users of this method must call flushBuffer() or the contents will not be written to the wrapped stream.

Parameters:

data - The bytes to write.

writeCString

public void writeCString(String... strings)

Writes a "Cstring" to the output buffer.

Users of this method must call flushBuffer() or the contents will not be written to the wrapped stream.

Parameters:

strings - The CString to write. The strings are concatenated into a single CString value.

writeDocument

public void writeDocument(Document doc)
                   throws IOException

Writes the Document in BSON format to the underlying stream.

Users of this method must call flushBuffer() or the contents will not be written to the wrapped stream.

Parameters:

doc - The document to write.

Throws:

IOException - On a failure to write to the underlying document.

writeInt

public void writeInt(int value)

Writes the integer value in little-endian byte order to the output buffer.

Users of this method must call flushBuffer() or the contents will not be written to the wrapped stream.

Parameters:

value - The value to write.

writeIntAt

public void writeIntAt(long position,
              int value)

Similar to writeInt(int) but allows a portion of the already written buffer to be re-written.

Users of this method must call flushBuffer() or the contents will not be written to the wrapped stream.

Parameters:

position - The position to write at. This location should have already been written.

value - The integer value to write.

writeLong

public void writeLong(long value)

Write the long value in little-endian byte order to the output buffer.

Users of this method must call flushBuffer() or the contents will not be written to the wrapped stream.

Parameters:

value - The long to write.

writeString

public void writeString(String string)

Writes a "string" to the output buffer.

Users of this method must call flushBuffer() or the contents will not be written to the wrapped stream.

Parameters:

string - The String to write.