com.allanbank.mongodb.bson.builder

Interface ArrayBuilder

All Superinterfaces:

Builder

All Known Implementing Classes:

ArrayBuilderImpl

public interface ArrayBuilder
extends Builder

Interface for a builder used to construct a BSON array.

API Notice:

This interface 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

Method Summary

Methods

Modifier and Type	Method and Description
ArrayBuilder	add(boolean value) Adds a boolean element.
ArrayBuilder	add(byte[] data) Adds a binary element using sub-type zero (the default).
ArrayBuilder	add(byte subType, byte[] data) Adds a binary element.
ArrayBuilder	add(Date timestamp) Adds a timestamp element.
ArrayBuilder	add(DocumentAssignable document) Adds a pre-constructed document to the array.
ArrayBuilder	add(DocumentElement document) Adds a pre-constructed DocumentElement to the array.
ArrayBuilder	add(double value) Adds a double element.
ArrayBuilder	add(ElementAssignable element) Adds a pre-built element to the document.
ArrayBuilder	add(int value) Adds a integer (32-bit signed) element.
ArrayBuilder	add(long value) Adds a long (64-bit signed) element.
ArrayBuilder	add(Object value) Adds the value to the array after trying to coerce the value into the best possible element type.
ArrayBuilder	add(ObjectId id) Adds an ObjectId element.
ArrayBuilder	add(Pattern pattern) Adds an ObjectId element.
ArrayBuilder	add(String value) Adds a string element.
ArrayBuilder	add(String databaseName, String collectionName, ObjectId id) Deprecated. See BSON specification.
ArrayBuilder	add(UUID uuid) Adds a (sub-type 4) UUID binary element.
ArrayBuilder	addBinary(byte[] data) Adds a binary element using sub-type zero (the default).
ArrayBuilder	addBinary(byte subType, byte[] data) Adds a binary element.
ArrayBuilder	addBoolean(boolean value) Adds a boolean element.
ArrayBuilder	addDBPointer(String databaseName, String collectionName, ObjectId id) Deprecated. See BSON specification.
ArrayBuilder	addDocument(DocumentAssignable document) Adds a pre-constructed document to the array.
ArrayBuilder	addDouble(double value) Adds a double element.
ArrayBuilder	addInteger(int value) Adds a integer (32-bit signed) element.
ArrayBuilder	addJavaScript(String code) Adds a JavaScript element.
ArrayBuilder	addJavaScript(String code, DocumentAssignable scope) Adds a JavaScript with Scope element.
ArrayBuilder	addLegacyUuid(UUID uuid) Adds a legacy (sub-type 3) UUID binary element.
ArrayBuilder	addLong(long value) Adds a long (64-bit signed) element.
ArrayBuilder	addMaxKey() Adds a minimum key value element.
ArrayBuilder	addMinKey() Adds a minimum key value element.
ArrayBuilder	addMongoTimestamp(long value) Adds a MongoDB Timestamp element.
ArrayBuilder	addNull() Adds a null valued element.
ArrayBuilder	addObjectId(ObjectId id) Adds an ObjectId element.
ArrayBuilder	addRegularExpression(Pattern pattern) Adds a regular expression element.
ArrayBuilder	addRegularExpression(String pattern, String options) Adds a regular expression element.
ArrayBuilder	addString(String value) Adds a string element.
ArrayBuilder	addSymbol(String symbol) Adds a symbol element.
ArrayBuilder	addTimestamp(long timestamp) Adds a timestamp element.
ArrayBuilder	addUuid(UUID uuid) Adds a (sub-type 4) UUID binary element.
Element[]	build() Returns the array of Elements being constructed.
DocumentBuilder	push() Pushes a context for constructing a sub-document.
ArrayBuilder	pushArray() Pushes a context for constructing a sub-array.
ArrayBuilder	reset() Resets the builder back to an empty state.

Methods inherited from interface com.allanbank.mongodb.bson.builder.Builder

pop

Method Detail

add

ArrayBuilder add(boolean value)

Adds a boolean element.

This is a equivalent to addBoolean(boolean) but less verbose.

Parameters:

value - The boolean value.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(byte subType,
               byte[] data)
                 throws IllegalArgumentException

Adds a binary element.

This is a equivalent to addBinary(byte, byte[]) but less verbose.

Parameters:

subType - The sub-type for the binary data.

data - The binary value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If data is null.

add

ArrayBuilder add(byte[] data)

Adds a binary element using sub-type zero (the default).

This is a equivalent to addBinary(byte[]) but will insert a NullElement if the data is null instead of throwing an IllegalArgumentException.

Parameters:

data - The binary value.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(Date timestamp)

Adds a timestamp element. The timestamp is the number of milliseconds since the Unix epoch.

