com.allanbank.mongodb.bson.builder.impl

Class ArrayBuilderImpl

java.lang.Object

com.allanbank.mongodb.bson.builder.impl.AbstractBuilder

com.allanbank.mongodb.bson.builder.impl.ArrayBuilderImpl

All Implemented Interfaces:

ArrayBuilder, Builder

public class ArrayBuilderImpl
extends AbstractBuilder
implements ArrayBuilder

A builder for BSON arrays.

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

Nested Class Summary

Nested classes/interfaces inherited from class com.allanbank.mongodb.bson.builder.impl.AbstractBuilder

AbstractBuilder.BuilderElement

Field Summary

Fields inherited from class com.allanbank.mongodb.bson.builder.impl.AbstractBuilder

ASSERTIONS_ENABLED, BUILDER_ELEMENT_CLASS, myElements, mySize

Constructor Summary

Constructors

Constructor and Description
ArrayBuilderImpl() Creates a new ArrayBuilderImpl.
ArrayBuilderImpl(AbstractBuilder outerBuilder) Creates a new ArrayBuilderImpl.

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.
ArrayBuilder	add(UUID uuid) Adds a (sub-type 4) UUID binary element.
ArrayBuilder	addBinary(byte[] value) Adds a binary element using sub-type zero (the default).
ArrayBuilder	addBinary(byte subType, byte[] value) Adds a binary element.
ArrayBuilder	addBoolean(boolean value) Adds a boolean element.
ArrayBuilder	addDBPointer(String databaseName, String collectionName, ObjectId id) Deprecated.
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.
ArrayElement	build(String name) Constructs the final form of the element 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.
String	toString()

Methods inherited from class com.allanbank.mongodb.bson.builder.impl.AbstractBuilder

doPush, doPushArray, pop, subElements

Methods inherited from class java.lang.Object

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

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

pop

Constructor Detail

ArrayBuilderImpl

public ArrayBuilderImpl()

Creates a new ArrayBuilderImpl.

ArrayBuilderImpl

public ArrayBuilderImpl(AbstractBuilder outerBuilder)

Creates a new ArrayBuilderImpl.

Parameters:

outerBuilder - The outer builder scope.

Method Detail

add

public ArrayBuilder add(boolean value)

Adds a boolean element.

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

Specified by:

add in interface ArrayBuilder

Parameters:

value - The boolean value.

Returns:

This ArrayBuilder for method chaining.

add

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

Adds a binary element.

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

Specified by:

add in interface ArrayBuilder

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

public ArrayBuilder add(byte[] data)

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

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

Specified by:

add in interface ArrayBuilder

Parameters:

data - The binary value.

Returns:

This ArrayBuilder for method chaining.

add

public 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.

Specified by:

add in interface ArrayBuilder

Parameters:

timestamp - The number of milliseconds since the Unix epoch.

Returns:

This ArrayBuilder for method chaining.

add

public ArrayBuilder add(DocumentAssignable document)

Adds a pre-constructed document to the array.

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

Specified by:

add in interface ArrayBuilder

Parameters:

document - The document to add to the array.

Returns:

This ArrayBuilder for method chaining.

add

public ArrayBuilder add(DocumentElement document)

Adds a pre-constructed DocumentElement to the array.

This is a equivalent to ArrayBuilder.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.

Specified by:

add in interface ArrayBuilder

Parameters:

document - The document to add to the array.

Returns:

This ArrayBuilder for method chaining.

add

public ArrayBuilder add(double value)

Adds a double element.

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

Specified by:

add in interface ArrayBuilder

Parameters:

value - The double value.

Returns:

This ArrayBuilder for method chaining.

add

public ArrayBuilder add(ElementAssignable element)
                 throws IllegalArgumentException

Adds a pre-built element to the document.

Specified by:

add in interface ArrayBuilder

Parameters:

element - The element to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If element is null.

add

public ArrayBuilder add(int value)

Adds a integer (32-bit signed) element.

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

Specified by:

add in interface ArrayBuilder

Parameters:

value - The integer value.

Returns:

This ArrayBuilder for method chaining.

add

public ArrayBuilder add(long value)

Adds a long (64-bit signed) element.

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

Specified by:

add in interface ArrayBuilder

Parameters:

value - The long value.

Returns:

This ArrayBuilder for method chaining.

add

public 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 coercion 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.

Specified by:

add in interface ArrayBuilder

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

public ArrayBuilder add(ObjectId id)

Adds an ObjectId element.

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

Specified by:

add in interface ArrayBuilder

Parameters:

id - The ObjectId to add.

Returns:

This ArrayBuilder for method chaining.

add

public ArrayBuilder add(Pattern pattern)

Adds an ObjectId element.

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

Specified by:

add in interface ArrayBuilder

Parameters:

pattern - The pattern for the regular expression.

Returns:

This ArrayBuilder for method chaining.

add

public ArrayBuilder add(String value)

Adds a string element.

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

Specified by:

add in interface ArrayBuilder

Parameters:

value - The string value.

Returns:

This ArrayBuilder for method chaining.

add

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

Deprecated.

Adds a deprecated DBPointer element.

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

Specified by:

add in interface ArrayBuilder

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

public ArrayBuilder add(UUID uuid)
                 throws IllegalArgumentException

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

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

Specified by:

add in interface ArrayBuilder

Parameters:

uuid - The UUID to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException

addBinary

public ArrayBuilder addBinary(byte subType,
                     byte[] value)
                       throws IllegalArgumentException

Adds a binary element.

Specified by:

addBinary in interface ArrayBuilder

Parameters:

subType - The sub-type for the binary data.

value - The binary value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If data is null.

addBinary

