com.allanbank.mongodb.bson.io

Class RandomAccessOutputStream

java.lang.Object

java.io.OutputStream

com.allanbank.mongodb.bson.io.RandomAccessOutputStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

public class RandomAccessOutputStream
extends OutputStream

Provides a capability similar to the ByteArrayOutputStream but also provides the ability to re-write portions of the stream already written and to determine the current size (or position) of the written data.

Instead of allocating a single large byte array this implementation tracks a group of (increasing in size) buffers. This should reduce the runtime cost of buffer reallocations since it avoids the copy of contents from one buffer to another.

API Warning:

This class is NOT part of the drivers API. This class may be mutated in incompatible ways between any two releases of the driver.

Copyright ©:

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

Field Summary

Fields

Modifier and Type	Field and Description
static Charset	UTF8 UTF-8 Character set for encoding strings.

Constructor Summary

Constructors

Constructor and Description
RandomAccessOutputStream() Creates a new RandomAccessOutputStream.
RandomAccessOutputStream(StringEncoderCache cache) Creates a new RandomAccessOutputStream.

Method Summary

Methods

Modifier and Type	Method and Description
void	close()
void	flush()
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.
long	getPosition() Returns the current position in the stream.
long	getSize() Returns the number of bytes written to the stream.
protected void	nextBuffer() Allocates a new buffer to use.
void	reset() Resets the size of the buffer to zero.
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[] buffer)
void	write(byte[] buffer, int offset, int length)
void	write(int b)
void	writeAt(long position, byte[] buffer) Similar to write(byte[]) but allows a portion of the already written buffer to be re-written.
void	writeAt(long position, byte[] buffer, int offset, int length) Similar to write(byte[], int, int) but allows a portion of the already written buffer to be re-written.
void	writeAt(long position, int b) Similar to write(int) but allows a portion of the already written buffer to be re-written.
void	writeByte(byte b) Writes a single byte to the stream.
void	writeBytes(byte[] data) Writes a sequence of bytes to the under lying stream.
void	writeCString(String... strings) Writes a "Cstring" to the stream.
void	writeInt(int value) Write the integer value in little-endian byte order.
void	writeIntAt(long position, int value) Write the integer value in little-endian byte order at the specified position in the stream.
void	writeLong(long value) Write the long value in little-endian byte order.
void	writeString(String string) Writes a "string" to the stream.
void	writeTo(OutputStream out) Writes the complete contents of this byte array output stream to the specified output stream argument, as if by calling the output stream's write method using out.write(buf, 0, count).

Methods inherited from class java.lang.Object

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

Field Detail

UTF8

public static final Charset UTF8

UTF-8 Character set for encoding strings.

Constructor Detail

RandomAccessOutputStream

public RandomAccessOutputStream()

Creates a new RandomAccessOutputStream.

RandomAccessOutputStream

public RandomAccessOutputStream(StringEncoderCache cache)

Creates a new RandomAccessOutputStream.

Parameters:

cache - The cache for encoding string.

Method Detail

close

public void close()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class OutputStream

flush

public void flush()

Specified by:

flush in interface Flushable

Overrides:

flush in class OutputStream

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.

getPosition

public long getPosition()

Returns the current position in the stream. This is equivalent to getSize().

Returns:

The current position in the stream.

getSize

public long getSize()

Returns the number of bytes written to the stream.

Returns:

The current number of bytes written to the stream.

reset

public void reset()

Resets the size of the buffer to zero. All buffers can be re-used.

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[] buffer)

Overrides:

write in class OutputStream

Parameters:

buffer - the data.

write

public void write(byte[] buffer,
         int offset,
         int length)

Overrides:

write in class OutputStream

Parameters:

buffer - the data.

offset - the start offset in the data.

length - the number of bytes to write.

write

public void write(int b)

Specified by:

write in class OutputStream

writeAt

public void writeAt(long position,
           byte[] buffer)

Similar to write(byte[]) but allows a portion of the already written buffer to be re-written.

Equivalent to writeAt(position, buffer, 0, buffer.length);.

Parameters:

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

buffer - the data.

writeAt

public void writeAt(long position,
           byte[] buffer,
           int offset,
           int length)

Similar to write(byte[], int, int) but allows a portion of the already written buffer to be re-written.

Parameters:

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

buffer - the data.

offset - the start offset in the data.

length - the number of bytes to write.

writeAt

public void writeAt(long position,
           int b)

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

Parameters:

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

b - The byte value to write.

writeByte

public void writeByte(byte b)

Writes a single byte to the stream.

Parameters:

b - The byte to write.

writeBytes

public void writeBytes(byte[] data)

Writes a sequence of bytes to the under lying stream.

Parameters:

data - The bytes to write.

writeCString

public void writeCString(String... strings)

Writes a "Cstring" to the stream.

Parameters:

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

writeInt

public void writeInt(int value)

Write the integer value in little-endian byte order.

Parameters:

value - The integer to write.

writeIntAt

public void writeIntAt(long position,
              int value)

Write the integer value in little-endian byte order at the specified position in the stream.

Parameters:

position - The position in the stream to write the integer.

value - The long to write.

writeLong

public void writeLong(long value)

Write the long value in little-endian byte order.

Parameters:

value - The long to write.

writeString

public void writeString(String string)

Writes a "string" to the stream.

Parameters:

string - The String to write.

writeTo

public void writeTo(OutputStream out)
             throws IOException

Writes the complete contents of this byte array output stream to the specified output stream argument, as if by calling the output stream's write method using out.write(buf, 0, count).

Parameters:

out - the output stream to which to write the data.

Throws:

IOException - if an I/O error occurs.

nextBuffer

protected void nextBuffer()

Allocates a new buffer to use.