This is a equivalent to addTimeStamp(timestamp.getTime()) but will insert a NullElement if the timestamp is null instead of throwing an IllegalArgumentException.

Parameters:

timestamp - The number of milliseconds since the Unix epoch.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(DocumentAssignable document)

Adds a pre-constructed document to the array.

This is a equivalent to addDocument(DocumentAssignable) but will insert a NullElement if the document is null instead of throwing an IllegalArgumentException.

Parameters:

document - The document to add to the array.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(DocumentElement document)

Adds a pre-constructed DocumentElement to the array.

This is a equivalent to addDocument(DocumentAssignable) but will insert a NullElement if the document is null instead of throwing an IllegalArgumentException.

Added to resolve ambiguity between the DocumentElement being both a DocumentAssignable and an ElementAssignable.

Parameters:

document - The document to add to the array.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(double value)

Adds a double element.

This is a equivalent to addDouble(double) but less verbose.

Parameters:

value - The double value.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(ElementAssignable element)
                 throws IllegalArgumentException

Adds a pre-built element to the document.

Parameters:

element - The element to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If element is null.

add

ArrayBuilder add(int value)

Adds a integer (32-bit signed) element.

This is a equivalent to addInteger(int) but less verbose.

Parameters:

value - The integer value.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(long value)

Adds a long (64-bit signed) element.

This is a equivalent to addLong(long) but less verbose.

Parameters:

value - The long value.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(Object value)
                 throws IllegalArgumentException

Adds the value to the array after trying to coerce the value into the best possible element type. If the coersion fails then an IllegalArgumentException is thrown.

This method does type inspection which can be slow. It is generally much faster to use the type specific methods of this interface.

Parameters:

value - The Object value to coerce into an element.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If the value cannot be coerced into an element type.

add

ArrayBuilder add(ObjectId id)

Adds an ObjectId element.

This is a equivalent to addObjectId(ObjectId) but will insert a NullElement if the id is null instead of throwing an IllegalArgumentException.

Parameters:

id - The ObjectId to add.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(Pattern pattern)

Adds an ObjectId element.

This is a equivalent to addRegularExpression(Pattern) but will insert a NullElement if the pattern is null instead of throwing an IllegalArgumentException.

Parameters:

pattern - The pattern for the regular expression.

Returns:

This ArrayBuilder for method chaining.

add

ArrayBuilder add(String value)

Adds a string element.

This is a equivalent to addString(String) but will insert a NullElement if the value is null instead of throwing an IllegalArgumentException.

Parameters:

value - The string value.

Returns:

This ArrayBuilder for method chaining.

add

@Deprecated
ArrayBuilder add(String databaseName,
                          String collectionName,
                          ObjectId id)
                 throws IllegalArgumentException

Deprecated. See BSON specification.

Adds a deprecated DBPointer element.

This is a equivalent to addDBPointer(String, String, ObjectId) but less verbose.

Parameters:

databaseName - The name of the database containing the document.

collectionName - The name of the collection containing the document.

id - The id for the document.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If databaseName, collectionName, or id is null.

add

ArrayBuilder add(UUID uuid)

Adds a (sub-type 4) UUID binary element.

This is a equivalent to addUuid(UUID) but will insert a NullElement if the uuid is null instead of throwing an IllegalArgumentException.

Parameters:

uuid - The UUID to add.

Returns:

This ArrayBuilder for method chaining.

addBinary

ArrayBuilder addBinary(byte subType,
                     byte[] data)
                       throws IllegalArgumentException

Adds a binary element.

Parameters:

subType - The sub-type for the binary data.

data - The binary value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If data is null.

addBinary

ArrayBuilder addBinary(byte[] data)
                       throws IllegalArgumentException

Adds a binary element using sub-type zero (the default).

This method throws an IllegalArgumentException if the data is null. If you would prefer a NullElement be inserted in the document use the add(byte[]) method instead.

Parameters:

data - The binary value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If data is null.

addBoolean

ArrayBuilder addBoolean(boolean value)

Adds a boolean element.

Parameters:

value - The boolean value.

Returns:

This ArrayBuilder for method chaining.

addDBPointer

@Deprecated
ArrayBuilder addDBPointer(String databaseName,
                                   String collectionName,
                                   ObjectId id)
                          throws IllegalArgumentException

Deprecated. See BSON specification.

Adds a deprecated DBPointer element.

Parameters:

databaseName - The name of the database containing the document.

collectionName - The name of the collection containing the document.

id - The id for the document.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If databaseName, collectionName, or id is null.

addDocument

ArrayBuilder addDocument(DocumentAssignable document)
                         throws IllegalArgumentException

Adds a pre-constructed document to the array.

This method throws an IllegalArgumentException if the document is null. If you would prefer a NullElement be inserted in the document use the add(DocumentAssignable) method instead.

