com.allanbank.mongodb.bson.builder

Interface DocumentBuilder

All Superinterfaces:

Builder, DocumentAssignable

All Known Implementing Classes:

AggregationGroupId.Builder, DocumentBuilderImpl

public interface DocumentBuilder
extends Builder, DocumentAssignable

Interface for a builder used to construct a BSON document.

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-2012, Allanbank Consulting, Inc., All Rights Reserved

Method Summary

Methods

Modifier and Type	Method and Description
DocumentBuilder	add(ElementAssignable element) 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. See BSON specification.
DocumentBuilder	add(String name, UUID uuid) Adds a (sub-type 4) UUID binary element.
DocumentBuilder	addBinary(String name, byte[] data) Adds a binary element using sub-type zero (the default).
DocumentBuilder	addBinary(String name, byte subType, byte[] data) 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. See BSON specification.
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	build() Returns the Document 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.

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

pop

Methods inherited from interface com.allanbank.mongodb.bson.DocumentAssignable

asDocument

Method Detail

add

DocumentBuilder add(ElementAssignable element)
                    throws IllegalArgumentException

Adds a pre-built element to the document.

Parameters:

element - The element to add.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the element is null.

add

DocumentBuilder add(String name,
                  boolean value)
                    throws IllegalArgumentException

Adds a boolean element.

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

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

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

Adds a binary element.

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

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

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

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

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

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

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.

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

DocumentBuilder add(String name,
                  DocumentAssignable document)
                    throws IllegalArgumentException

Adds a pre-constructed document to the array.

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

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

DocumentBuilder add(String name,
                  double value)
                    throws IllegalArgumentException

Adds a double element.

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

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

DocumentBuilder add(String name,
                  int value)
                    throws IllegalArgumentException

Adds a integer (32-bit signed) element.

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

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

DocumentBuilder add(String name,
                  long value)
                    throws IllegalArgumentException

Adds a long (64-bit signed) element.

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

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

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 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:

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

DocumentBuilder add(String name,
                  ObjectId id)
                    throws IllegalArgumentException

Adds an ObjectId element.

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

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

DocumentBuilder add(String name,
                  Pattern pattern)
                    throws IllegalArgumentException

Adds an ObjectId element.

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

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

DocumentBuilder add(String name,
                  String value)
                    throws IllegalArgumentException

Adds a string element.

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

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
DocumentBuilder add(String name,
                             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, String, ObjectId) but less verbose.

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

DocumentBuilder add(String name,
                  UUID uuid)
                    throws IllegalArgumentException

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

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

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

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

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

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.

addBinary

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

Parameters:

name - The name of the element.

data - The binary value.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name or value is null.

addBoolean

DocumentBuilder addBoolean(String name,
                         boolean value)
                           throws IllegalArgumentException

Adds a boolean element.

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
DocumentBuilder addDBPointer(String name,
                                      String databaseName,
                                      String collectionName,
                                      ObjectId id)
                             throws IllegalArgumentException

Deprecated. See BSON specification.

Adds a deprecated DBPointer element.

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

DocumentBuilder addDocument(String name,
                          DocumentAssignable value)
                            throws IllegalArgumentException

Adds a pre-built document element. Can also 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 add(String, DocumentAssignable) method instead.

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

DocumentBuilder addDouble(String name,
                        double value)
                          throws IllegalArgumentException

Adds a double element.

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

DocumentBuilder addInteger(String name,
                         int value)
                           throws IllegalArgumentException

Adds a integer (32-bit signed) element.

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

DocumentBuilder addJavaScript(String name,
                            String code)
                              throws IllegalArgumentException

Adds a JavaScript element.

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

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

Adds a JavaScript with Scope element.

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

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.

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

DocumentBuilder addLong(String name,
                      long value)
                        throws IllegalArgumentException

Adds a long (64-bit signed) element.

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

DocumentBuilder addMaxKey(String name)
                          throws IllegalArgumentException

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

Parameters:

name - The name of the element.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addMinKey

DocumentBuilder addMinKey(String name)
                          throws IllegalArgumentException

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

Parameters:

name - The name of the element.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addMongoTimestamp

DocumentBuilder addMongoTimestamp(String name,
                                long value)
                                  throws IllegalArgumentException

Adds a MongoDB Timestamp element.

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

DocumentBuilder addNull(String name)
                        throws IllegalArgumentException

Adds a null valued element.

Parameters:

name - The name of the element.

Returns:

This DocumentBuilder for method chaining.

Throws:

IllegalArgumentException - If the name is null.

addObjectId

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

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

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

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

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

Adds a regular expression element.

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

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

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

DocumentBuilder addSymbol(String name,
                        String symbol)
                          throws IllegalArgumentException

Adds a symbol element.

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

DocumentBuilder addTimestamp(String name,
                           long timestamp)
                             throws IllegalArgumentException

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

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

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 add(String, UUID) method instead.

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.

build

Document build()

Returns the Document being constructed.

Returns:

The constructed Document.

push

DocumentBuilder push(String name)
                     throws IllegalArgumentException

Pushes a context for constructing a sub-document.

Parameters:

name - The name of the sub-document.

Returns:

A DocumentBuilder for constructing the sub-document.

Throws:

IllegalArgumentException - If the name is null.

pushArray

ArrayBuilder pushArray(String name)
                       throws IllegalArgumentException

Pushes a context for constructing a sub-array.

Parameters:

name - The name of the sub-array.

Returns:

A ArrayBuilder for constructing the sub-array.

Throws:

IllegalArgumentException - If the name is null.

remove

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 add that element to the end of document's element list.

Parameters:

name - The name of the element to remove.

Returns:

This DocumentBuilder for method chaining.

reset

DocumentBuilder reset()

Resets the builder back to an empty state.

Overridden to return an DocumentBuilder instance.

Specified by:

reset in interface Builder

Returns:

This builder for method call chaining.