BuilderFactory (mongodb-async-driver 2.0.1 API)

java.lang.Object
- com.allanbank.mongodb.bson.builder.BuilderFactory

```
public class BuilderFactory
extends Object
```
Helper class for getting started with a builder. The use of this class is encouraged to avoid direct references to the builder implementations.
Two modes are provided by this class. The first uses the static methods d(com.allanbank.mongodb.bson.Element...), a(), and e(java.lang.String, boolean) to create documents, arrays, and elements of a document respectfully. This allows for the quick construction of documents with a known structure. As an example consider the following code:
```
 
 DocumentBuilder movie = d(
    e( "title", "Gone with the Wind" ),
    e( "directors", a( "Victor Fleming", "George Cukor", "Sam Wood" ) ),
    e( "stars", a( "Clark Gable", "Vivien Leigh", "Thomas Mitchell" ))
 );
 
 
```
The above code creates a document with the following JSON structure:
```
 
 {
    "title" : "Gone with the Wind",
    "directors" : [ "Victor Fleming", "George Cukor", "Sam Wood" ],
    "stars" : [ "Clark Gable", "Vivien Leigh", "Thomas Mitchell" ]
 }
 
 
```
The second model for creating documents is to use the DocumentBuilder s and ArrayBuilders directly to dynamically construct the documents. To create a dynamic builders call one of the start() methods. Here is an example creating the equivalent document we saw above:
```
 
 DocumentBuilder movie = BuilderFactory.start();
 movie.add("title", "Gone with the Wind");
 
 ArrayBuilder directorsArray = movie.pushArray("directors");
 directorsArray.add("Victor Fleming")
               .add("George Cukor")
               .add("Sam Wood");
 
 ArrayBuilder starsArray = movie.pushArray("stars");
 starsArray.add("Clark Gable")
           .add("Vivien Leigh")
           .add("Thomas Mitchell");
 
 
```
The choice between the static or dynamic builders is based on a user's preference.
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

Method Summary

Methods
Modifier and Type	Method and Description
`static ArrayElement`	`a()` Creates an array element containing no elements.
`static ArrayElement`	`a(Boolean... values)` Creates an array element containing boolean elements.
`static ArrayElement`	`a(byte[]... datas)` Creates an array element containing binary elements using sub-type zero (the default).
`static ArrayElement`	`a(Date... timestamps)` Creates an array element containing timestamp elements.
`static ArrayElement`	`a(DocumentAssignable... documents)` Creates an array element containing pre-constructed document elements.
`static ArrayElement`	`a(Double... values)` Creates an array element containing double elements.
`static ArrayElement`	`a(ElementAssignable... elements)` Creates an array element containing the re-created slements.
`static ArrayElement`	`a(Integer... values)` Creates an array element containing integer (32-bit signed) elements.
`static ArrayElement`	`a(Long... values)` Creates an array element containing long (64-bit signed) elements.
`static ArrayElement`	`a(Object... values)` Creates an ArrayElement after trying to coerce the values into the best possible element type.
`static ArrayElement`	`a(ObjectId... ids)` Creates an array element containing ObjectId elements.
`static ArrayElement`	`a(Pattern... patterns)` Creates an array element containing regular expression elements.
`static ArrayElement`	`a(String... values)` Creates an array element containing string elements.
`static ArrayElement`	`a(UUID... uuids)` Create an array element containing (sub-type 4) `UUID` elements.
`static DocumentBuilder`	`d(Element... elements)` Helper method for creating static document structures.
`static BooleanElement`	`e(String name, boolean value)` Creates a boolean element.
`static Element`	`e(String name, byte[] data)` Creates a binary element using sub-type zero (the default).
`static Element`	`e(String name, Date timestamp)` Creates a timestamp element.
`static Element`	`e(String name, DocumentAssignable document)` Creates a pre-constructed document element.
`static DoubleElement`	`e(String name, double value)` Creates a double element.
`static Element`	`e(String name, ElementAssignable element)` Re-creates the Element with the name provided.
`static IntegerElement`	`e(String name, int value)` Creates a integer (32-bit signed) element.
`static LongElement`	`e(String name, long value)` Creates a long (64-bit signed) element.
`static Element`	`e(String name, Object value)` Creates an element after trying to coerce the value into the best possible element type.
`static Element`	`e(String name, ObjectId id)` Creates an ObjectId element.
`static Element`	`e(String name, Pattern pattern)` Creates a regular expression element.
`static Element`	`e(String name, String value)` Creates a string element.
`static Element`	`e(String name, UUID uuid)` Create a (sub-type 4) `UUID` element.
`static DocumentBuilder`	`start()` Creates a new `DocumentBuilder`.
`static DocumentBuilder`	`start(DocumentAssignable... seedDocuments)` Creates a new `DocumentBuilder` to append more elements to an existing set of documents.
`static DocumentBuilder`	`start(DocumentAssignable seedDocument)` Creates a new `DocumentBuilder` to append more elements to an existing document.
`static ArrayBuilder`	`startArray()` Creates a new `ArrayBuilder`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - a
```
public static final ArrayElement a()
                            throws IllegalArgumentException
```
    Creates an array element containing no elements. e.g., an empty array.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(Boolean... values)
                            throws IllegalArgumentException
