BsonInputStream (mongodb-async-driver 2.0.1 API)

java.lang.Object
- java.io.InputStream
- - com.allanbank.mongodb.bson.io.BsonInputStream

All Implemented Interfaces:

Closeable, AutoCloseable
```
public class BsonInputStream
extends InputStream
```
BsonInputStream provides a class to read BSON documents based on the BSON specification.

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
Modifier and Type Field and Description

static Charset UTF8
UTF-8 Character set for encoding strings.

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

Constructor Summary

Constructors
Constructor and Description
`BsonInputStream(InputStream input)` Creates a BSON document reader.
`BsonInputStream(InputStream input, int expectedMaxDocumentSize)` Creates a BSON document reader.
`BsonInputStream(InputStream input, int expectedMaxDocumentSize, StringDecoderCache cache)` Creates a BSON document reader.
`BsonInputStream(InputStream input, StringDecoderCache cache)` Creates a BSON document reader.

Method Summary

Methods
Modifier and Type	Method and Description
`int`	`available()`
`protected int`	`availableInBuffer()` Returns the number of bytes available in the buffer.
`void`	`close()`
`long`	`getBytesRead()` Returns the number of bytes that have been read by the stream.
`int`	`getMaxCachedStringEntries()` Deprecated. The cache `StringDecoderCache` should be controlled directory. This method will be removed after the 2.1.0 release.
`int`	`getMaxCachedStringLength()` Deprecated. The cache `StringDecoderCache` should be controlled directory. This method will be removed after the 2.1.0 release.
`void`	`mark(int readlimit)`
`boolean`	`markSupported()`
`void`	`prefetch(int size)` Tries to prefetch the requested number of bytes from the underlying stream.
`int`	`read()`
`int`	`read(byte[] b)`
`int`	`read(byte[] b, int off, int len)`
`protected ArrayElement`	`readArrayElement()` Reads a BSON Array element:
`protected BinaryElement`	`readBinaryElement()` Reads a `BinaryElement`'s contents:
`protected BooleanElement`	`readBooleanElement()` Reads a `BooleanElement` from the stream.
`String`	`readCString()` Reads a "cstring" value from the stream:
`protected Element`	`readDBPointerElement()` Deprecated. Per the BSON specification.
`Document`	`readDocument()` Reads a BSON document element:
`protected DocumentElement`	`readDocumentElement()` Reads a BSON Subdocument element:
`protected DoubleElement`	`readDoubleElement()` Reads a `DoubleElement` from the stream.
`protected Element`	`readElement(byte token)` Reads the element:
`protected List<Element>`	`readElements()` Reads a BSON element list (e_list):
`void`	`readFully(byte[] buffer)` Reads the complete set of bytes from the stream or throws an `EOFException`.
`int`	`readInt()` Reads a little-endian 4 byte signed integer from the stream.
`protected IntegerElement`	`readIntegerElement()` Reads a `IntegerElement` from the stream.
`protected JavaScriptElement`	`readJavaScriptElement()` Reads a `JavaScriptElement` from the stream.
`protected JavaScriptWithScopeElement`	`readJavaScriptWithScopeElement()` Reads a `JavaScriptWithScopeElement` from the stream.
`long`	`readLong()` Reads a little-endian 8 byte signed integer from the stream.
`protected LongElement`	`readLongElement()` Reads a `LongElement` from the stream.
`protected MaxKeyElement`	`readMaxKeyElement()` Reads a `MaxKeyElement` from the stream.
`protected MinKeyElement`	`readMinKeyElement()` Reads a `MinKeyElement` from the stream.
`protected MongoTimestampElement`	`readMongoTimestampElement()` Reads a `MongoTimestampElement` from the stream.
`protected NullElement`	`readNullElement()` Reads a `NullElement` from the stream.
`protected ObjectIdElement`	`readObjectIdElement()` Reads a `ObjectIdElement` from the stream.
`protected RegularExpressionElement`	`readRegularExpressionElement()` Reads a `RegularExpressionElement` from the stream.
`protected String`	`readString()` Reads a "string" value from the stream:
`protected StringElement`	`readStringElement()` Reads a `StringElement` from the stream.
`protected SymbolElement`	`readSymbolElement()` Reads a `SymbolElement` from the stream.
`protected TimestampElement`	`readTimestampElement()` Reads a `TimestampElement` from the stream.
`void`	`reset()`
`void`	`setMaxCachedStringEntries(int maxCacheEntries)` Deprecated. The cache `StringDecoderCache` should be controlled directory. This method will be removed after the 2.1.0 release.
`void`	`setMaxCachedStringLength(int maxlength)` Deprecated. The cache `StringDecoderCache` should be controlled directory. This method will be removed after the 2.1.0 release.
`long`	`skip(long n)`

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
  - BsonInputStream