Parameters:

document - The document to add to the array.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If document is null.

addDouble

ArrayBuilder addDouble(double value)

Adds a double element.

Parameters:

value - The double value.

Returns:

This ArrayBuilder for method chaining.

addInteger

ArrayBuilder addInteger(int value)

Adds a integer (32-bit signed) element.

Parameters:

value - The integer value.

Returns:

This ArrayBuilder for method chaining.

addJavaScript

ArrayBuilder addJavaScript(String code)
                           throws IllegalArgumentException

Adds a JavaScript element.

Parameters:

code - The java script code.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If code is null.

addJavaScript

ArrayBuilder addJavaScript(String code,
                         DocumentAssignable scope)
                           throws IllegalArgumentException

Adds a JavaScript with Scope element.

Parameters:

code - The java script code.

scope - The scope for the JacaScript code.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If code or scope is null.

addLegacyUuid

ArrayBuilder addLegacyUuid(UUID uuid)
                           throws IllegalArgumentException

Adds a legacy (sub-type 3) UUID binary element.

This method throws an IllegalArgumentException if the uuid is null.

Parameters:

uuid - The UUID to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If the uuid is null.

addLong

ArrayBuilder addLong(long value)

Adds a long (64-bit signed) element.

Parameters:

value - The long value.

Returns:

This ArrayBuilder for method chaining.

addMaxKey

ArrayBuilder addMaxKey()

Adds a minimum key value element. Used as an absolute upper bounds.

Returns:

This ArrayBuilder for method chaining.

addMinKey

ArrayBuilder addMinKey()

Adds a minimum key value element. Used as an absolute lower bounds.

Returns:

This ArrayBuilder for method chaining.

addMongoTimestamp

ArrayBuilder addMongoTimestamp(long value)

Adds a MongoDB Timestamp element.

Parameters:

value - The mongoDB timstamp value.

Returns:

This ArrayBuilder for method chaining.

addNull

ArrayBuilder addNull()

Adds a null valued element.

Returns:

This ArrayBuilder for method chaining.

addObjectId

ArrayBuilder addObjectId(ObjectId id)
                         throws IllegalArgumentException

Adds an ObjectId element.

This method throws an IllegalArgumentException if the id is null. If you would prefer a NullElement be inserted in the document use the add(ObjectId) method instead.

Parameters:

id - The ObjectId to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If id is null.

addRegularExpression

ArrayBuilder addRegularExpression(Pattern pattern)
                                  throws IllegalArgumentException

Adds a regular expression element.

This method throws an IllegalArgumentException if the pattern is null. If you would prefer a NullElement be inserted in the document use the add(Pattern) method instead.

Parameters:

pattern - The pattern for the regular expression.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If pattern is null.

addRegularExpression

ArrayBuilder addRegularExpression(String pattern,
                                String options)
                                  throws IllegalArgumentException

Adds a regular expression element.

Parameters:

pattern - The pattern for the regular expression.

options - The regular expression options. See the BSON specification for details. These may be null.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If pattern is null. The options may be null.

addString

ArrayBuilder addString(String value)
                       throws IllegalArgumentException

Adds a string element.

This method throws an IllegalArgumentException if the value is null. If you would prefer a NullElement be inserted in the document use the add(String) method instead.

Parameters:

value - The string value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If value is null.

addSymbol

ArrayBuilder addSymbol(String symbol)
                       throws IllegalArgumentException

Adds a symbol element.

Parameters:

symbol - The symbol value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If symbol is null.

addTimestamp

ArrayBuilder addTimestamp(long timestamp)

Adds a timestamp element. The timestamp is the number of milliseconds since the Unix epoch.

Parameters:

timestamp - The number of milliseconds since the Unix epoch.

Returns:

This ArrayBuilder for method chaining.

addUuid

ArrayBuilder addUuid(UUID uuid)
                     throws IllegalArgumentException

Adds a (sub-type 4) UUID binary element.

This method throws an IllegalArgumentException if the uuid is null. If you would prefer a NullElement be inserted in the array use the add(UUID) method instead.

Parameters:

uuid - The UUID to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If the uuid is null.

build

Element[] build()

Returns the array of Elements being constructed.

Returns:

The constructed array of Element.

push

DocumentBuilder push()

Pushes a context for constructing a sub-document.

Returns:

This ArrayBuilder for method chaining.

pushArray

ArrayBuilder pushArray()

Pushes a context for constructing a sub-array.

Returns:

This ArrayBuilder for method chaining.

reset

ArrayBuilder reset()

Resets the builder back to an empty state.

Overridden to return an ArrayBuilder instance.

Specified by:

reset in interface Builder

Returns:

This builder for method call chaining.