```
    Creates an array element containing boolean elements.
    
    Parameters:
    values - The boolean value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(byte[]... datas)
                            throws IllegalArgumentException
```
    Creates an array element containing binary elements using sub-type zero (the default).
    Will return a NullElement if any data is null.
    
    Parameters:
    datas - The binary value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(Date... timestamps)
                            throws IllegalArgumentException
```
    Creates an array element containing timestamp elements. The timestamp is the number of milliseconds since the Unix epoch.
    Will return a NullElement if any timestamp is null.
    
    Parameters:
    timestamps - The number of milliseconds since the Unix epoch.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(DocumentAssignable... documents)
                            throws IllegalArgumentException
```
    Creates an array element containing pre-constructed document elements.
    Will return a NullElement if any document is null.
    
    Parameters:
    documents - The document to wrap.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(Double... values)
                            throws IllegalArgumentException
```
    Creates an array element containing double elements.
    
    Parameters:
    values - The double value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(ElementAssignable... elements)
                            throws IllegalArgumentException
```
    Creates an array element containing the re-created slements.
    Will return a NullElement if any element is null.
    
    Parameters:
    elements - The element to add to wrap.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(Integer... values)
                            throws IllegalArgumentException
```
    Creates an array element containing integer (32-bit signed) elements.
    
    Parameters:
    values - The integer value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(Long... values)
                            throws IllegalArgumentException
```
    Creates an array element containing long (64-bit signed) elements.
    
    Parameters:
    values - The long value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(Object... values)
```
    Creates an ArrayElement after trying to coerce the values into the best possible element type. If the coercion fails then an IllegalArgumentException is thrown.
    
    Parameters:
    values - The Object values to coerce into an element.
    
    Returns:
    The ArrayElement with the name "" and the provided values.
    
    Throws:
    
    IllegalArgumentException - If the name is null or the value cannot be coerced into an element type.
  - a
```
public static final ArrayElement a(ObjectId... ids)
                            throws IllegalArgumentException
```
    Creates an array element containing ObjectId elements.
    Will return a NullElement if any id is null.
    
    Parameters:
    ids - The ObjectId to wrap.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name or id is null.
  - a
```
public static final ArrayElement a(Pattern... patterns)
                            throws IllegalArgumentException
```
    Creates an array element containing regular expression elements.
    Will return a NullElement if any pattern is null.
    
    Parameters:
    patterns - The pattern for the regular expression.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(String... values)
                            throws IllegalArgumentException
```
    Creates an array element containing string elements.
    Will return a NullElement if any value is null.
    
    Parameters:
    values - The string value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - a
```
public static final ArrayElement a(UUID... uuids)
                            throws IllegalArgumentException
```
    Create an array element containing (sub-type 4) UUID elements.
    Will return a NullElement if the uuid is null.
    
    Parameters:
    uuids - The UUIDs to wrap in an element.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - d
```
public static final DocumentBuilder d(Element... elements)
```
    Helper method for creating static document structures.
    
    Parameters:
    elements - The elements of the document. The elements may be created using the e(java.lang.String, boolean) methods.
    
    Returns:
    The document builder seeded with the specified elements.
  - e
```
public static final BooleanElement e(String name,
               boolean value)
                              throws IllegalArgumentException
```
    Creates a boolean element.
    
    Parameters:
    name - The name of the element.
    value - The boolean value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final Element e(String name,
        byte[] data)
                       throws IllegalArgumentException