```
public BsonInputStream(InputStream input)
```
    Creates a BSON document reader.
    
    Parameters:
    input - the underlying stream to read from.
  - BsonInputStream
```
public BsonInputStream(InputStream input,
               int expectedMaxDocumentSize)
```
    Creates a BSON document reader.
    
    Parameters:
    input - the underlying stream to read from.
    expectedMaxDocumentSize - The expected maximum size for a document. If this guess is wrong then there may be incremental allocations of the read buffer.
  - BsonInputStream
```
public BsonInputStream(InputStream input,
               int expectedMaxDocumentSize,
               StringDecoderCache cache)
```
    Creates a BSON document reader.
    
    Parameters:
    input - the underlying stream to read from.
    expectedMaxDocumentSize - The expected maximum size for a document. If this guess is wrong then there may be incremental allocations of the read buffer.
    cache - The cache to use for decoded strings.
  - BsonInputStream
```
public BsonInputStream(InputStream input,
               StringDecoderCache cache)
```
    Creates a BSON document reader.
    
    Parameters:
    input - the underlying stream to read from.
    cache - The cache to use for decoded strings.
- Method Detail
  - available
```
public int available()
              throws IOException
```
    Overridden to return the number of bytes in the buffer and from the source stream.
    
    Overrides:
    
    available in class InputStream
    
    Throws:
    
    IOException
  - close
```
public void close()
           throws IOException
```
    Overridden to close the wrapped InputStream.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Overrides:
    
    close in class InputStream
    
    Throws:
    
    IOException
  - getBytesRead
```
public long getBytesRead()
```
    Returns the number of bytes that have been read by the stream.
    
    Returns:
    The number of bytes that have been read from the stream.
  - getMaxCachedStringEntries
```
@Deprecated
public int getMaxCachedStringEntries()
```
    Deprecated. The cache StringDecoderCache 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 StringDecoderCache 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.
  - mark
```
public void mark(int readlimit)
```
    Overridden to throw an UnsupportedOperationException.
    
    Overrides:
    
    mark in class InputStream
  - markSupported
```
public boolean markSupported()
```
    Overridden to return false.
    
    Overrides:
    
    markSupported in class InputStream
  - prefetch
```
public final void prefetch(int size)
                    throws IOException
```
    Tries to prefetch the requested number of bytes from the underlying stream.
    
    Parameters:
    size - The number of bytes to try and read.
    
    Throws:
    
    IOException - On a failure to read from the underlying stream.
  - read
```
public int read()
         throws IOException
```
    Overridden to track the bytes that have been read.
    
    Specified by:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b)
         throws IOException
```
    Overridden to track the bytes that have been read.
    
    Overrides:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - read
```
public int read(byte[] b,
       int off,
       int len)
         throws IOException
```
    Overridden to track the bytes that have been read.
    
    Overrides:
    
    read in class InputStream
    
    Throws:
    
    IOException
  - readCString
```
public String readCString()
                   throws EOFException,
                          IOException
```
    Reads a "cstring" value from the stream:cstring ::= (byte*) "\x00"
    
    CString - Zero or more modified UTF-8 encoded characters followed by '\x00'. The (byte*) MUST NOT contain '\x00', hence it is not full UTF-8.
    Returns:
    The string value.
    
    Throws:
    
    EOFException - On insufficient data for the integer.
    
    IOException - On a failure reading the integer.
  - readDocument
```
public Document readDocument()
                      throws IOException
```
    Reads a BSON document element: document ::= int32 e_list "\x00"
    Returns:
    The Document.
    
    Throws:
    
    EOFException - On insufficient data for the document.
    
    IOException - On a failure reading the document.
  - readFully
```
public void readFully(byte[] buffer)
               throws EOFException,
                      IOException
```
    Reads the complete set of bytes from the stream or throws an EOFException.
    
    Parameters:
    buffer - The buffer into which the data is read.
    
    Throws:
    
    EOFException - If the input stream reaches the end before reading all the bytes.
    
    IOException - On an error reading from the underlying stream.
  - readInt
```
public int readInt()
            throws EOFException,
                   IOException
