com.allanbank.mongodb.bson.builder.impl

Class DocumentBuilderImpl

java.lang.Object

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

com.allanbank.mongodb.bson.builder.impl.DocumentBuilderImpl

All Implemented Interfaces:

Builder, DocumentBuilder, DocumentAssignable

Direct Known Subclasses:

AggregationGroupId.Builder

public class DocumentBuilderImpl
extends AbstractBuilder
implements DocumentBuilder

A builder for BSON documents.

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
DocumentBuilderImpl() Creates a new builder.
DocumentBuilderImpl(AbstractBuilder outerScope) Creates a new builder.
DocumentBuilderImpl(DocumentAssignable seedDocument) Creates a new builder.

Method Summary

Methods

Modifier and Type	Method and Description
DocumentBuilder	add(ElementAssignable elementRef) Adds a pre-built element to the document.
DocumentBuilder	add(String name, boolean value) Adds a boolean element.
DocumentBuilder	add(String name, byte[] data) Adds a binary element using sub-type zero (the default).
DocumentBuilder	add(String name, byte subType, byte[] data) Adds a binary element.
DocumentBuilder	add(String name, Date timestamp) Adds a timestamp element.
DocumentBuilder	add(String name, DocumentAssignable document) Adds a pre-constructed document to the array.
DocumentBuilder	add(String name, double value) Adds a double element.
DocumentBuilder	add(String name, int value) Adds a integer (32-bit signed) element.
DocumentBuilder	add(String name, long value) Adds a long (64-bit signed) element.
DocumentBuilder	add(String name, Object value) Adds the value to the document after trying to coerce the value into the best possible element type.
DocumentBuilder	add(String name, ObjectId id) Adds an ObjectId element.
DocumentBuilder	add(String name, Pattern pattern) Adds an ObjectId element.
DocumentBuilder	add(String name, String value) Adds a string element.
DocumentBuilder	add(String name, String databaseName, String collectionName, ObjectId id) Deprecated.
DocumentBuilder	add(String name, UUID uuid) Adds a (sub-type 4) UUID binary element.
DocumentBuilder	addBinary(String name, byte[] value) Adds a binary element using sub-type zero (the default).
DocumentBuilder	addBinary(String name, byte subType, byte[] value) Adds a binary element using sub-type zero (the default).
DocumentBuilder	addBoolean(String name, boolean value) Adds a boolean element.
DocumentBuilder	addDBPointer(String name, String databaseName, String collectionName, ObjectId id) Deprecated.
DocumentBuilder	addDocument(String name, DocumentAssignable value) Adds a pre-built document element.
DocumentBuilder	addDouble(String name, double value) Adds a double element.
DocumentBuilder	addInteger(String name, int value) Adds a integer (32-bit signed) element.
DocumentBuilder	addJavaScript(String name, String code) Adds a JavaScript element.
DocumentBuilder	addJavaScript(String name, String code, DocumentAssignable scope) Adds a JavaScript with Scope element.
DocumentBuilder	addLegacyUuid(String name, UUID uuid) Adds a legacy (sub-type 3) UUID binary element.
DocumentBuilder	addLong(String name, long value) Adds a long (64-bit signed) element.
DocumentBuilder	addMaxKey(String name) Adds a minimum key value element.
DocumentBuilder	addMinKey(String name) Adds a minimum key value element.
DocumentBuilder	addMongoTimestamp(String name, long value) Adds a MongoDB Timestamp element.
DocumentBuilder	addNull(String name) Adds a null valued element.
DocumentBuilder	addObjectId(String name, ObjectId id) Adds an ObjectId element.
DocumentBuilder	addRegularExpression(String name, Pattern pattern) Adds a regular expression element.
DocumentBuilder	addRegularExpression(String name, String pattern, String options) Adds a regular expression element.
DocumentBuilder	addString(String name, String value) Adds a string element.
DocumentBuilder	addSymbol(String name, String symbol) Adds a symbol element.
DocumentBuilder	addTimestamp(String name, long timestamp) Adds a timestamp element.
DocumentBuilder	addUuid(String name, UUID uuid) Adds a (sub-type 4) UUID binary element.
Document	asDocument() Converts the object into a document.
Document	build() Returns the Document being constructed.
protected Element	build(String name) Constructs the final form of the element being constructed.
DocumentBuilder	push(String name) Pushes a context for constructing a sub-document.
ArrayBuilder	pushArray(String name) Pushes a context for constructing a sub-array.
DocumentBuilder	remove(String name) Removes all Elements that have the provided name from the document being built.
DocumentBuilder	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

DocumentBuilderImpl

public DocumentBuilderImpl()

Creates a new builder.

DocumentBuilderImpl

public DocumentBuilderImpl(AbstractBuilder outerScope)

Creates a new builder.

Parameters:

outerScope - The outer document scope.

DocumentBuilderImpl

public DocumentBuilderImpl(DocumentAssignable seedDocument)