```
    Creates a binary element using sub-type zero (the default).
    Will return a NullElement if the data is null.
    
    Parameters:
    name - The name of the element.
    data - The binary value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final Element e(String name,
        Date timestamp)
                       throws IllegalArgumentException
```
    Creates a timestamp element. The timestamp is the number of milliseconds since the Unix epoch.
    Will return a NullElement if the timestamp is null.
    
    Parameters:
    name - The name of the element.
    timestamp - The number of milliseconds since the Unix epoch.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final Element e(String name,
        DocumentAssignable document)
                       throws IllegalArgumentException
```
    Creates a pre-constructed document element.
    Will return a NullElement if the document is null.
    
    Parameters:
    name - The name of the element.
    document - The document to wrap.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final DoubleElement e(String name,
              double value)
                             throws IllegalArgumentException
```
    Creates a double element.
    
    Parameters:
    name - The name of the element.
    value - The double value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final Element e(String name,
        ElementAssignable element)
                       throws IllegalArgumentException
```
    Re-creates the Element with the name provided.
    Will return a NullElement if the element is null.
    
    Parameters:
    name - The name of the element.
    element - The element to add to wrap.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final IntegerElement e(String name,
               int value)
                              throws IllegalArgumentException
```
    Creates a integer (32-bit signed) element.
    
    Parameters:
    name - The name of the element.
    value - The integer value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final LongElement e(String name,
            long value)
                           throws IllegalArgumentException
```
    Creates a long (64-bit signed) element.
    
    Parameters:
    name - The name of the element.
    value - The long value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final Element e(String name,
        Object value)
```
    Creates an element 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 e(java.lang.String, boolean) methods of this class.
    
    Parameters:
    name - The name of the element.
    value - The Object value to coerce into an element.
    
    Returns:
    The element with the name and value.
    
    Throws:
    
    IllegalArgumentException - If the name is null or the value cannot be coerced into an element type.
  - e
```
public static final Element e(String name,
        ObjectId id)
                       throws IllegalArgumentException
```
    Creates an ObjectId element.
    Will return a NullElement if the id is null.
    
    Parameters:
    name - The name of the element.
    id - The ObjectId to wrap.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name or id is null.
  - e
```
public static final Element e(String name,
        Pattern pattern)
                       throws IllegalArgumentException
```
    Creates a regular expression element.
    Will return a NullElement if the pattern is null.
    
    Parameters:
    name - The name of the element.
    pattern - The pattern for the regular expression.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final Element e(String name,
        String value)
                       throws IllegalArgumentException
```
    Creates a string element.
    Will return a NullElement if the value is null.
    
    Parameters:
    name - The name of the element.
    value - The string value.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - e
```
public static final Element e(String name,
        UUID uuid)
                       throws IllegalArgumentException
```
    Create a (sub-type 4) UUID element.
    Will return a NullElement if the uuid is null.
    
    Parameters:
    name - The name of the element.
    uuid - The UUID to wrap in an element.
    
    Returns:
    The wrapped element.
    
    Throws:
    
    IllegalArgumentException - If the name is null.
  - start
```
public static final DocumentBuilder start()
```
    Creates a new DocumentBuilder.
    
    Returns:
    The root level document builder.
  - start
```
public static final DocumentBuilder start(DocumentAssignable seedDocument)
```
    Creates a new DocumentBuilder to append more elements to an existing document.
    
    Parameters:
    seedDocument - The document to seed the builder with. The builder will contain the seed document elements plus any added/appended elements.
    
    Returns:
    The root level document builder.
  - start
```
public static final DocumentBuilder start(DocumentAssignable... seedDocuments)
```
    Creates a new DocumentBuilder to append more elements to an existing set of documents.
    
    Parameters:
    seedDocuments - The documents to seed the builder with. The builder will contain the seed document elements plus any added/appended elements.
    
    Returns:
    The root level document builder.
  - startArray
```
public static final ArrayBuilder startArray()
```
    Creates a new ArrayBuilder.
    
    Returns:
    The root level array builder.

Class BuilderFactory

Method Summary

Methods inherited from class java.lang.Object

Method Detail

a

a

a

a

a

a

a

a

a

a

a

a

a

a

d

e

e

e

e

e

e

e

e

e

e

e

e

e

start

start

start

startArray