```
    Reads a little-endian 4 byte signed integer from the stream.
    
    Returns:
    The integer value.
    
    Throws:
    
    EOFException - On insufficient data for the integer.
    
    IOException - On a failure reading the integer.
  - readLong
```
public long readLong()
              throws EOFException,
                     IOException
```
    Reads a little-endian 8 byte signed integer from the stream.
    
    Returns:
    The long value.
    
    Throws:
    
    EOFException - On insufficient data for the long.
    
    IOException - On a failure reading the long.
  - reset
```
public void reset()
           throws UnsupportedOperationException
```
    Overridden to throw an UnsupportedOperationException.
    
    Overrides:
    
    reset in class InputStream
    
    Throws:
    
    UnsupportedOperationException
  - setMaxCachedStringEntries
```
@Deprecated
public void setMaxCachedStringEntries(int maxCacheEntries)
```
    Deprecated. The cache StringDecoderCache 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 StringDecoderCache 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.
  - skip
```
public long skip(long n)
          throws IOException
```
    Overridden to track the bytes that have been skipped.
    
    Overrides:
    
    skip in class InputStream
    
    Throws:
    
    IOException
  - availableInBuffer
```
protected final int availableInBuffer()
```
    Returns the number of bytes available in the buffer.
    
    Returns:
    The number of bytes available in the buffer.
  - readArrayElement
```
protected ArrayElement readArrayElement()
                                 throws IOException
```
    Reads a BSON Array element: "\x04" e_name document
    Returns:
    The ArrayElement.
    
    Throws:
    
    EOFException - On insufficient data for the document.
    
    IOException - On a failure reading the document.
  - readBinaryElement
```
protected BinaryElement readBinaryElement()
                                   throws IOException
```
    Reads a BinaryElement's contents: binary ::= int32 subtype (byte*) subtype ::= "\x00" Binary / Generic | "\x01" Function | "\x02" Binary (Old) | "\x03" UUID | "\x05" MD5 | "\x80" User defined
    Returns:
    The BinaryElement.
    
    Throws:
    
    IOException - On a failure reading the binary data.
  - readBooleanElement
```
protected BooleanElement readBooleanElement()
                                     throws IOException
```
    Reads a BooleanElement from the stream.
    
    Returns:
    The BooleanElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the BooleanElement.
  - readDBPointerElement
```
@Deprecated
protected Element readDBPointerElement()
                                throws IOException
```
    Deprecated. Per the BSON specification.
    
    Reads a DBPointerElement from the stream.
    
    Returns:
    The DBPointerElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the DBPointerElement.
  - readDocumentElement
```
protected DocumentElement readDocumentElement()
                                       throws IOException
```
    Reads a BSON Subdocument element: "\x03" e_name document
    Returns:
    The ArrayElement.
    
    Throws:
    
    IOException - On a failure reading the document.
  - readDoubleElement
```
protected DoubleElement readDoubleElement()
                                   throws IOException
```
    Reads a DoubleElement from the stream.
    
    Returns:
    The DoubleElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the DoubleElement.
  - readElement
```
protected Element readElement(byte token)
                       throws EOFException,
                              IOException
```
    Reads the element:element ::= "\x01" e_name double Floating point | "\x02" e_name string UTF-8 string | "\x03" e_name document Embedded document | "\x04" e_name document Array | "\x05" e_name binary Binary data | "\x06" e_name Undefined — Deprecated | "\x07" e_name (byte*12) ObjectId | "\x08" e_name "\x00" Boolean "false" | "\x08" e_name "\x01" Boolean "true" | "\x09" e_name int64 UTC datetime | "\x0A" e_name Null value | "\x0B" e_name cstring cstring Regular expression | "\x0C" e_name string (byte*12) DBPointer — Deprecated | "\x0D" e_name string JavaScript code | "\x0E" e_name string Symbol | "\x0F" e_name code_w_s JavaScript code w/ scope | "\x10" e_name int32 32-bit Integer | "\x11" e_name int64 Timestamp | "\x12" e_name int64 64-bit integer | "\xFF" e_name Min key | "\x7F" e_name Max key
    Parameters:
    token - The element's token.
    
    Returns:
    The Element.
    
    Throws:
    
    EOFException - On insufficient data for the element.
    
    IOException - On a failure reading the element.
  - readElements
```
protected List<Element> readElements()
                              throws EOFException,
                                     IOException