Creates a new builder.

Parameters:

seedDocument - The document to seed the builder with. The builder will contain the seed document elements plus any added/appended elements.

Method Detail

add

public DocumentBuilder add(ElementAssignable elementRef)
                    throws IllegalArgumentException

Adds a pre-built element to the document.

Specified by:

add in interface DocumentBuilder

Parameters:

elementRef - The element to add.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the element is null.

add

public DocumentBuilder add(String name,
                  boolean value)
                    throws IllegalArgumentException

Adds a boolean element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The boolean value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

public DocumentBuilder add(String name,
                  byte subType,
                  byte[] data)
                    throws IllegalArgumentException

Adds a binary element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

subType - The sub-type for the binary data.

data - The binary value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or data is null.

add

public DocumentBuilder add(String name,
                  byte[] data)
                    throws IllegalArgumentException

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

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

data - The binary value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

public DocumentBuilder add(String name,
                  Date timestamp)
                    throws IllegalArgumentException

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 DocumentBuilder

Parameters:

name - The name of the element.

timestamp - The number of milliseconds since the Unix epoch.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

public DocumentBuilder add(String name,
                  DocumentAssignable document)
                    throws IllegalArgumentException

Adds a pre-constructed document to the array.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

document - The document to add to the array.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

public DocumentBuilder add(String name,
                  double value)
                    throws IllegalArgumentException

Adds a double element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The double value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

public DocumentBuilder add(String name,
                  int value)
                    throws IllegalArgumentException

Adds a integer (32-bit signed) element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The integer value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

public DocumentBuilder add(String name,
                  long value)
                    throws IllegalArgumentException

Adds a long (64-bit signed) element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The long value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

public DocumentBuilder add(String name,
                  Object value)
                    throws IllegalArgumentException

Adds the value to the document 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 DocumentBuilder

Parameters:

name - The name of the element.

value - The Object value to coerce into an element.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null or the value cannot be coerced into an element type.

add

public DocumentBuilder add(String name,
                  ObjectId id)
                    throws IllegalArgumentException

Adds an ObjectId element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

id - The ObjectId to add.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or id is null.

add

public DocumentBuilder add(String name,
                  Pattern pattern)
                    throws IllegalArgumentException

Adds an ObjectId element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

pattern - The pattern for the regular expression.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

public DocumentBuilder add(String name,
                  String value)
                    throws IllegalArgumentException

Adds a string element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The string value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

add

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

Deprecated.

Adds a deprecated DBPointer element.

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

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 DocumentBuilder for method chaining.

Throws:

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

add

public DocumentBuilder add(String name,
                  UUID uuid)
                    throws IllegalArgumentException

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

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

Specified by:

add in interface DocumentBuilder

Parameters:

name - The name of the element.

uuid - The UUID to add.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addBinary

public DocumentBuilder addBinary(String name,
                        byte subType,
                        byte[] value)
                          throws IllegalArgumentException

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

Specified by:

addBinary in interface DocumentBuilder

Parameters:

name - The name of the element.

subType - The sub-type for the binary data.

value - The binary value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or data is null.

addBinary