public ArrayBuilder addBinary(byte[] value)
                       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 ArrayBuilder.add(byte[]) method instead.

Specified by:

addBinary in interface ArrayBuilder

Parameters:

value - The binary value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If data is null.

addBoolean

public ArrayBuilder addBoolean(boolean value)

Adds a boolean element.

Specified by:

addBoolean in interface ArrayBuilder

Parameters:

value - The boolean value.

Returns:

This ArrayBuilder for method chaining.

addDBPointer

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

Deprecated.

Adds a deprecated DBPointer element.

Specified by:

addDBPointer in interface ArrayBuilder

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

public 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 ArrayBuilder.add(DocumentAssignable) method instead.

Specified by:

addDocument in interface ArrayBuilder

Parameters:

document - The document to add to the array.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If document is null.

addDouble

public ArrayBuilder addDouble(double value)

Adds a double element.

Specified by:

addDouble in interface ArrayBuilder

Parameters:

value - The double value.

Returns:

This ArrayBuilder for method chaining.

addInteger

public ArrayBuilder addInteger(int value)

Adds a integer (32-bit signed) element.

Specified by:

addInteger in interface ArrayBuilder

Parameters:

value - The integer value.

Returns:

This ArrayBuilder for method chaining.

addJavaScript

public ArrayBuilder addJavaScript(String code)
                           throws IllegalArgumentException

Adds a JavaScript element.

Specified by:

addJavaScript in interface ArrayBuilder

Parameters:

code - The java script code.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If code is null.

addJavaScript

public ArrayBuilder addJavaScript(String code,
                         DocumentAssignable scope)
                           throws IllegalArgumentException

Adds a JavaScript with Scope element.

Specified by:

addJavaScript in interface ArrayBuilder

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

public 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.

Specified by:

addLegacyUuid in interface ArrayBuilder

Parameters:

uuid - The UUID to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If the uuid is null.

addLong

public ArrayBuilder addLong(long value)

Adds a long (64-bit signed) element.

Specified by:

addLong in interface ArrayBuilder

Parameters:

value - The long value.

Returns:

This ArrayBuilder for method chaining.

addMaxKey

public ArrayBuilder addMaxKey()

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

Specified by:

addMaxKey in interface ArrayBuilder

Returns:

This ArrayBuilder for method chaining.

addMinKey

public ArrayBuilder addMinKey()

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

Specified by:

addMinKey in interface ArrayBuilder

Returns:

This ArrayBuilder for method chaining.

addMongoTimestamp

public ArrayBuilder addMongoTimestamp(long value)

Adds a MongoDB Timestamp element.

Specified by:

addMongoTimestamp in interface ArrayBuilder

Parameters:

value - The mongoDB timstamp value.

Returns:

This ArrayBuilder for method chaining.

addNull

public ArrayBuilder addNull()

Adds a null valued element.

Specified by:

addNull in interface ArrayBuilder

Returns:

This ArrayBuilder for method chaining.

addObjectId

public 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 ArrayBuilder.add(ObjectId) method instead.

Specified by:

addObjectId in interface ArrayBuilder

Parameters:

id - The ObjectId to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If id is null.

addRegularExpression

public 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 ArrayBuilder.add(Pattern) method instead.

Specified by:

addRegularExpression in interface ArrayBuilder

Parameters:

pattern - The pattern for the regular expression.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If pattern is null.

addRegularExpression

public ArrayBuilder addRegularExpression(String pattern,
                                String options)
                                  throws IllegalArgumentException

Adds a regular expression element.

Specified by:

addRegularExpression in interface ArrayBuilder

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

public 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 ArrayBuilder.add(String) method instead.

Specified by:

addString in interface ArrayBuilder

Parameters:

value - The string value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If value is null.

addSymbol

public ArrayBuilder addSymbol(String symbol)
                       throws IllegalArgumentException

Adds a symbol element.

Specified by:

addSymbol in interface ArrayBuilder

Parameters:

symbol - The symbol value.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If symbol is null.

addTimestamp

public ArrayBuilder addTimestamp(long timestamp)

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

Specified by:

addTimestamp in interface ArrayBuilder

Parameters:

timestamp - The number of milliseconds since the Unix epoch.

Returns:

This ArrayBuilder for method chaining.

addUuid

public 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 ArrayBuilder.add(UUID) method instead.

Specified by:

addUuid in interface ArrayBuilder

Parameters:

uuid - The UUID to add.

Returns:

This ArrayBuilder for method chaining.

Throws:

IllegalArgumentException - If the uuid is null.

build

public Element[] build()

Returns the array of Elements being constructed.

Overridden to return an array of the built elements.

Specified by:

build in interface ArrayBuilder

Returns:

The constructed array of Element.

build

public ArrayElement build(String name)

Constructs the final form of the element being constructed.

Overridden to return an ArrayElement.

Specified by:

build in class AbstractBuilder

Parameters:

name - The name of the element.

Returns:

The Element constructed by the builder.

push

public DocumentBuilder push()

Pushes a context for constructing a sub-document.

Specified by:

push in interface ArrayBuilder

Returns:

This ArrayBuilder for method chaining.

pushArray

public ArrayBuilder pushArray()

Pushes a context for constructing a sub-array.

Specified by:

pushArray in interface ArrayBuilder

Returns:

This ArrayBuilder for method chaining.

reset

public ArrayBuilder reset()

Resets the builder back to an empty state.

Specified by:

reset in interface ArrayBuilder

Specified by:

reset in interface Builder

Overrides:

reset in class AbstractBuilder

Returns:

This builder for method call chaining.

toString

public String toString()

Overridden to return the current state of the builder as an array element.

Overrides:

toString in class Object