```
    Reads a BSON element list (e_list): e_list ::= element e_list | ""
    Returns:
    The list of elements.
    
    Throws:
    
    EOFException - On insufficient data for the elements.
    
    IOException - On a failure reading the elements.
  - readIntegerElement
```
protected IntegerElement readIntegerElement()
                                     throws IOException
```
    Reads a IntegerElement from the stream.
    
    Returns:
    The IntegerElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the IntegerElement.
  - readJavaScriptElement
```
protected JavaScriptElement readJavaScriptElement()
                                           throws IOException
```
    Reads a JavaScriptElement from the stream.
    
    Returns:
    The JavaScriptElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the JavaScriptElement.
  - readJavaScriptWithScopeElement
```
protected JavaScriptWithScopeElement readJavaScriptWithScopeElement()
                                                             throws IOException
```
    Reads a JavaScriptWithScopeElement from the stream.
    
    Returns:
    The JavaScriptWithScopeElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the JavaScriptWithScopeElement.
  - readLongElement
```
protected LongElement readLongElement()
                               throws IOException
```
    Reads a LongElement from the stream.
    
    Returns:
    The LongElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the LongElement.
  - readMaxKeyElement
```
protected MaxKeyElement readMaxKeyElement()
                                   throws IOException
```
    Reads a MaxKeyElement from the stream.
    
    Returns:
    The MaxKeyElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the MaxKeyElement.
  - readMinKeyElement
```
protected MinKeyElement readMinKeyElement()
                                   throws IOException
```
    Reads a MinKeyElement from the stream.
    
    Returns:
    The MinKeyElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the MinKeyElement.
  - readMongoTimestampElement
```
protected MongoTimestampElement readMongoTimestampElement()
                                                   throws IOException
```
    Reads a MongoTimestampElement from the stream.
    
    Returns:
    The MongoTimestampElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the MongoTimestampElement.
  - readNullElement
```
protected NullElement readNullElement()
                               throws IOException
```
    Reads a NullElement from the stream.
    
    Returns:
    The NullElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the NullElement.
  - readObjectIdElement
```
protected ObjectIdElement readObjectIdElement()
                                       throws IOException
```
    Reads a ObjectIdElement from the stream.
    
    Returns:
    The ObjectIdElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the ObjectIdElement.
  - readRegularExpressionElement
```
protected RegularExpressionElement readRegularExpressionElement()
                                                         throws IOException
```
    Reads a RegularExpressionElement from the stream.
    
    Returns:
    The RegularExpressionElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the RegularExpressionElement.
  - readString
```
protected String readString()
                     throws EOFException,
                            IOException
```
    Reads a "string" value from the stream:string ::= int32 (byte*) "\x00"
    
    String - The int32 is the number bytes in the (byte*) + 1 (for the trailing '\x00'). The (byte*) is zero or more UTF-8 encoded characters.
    Returns:
    The string value.
    
    Throws:
    
    EOFException - On insufficient data for the integer.
    
    IOException - On a failure reading the integer.
  - readStringElement
```
protected StringElement readStringElement()
                                   throws IOException
```
    Reads a StringElement from the stream.
    
    Returns:
    The StringElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the StringElement.
  - readSymbolElement
```
protected SymbolElement readSymbolElement()
                                   throws IOException
```
    Reads a SymbolElement from the stream.
    
    Returns:
    The SymbolElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the SymbolElement.
  - readTimestampElement
```
protected TimestampElement readTimestampElement()
                                         throws IOException
```
    Reads a TimestampElement from the stream.
    
    Returns:
    The TimestampElement.
    
    Throws:
    
    IOException - On a failure to read the contents of the TimestampElement.

Class BsonInputStream

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UTF8

Constructor Detail

BsonInputStream

BsonInputStream

BsonInputStream

BsonInputStream

Method Detail

available

close

getBytesRead

getMaxCachedStringEntries

getMaxCachedStringLength

mark

markSupported

prefetch

read

read

read

readCString

readDocument

readFully

readInt

readLong

reset

setMaxCachedStringEntries

setMaxCachedStringLength

skip

availableInBuffer

readArrayElement

readBinaryElement

readBooleanElement

readDBPointerElement

readDocumentElement

readDoubleElement

readElement

readElements

readIntegerElement

readJavaScriptElement

readJavaScriptWithScopeElement

readLongElement

readMaxKeyElement

readMinKeyElement

readMongoTimestampElement

readNullElement

readObjectIdElement

readRegularExpressionElement

readString

readStringElement

readSymbolElement

readTimestampElement