public DocumentBuilder addBinary(String name,
                        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 DocumentBuilder.add(String, byte[]) method instead.

Specified by:

addBinary in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The binary value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or value is null.

addBoolean

public DocumentBuilder addBoolean(String name,
                         boolean value)
                           throws IllegalArgumentException

Adds a boolean element.

Specified by:

addBoolean in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The boolean value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addDBPointer

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

Deprecated.

Adds a deprecated DBPointer element.

Specified by:

addDBPointer in interface DocumentBuilder

Parameters:

name - The name of the element.

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 DocumentBuilder for method chaining.

Throws:

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

addDocument

public DocumentBuilder addDocument(String name,
                          DocumentAssignable value)
                            throws IllegalArgumentException

Adds a pre-built document element. Can also DocumentBuilder.push(String) a sub document.

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

Specified by:

addDocument in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The document value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or value is null.

addDouble

public DocumentBuilder addDouble(String name,
                        double value)
                          throws IllegalArgumentException

Adds a double element.

Specified by:

addDouble in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The double value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addInteger

public DocumentBuilder addInteger(String name,
                         int value)
                           throws IllegalArgumentException

Adds a integer (32-bit signed) element.

Specified by:

addInteger in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The integer value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addJavaScript

public DocumentBuilder addJavaScript(String name,
                            String code)
                              throws IllegalArgumentException

Adds a JavaScript element.

Specified by:

addJavaScript in interface DocumentBuilder

Parameters:

name - The name of the element.

code - The java script code.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or code is null.

addJavaScript

public DocumentBuilder addJavaScript(String name,
                            String code,
                            DocumentAssignable scope)
                              throws IllegalArgumentException

Adds a JavaScript with Scope element.

Specified by:

addJavaScript in interface DocumentBuilder

Parameters:

name - The name of the element.

code - The java script code.

scope - The scope for the JacaScript code.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name, value, or scope is null.

addLegacyUuid

public DocumentBuilder addLegacyUuid(String name,
                            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 DocumentBuilder

Parameters:

name - The name of the element.

uuid - The UUID to add.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or uuid is null.

addLong

public DocumentBuilder addLong(String name,
                      long value)
                        throws IllegalArgumentException

Adds a long (64-bit signed) element.

Specified by:

addLong in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The long value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addMaxKey

public DocumentBuilder addMaxKey(String name)
                          throws IllegalArgumentException

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

Specified by:

addMaxKey in interface DocumentBuilder

Parameters:

name - The name of the element.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addMinKey

public DocumentBuilder addMinKey(String name)
                          throws IllegalArgumentException

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

Specified by:

addMinKey in interface DocumentBuilder

Parameters:

name - The name of the element.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addMongoTimestamp

public DocumentBuilder addMongoTimestamp(String name,
                                long value)
                                  throws IllegalArgumentException

Adds a MongoDB Timestamp element.

Specified by:

addMongoTimestamp in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The mongoDB timstamp value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addNull

public DocumentBuilder addNull(String name)
                        throws IllegalArgumentException

Adds a null valued element.

Specified by:

addNull in interface DocumentBuilder

Parameters:

name - The name of the element.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addObjectId

public DocumentBuilder addObjectId(String name,
                          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 DocumentBuilder.add(String, ObjectId) method instead.

Specified by:

addObjectId in interface DocumentBuilder

Parameters:

name - The name of the element.

id - The ObjectId to add.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or id is null.

addRegularExpression

public DocumentBuilder addRegularExpression(String name,
                                   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 DocumentBuilder.add(String, Pattern) method instead.

Specified by:

addRegularExpression in interface DocumentBuilder

Parameters:

name - The name of the element.

pattern - The pattern for the regular expression.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or pattern is null.

addRegularExpression

public DocumentBuilder addRegularExpression(String name,
                                   String pattern,
                                   String options)
                                     throws IllegalArgumentException

Adds a regular expression element.

Specified by:

addRegularExpression in interface DocumentBuilder

Parameters:

name - The name of the element.

pattern - The pattern for the regular expression.

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

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or pattern is null. Note the options may be null.

addString

public DocumentBuilder addString(String name,
                        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 DocumentBuilder.add(String, String) method instead.

Specified by:

addString in interface DocumentBuilder

Parameters:

name - The name of the element.

value - The string value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or value is null.

addSymbol

public DocumentBuilder addSymbol(String name,
                        String symbol)
                          throws IllegalArgumentException

Adds a symbol element.

Specified by:

addSymbol in interface DocumentBuilder

Parameters:

name - The name of the element.

symbol - The symbol value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or symbol is null.

addTimestamp

public DocumentBuilder addTimestamp(String name,
                           long timestamp)
                             throws IllegalArgumentException

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

Specified by:

addTimestamp in interface DocumentBuilder

Parameters:

name - The name of the element.

timestamp - The number of milliseconds since the Unix epoch.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addUuid

public DocumentBuilder addUuid(String name,
                      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 document use the DocumentBuilder.add(String, UUID) method instead.

Specified by:

addUuid in interface DocumentBuilder

Parameters:

name - The name of the element.

uuid - The UUID to add.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or uuid is null.

asDocument

public Document asDocument()

Converts the object into a document.

Returns the result of build().

Specified by:

asDocument in interface DocumentAssignable

Returns:

The object as a Document.

See Also:

build()

build

public Document build()

Returns the Document being constructed.

Specified by:

build in interface DocumentBuilder

Returns:

The constructed Document.

push

public DocumentBuilder push(String name)

Pushes a context for constructing a sub-document.

Specified by:

push in interface DocumentBuilder

Parameters:

name - The name of the sub-document.

Returns:

A DocumentBuilder for constructing the sub-document.

pushArray

public ArrayBuilder pushArray(String name)

Pushes a context for constructing a sub-array.

Specified by:

pushArray in interface DocumentBuilder

Parameters:

name - The name of the sub-array.

Returns:

A ArrayBuilder for constructing the sub-array.

remove

public DocumentBuilder remove(String name)

Removes all Elements that have the provided name from the document being built.

Note that adding a new element with the same name adds that element to the end of document's element list.

Specified by:

remove in interface DocumentBuilder

Parameters:

name - The name of the element to remove.

Returns:

This DocumentBuilder for method chaining.

reset

public DocumentBuilder reset()

Resets the builder back to an empty state.

Specified by:

reset in interface Builder

Specified by:

reset in interface DocumentBuilder

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 a document.

Overrides:

toString in class Object

build

protected Element build(String name)

Constructs the final form of the element being constructed.

Overridden to return an DocumentElement.

Specified by:

build in class AbstractBuilder

Parameters:

name - The name of the element.

Returns:

The Element constructed by the builder.