Coverage Report

Coverage Report - com.allanbank.mongodb.bson.builder.ArrayBuilder

Classes in this File

 /*
  * #%L
  * ArrayBuilder.java - mongodb-async-driver - Allanbank Consulting, Inc.
  * %%
  * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  * 
  *      http://www.apache.org/licenses/LICENSE-2.0
  * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  * #L%
  */
 package com.allanbank.mongodb.bson.builder;
 
 import java.util.Date;
 import java.util.UUID;
 import java.util.regex.Pattern;
 
 import com.allanbank.mongodb.bson.DocumentAssignable;
 import com.allanbank.mongodb.bson.Element;
 import com.allanbank.mongodb.bson.ElementAssignable;
 import com.allanbank.mongodb.bson.element.DocumentElement;
 import com.allanbank.mongodb.bson.element.NullElement;
 import com.allanbank.mongodb.bson.element.ObjectId;
 
 /**
  * Interface for a builder used to construct a BSON array.
  * 
  * @api.yes 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 &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
  *          before being removed or modified.
  * @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved
  */
 public interface ArrayBuilder extends Builder {
 
     /**
      * Adds a boolean element.
      * <p>
      * This is a equivalent to {@link #addBoolean(boolean)} but less verbose.
      * </p>
      * 
      * @param value
      *            The boolean value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(boolean value);
 
     /**
      * Adds a binary element.
      * <p>
      * This is a equivalent to {@link #addBinary(byte, byte[])} but less
      * verbose.
      * </p>
      * 
      * @param subType
      *            The sub-type for the binary data.
      * @param data
      *            The binary value.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code data} is <code>null</code>.
      */
     public ArrayBuilder add(byte subType, byte[] data)
             throws IllegalArgumentException;
 
     /**
      * Adds a binary element using sub-type zero (the default).
      * <p>
      * This is a equivalent to {@link #addBinary(byte[])} but will insert a
      * {@link NullElement} if the {@code data} is <code>null</code> instead of
      * throwing an {@link IllegalArgumentException}.
      * </p>
      * 
      * @param data
      *            The binary value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(byte[] data);
 
     /**
      * Adds a timestamp element. The timestamp is the number of milliseconds
      * since the Unix epoch.
      * <p>
      * This is a equivalent to {@link #addTimestamp(long)
      * addTimeStamp(timestamp.getTime())} but will insert a {@link NullElement}
      * if the {@code timestamp} is <code>null</code> instead of throwing an
      * {@link IllegalArgumentException}.
      * </p>
      * 
      * @param timestamp
      *            The number of milliseconds since the Unix epoch.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(Date timestamp);
 
     /**
      * Adds a pre-constructed document to the array.
      * <p>
      * This is a equivalent to {@link #addDocument(DocumentAssignable)} but will
      * insert a {@link NullElement} if the {@code document} is <code>null</code>
      * instead of throwing an {@link IllegalArgumentException}.
      * </p>
      * 
      * @param document
      *            The document to add to the array.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(DocumentAssignable document);
 
     /**
      * Adds a pre-constructed {@link DocumentElement} to the array.
      * <p>
      * This is a equivalent to {@link #addDocument(DocumentAssignable)} but will
      * insert a {@link NullElement} if the {@code document} is <code>null</code>
      * instead of throwing an {@link IllegalArgumentException}.
      * </p>
      * <p>
      * Added to resolve ambiguity between the {@link DocumentElement} being both
      * a {@link DocumentAssignable} and an {@link ElementAssignable}.
      * </p>
      * 
      * @param document
      *            The document to add to the array.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(DocumentElement document);
 
     /**
      * Adds a double element.
      * <p>
      * This is a equivalent to {@link #addDouble(double)} but less verbose.
      * </p>
      * 
      * @param value
      *            The double value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(double value);
 
     /**
      * Adds a pre-built element to the document.
      * 
      * @param element
      *            The element to add.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code element} is <code>null</code>.
      */
     public ArrayBuilder add(ElementAssignable element)
             throws IllegalArgumentException;
 
     /**
      * Adds a integer (32-bit signed) element.
      * <p>
      * This is a equivalent to {@link #addInteger(int)} but less verbose.
      * </p>
      * 
      * @param value
      *            The integer value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(int value);
 
     /**
      * Adds a long (64-bit signed) element.
      * <p>
      * This is a equivalent to {@link #addLong(long)} but less verbose.
      * </p>
      * 
      * @param value
      *            The long value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(long value);
 
     /**
      * Adds the value to the array after trying to coerce the value into the
      * best possible element type. If the coercion fails then an
      * {@link IllegalArgumentException} is thrown.
      * <p>
      * This method does type inspection which can be slow. It is generally much
      * faster to use the type specific methods of this interface.
      * </p>
      * 
      * @param value
      *            The Object value to coerce into an element.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If the {@code value} cannot be coerced into an element type.
      */
     public ArrayBuilder add(Object value) throws IllegalArgumentException;
 
     /**
      * Adds an ObjectId element.
      * <p>
      * This is a equivalent to {@link #addObjectId(ObjectId)} but will insert a
      * {@link NullElement} if the {@code id} is <code>null</code> instead of
      * throwing an {@link IllegalArgumentException}.
      * </p>
      * 
      * @param id
      *            The ObjectId to add.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(ObjectId id);
 
     /**
      * Adds an ObjectId element.
      * <p>
      * This is a equivalent to {@link #addRegularExpression(Pattern)} but will
      * insert a {@link NullElement} if the {@code pattern} is <code>null</code>
      * instead of throwing an {@link IllegalArgumentException}.
      * </p>
      * 
      * @param pattern
      *            The pattern for the regular expression.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(Pattern pattern);
 
     /**
      * Adds a string element.
      * <p>
      * This is a equivalent to {@link #addString(String)} but will insert a
      * {@link NullElement} if the {@code value} is <code>null</code> instead of
      * throwing an {@link IllegalArgumentException}.
      * </p>
      * 
      * @param value
      *            The string value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(String value);
 
     /**
      * Adds a deprecated DBPointer element.
      * <p>
      * This is a equivalent to {@link #addDBPointer(String, String, ObjectId)}
      * but less verbose.
      * </p>
      * 
      * @param databaseName
      *            The name of the database containing the document.
      * @param collectionName
      *            The name of the collection containing the document.
      * @param id
      *            The id for the document.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code databaseName}, {@code collectionName}, or
      *             {@code id} is <code>null</code>.
      * 
      * @deprecated See BSON specification.
      */
     @Deprecated
     public ArrayBuilder add(String databaseName, String collectionName,
             ObjectId id) throws IllegalArgumentException;
 
     /**
      * Adds a (sub-type 4) {@link UUID} binary element.
      * <p>
      * This is a equivalent to {@link #addUuid(UUID)} but will insert a
      * {@link NullElement} if the {@code uuid} is <code>null</code> instead of
      * throwing an {@link IllegalArgumentException}.
      * </p>
      * 
      * @param uuid
      *            The {@link UUID} to add.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder add(UUID uuid);
 
     /**
      * Adds a binary element.
      * 
      * @param subType
      *            The sub-type for the binary data.
      * @param data
      *            The binary value.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code data} is <code>null</code>.
      */
     public ArrayBuilder addBinary(byte subType, byte[] data)
             throws IllegalArgumentException;
 
     /**
      * Adds a binary element using sub-type zero (the default).
      * <p>
      * This method throws an {@link IllegalArgumentException} if the
      * {@code data} is <code>null</code>. If you would prefer a
      * {@link NullElement} be inserted in the document use the
      * {@link #add(byte[])} method instead.
      * </p>
      * 
      * @param data
      *            The binary value.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code data} is <code>null</code>.
      */
     public ArrayBuilder addBinary(byte[] data) throws IllegalArgumentException;
 
     /**
      * Adds a boolean element.
      * 
      * @param value
      *            The boolean value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addBoolean(boolean value);
 
     /**
      * Adds a deprecated DBPointer element.
      * 
      * @param databaseName
      *            The name of the database containing the document.
      * @param collectionName
      *            The name of the collection containing the document.
      * @param id
      *            The id for the document.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code databaseName}, {@code collectionName}, or
      *             {@code id} is <code>null</code>.
      * 
      * @deprecated See BSON specification.
      */
     @Deprecated
     public ArrayBuilder addDBPointer(String databaseName,
             String collectionName, ObjectId id) throws IllegalArgumentException;
 
     /**
      * Adds a pre-constructed document to the array.
      * <p>
      * This method throws an {@link IllegalArgumentException} if the
      * {@code document} is <code>null</code>. If you would prefer a
      * {@link NullElement} be inserted in the document use the
      * {@link #add(DocumentAssignable)} method instead.
      * </p>
      * 
      * @param document
      *            The document to add to the array.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code document} is <code>null</code>.
      */
     public ArrayBuilder addDocument(DocumentAssignable document)
             throws IllegalArgumentException;
 
     /**
      * Adds a double element.
      * 
      * @param value
      *            The double value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addDouble(double value);
 
     /**
      * Adds a integer (32-bit signed) element.
      * 
      * @param value
      *            The integer value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addInteger(int value);
 
     /**
      * Adds a JavaScript element.
      * 
      * @param code
      *            The java script code.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code code} is <code>null</code>.
      */
     public ArrayBuilder addJavaScript(String code)
             throws IllegalArgumentException;
 
     /**
      * Adds a JavaScript with Scope element.
      * 
      * @param code
      *            The java script code.
      * @param scope
      *            The scope for the JacaScript code.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code code} or {@code scope} is <code>null</code>.
      */
     public ArrayBuilder addJavaScript(String code, DocumentAssignable scope)
             throws IllegalArgumentException;
 
     /**
      * Adds a legacy (sub-type 3) {@link UUID} binary element.
      * <p>
      * This method throws an {@link IllegalArgumentException} if the
      * {@code uuid} is <code>null</code>.
      * </p>
      * 
      * @param uuid
      *            The {@link UUID} to add.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If the {@code uuid} is <code>null</code>.
      */
     public ArrayBuilder addLegacyUuid(UUID uuid)
             throws IllegalArgumentException;
 
     /**
      * Adds a long (64-bit signed) element.
      * 
      * @param value
      *            The long value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addLong(long value);
 
     /**
      * Adds a minimum key value element. Used as an absolute upper bounds.
      * 
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addMaxKey();
 
     /**
      * Adds a minimum key value element. Used as an absolute lower bounds.
      * 
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addMinKey();
 
     /**
      * Adds a MongoDB Timestamp element.
      * 
      * @param value
      *            The mongoDB timstamp value.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addMongoTimestamp(long value);
 
     /**
      * Adds a <code>null</code> valued element.
      * 
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addNull();
 
     /**
      * Adds an ObjectId element.
      * <p>
      * This method throws an {@link IllegalArgumentException} if the {@code id}
      * is <code>null</code>. If you would prefer a {@link NullElement} be
      * inserted in the document use the {@link #add(ObjectId)} method instead.
      * </p>
      * 
      * @param id
      *            The ObjectId to add.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code id} is <code>null</code>.
      */
     public ArrayBuilder addObjectId(ObjectId id)
             throws IllegalArgumentException;
 
     /**
      * Adds a regular expression element.
      * <p>
      * This method throws an {@link IllegalArgumentException} if the
      * {@code pattern} is <code>null</code>. If you would prefer a
      * {@link NullElement} be inserted in the document use the
      * {@link #add(Pattern)} method instead.
      * </p>
      * 
      * @param pattern
      *            The pattern for the regular expression.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code pattern} is <code>null</code>.
      */
     public ArrayBuilder addRegularExpression(Pattern pattern)
             throws IllegalArgumentException;
 
     /**
      * Adds a regular expression element.
      * 
      * @param pattern
      *            The pattern for the regular expression.
      * @param options
      *            The regular expression options. See the BSON specification for
      *            details. These may be <code>null</code>.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code pattern} is <code>null</code>. The options may be
      *             <code>null</code>.
      */
     public ArrayBuilder addRegularExpression(String pattern, String options)
             throws IllegalArgumentException;
 
     /**
      * Adds a string element.
      * <p>
      * This method throws an {@link IllegalArgumentException} if the
      * {@code value} is <code>null</code>. If you would prefer a
      * {@link NullElement} be inserted in the document use the
      * {@link #add(String)} method instead.
      * </p>
      * 
      * @param value
      *            The string value.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code value} is <code>null</code>.
      */
     public ArrayBuilder addString(String value) throws IllegalArgumentException;
 
     /**
      * Adds a symbol element.
      * 
      * @param symbol
      *            The symbol value.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If {@code symbol} is <code>null</code>.
      */
     public ArrayBuilder addSymbol(String symbol)
             throws IllegalArgumentException;
 
     /**
      * Adds a timestamp element. The timestamp is the number of milliseconds
      * since the Unix epoch.
      * 
      * @param timestamp
      *            The number of milliseconds since the Unix epoch.
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder addTimestamp(long timestamp);
 
     /**
      * Adds a (sub-type 4) {@link UUID} binary element.
      * <p>
      * This method throws an {@link IllegalArgumentException} if the
      * {@code uuid} is <code>null</code>. If you would prefer a
      * {@link NullElement} be inserted in the array use the {@link #add(UUID)}
      * method instead.
      * </p>
      * 
      * @param uuid
      *            The {@link UUID} to add.
      * @return This {@link ArrayBuilder} for method chaining.
      * @throws IllegalArgumentException
      *             If the {@code uuid} is <code>null</code>.
      */
     public ArrayBuilder addUuid(UUID uuid) throws IllegalArgumentException;
 
     /**
      * Returns the array of {@link Element}s being constructed.
      * 
      * @return The constructed array of {@link Element}.
      */
     public Element[] build();
 
     /**
      * Pushes a context for constructing a sub-document.
      * 
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public DocumentBuilder push();
 
     /**
      * Pushes a context for constructing a sub-array.
      * 
      * @return This {@link ArrayBuilder} for method chaining.
      */
     public ArrayBuilder pushArray();
 
     /**
      * {@inheritDoc}
      * <p>
      * Overridden to return an {@link ArrayBuilder} instance.
      * </p>
      */
     @Override
     public ArrayBuilder reset();
 }

1		/*
2		* #%L
3		* ArrayBuilder.java - mongodb-async-driver - Allanbank Consulting, Inc.
4		* %%
5		* Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
6		* %%
7		* Licensed under the Apache License, Version 2.0 (the "License");
8		* you may not use this file except in compliance with the License.
9		* You may obtain a copy of the License at
10		*
11		* http://www.apache.org/licenses/LICENSE-2.0
12		*
13		* Unless required by applicable law or agreed to in writing, software
14		* distributed under the License is distributed on an "AS IS" BASIS,
15		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16		* See the License for the specific language governing permissions and
17		* limitations under the License.
18		* #L%
19		*/
20		package com.allanbank.mongodb.bson.builder;
21
22		import java.util.Date;
23		import java.util.UUID;
24		import java.util.regex.Pattern;
25
26		import com.allanbank.mongodb.bson.DocumentAssignable;
27		import com.allanbank.mongodb.bson.Element;
28		import com.allanbank.mongodb.bson.ElementAssignable;
29		import com.allanbank.mongodb.bson.element.DocumentElement;
30		import com.allanbank.mongodb.bson.element.NullElement;
31		import com.allanbank.mongodb.bson.element.ObjectId;
32
33		/**
34		* Interface for a builder used to construct a BSON array.
35		*
36		* @api.yes This interface is part of the driver's API. Public and protected
37		* members will be deprecated for at least 1 non-bugfix release
38		* (version numbers are <major>.<minor>.<bugfix>)
39		* before being removed or modified.
40		* @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved
41		*/
42		public interface ArrayBuilder extends Builder {
43
44		/**
45		* Adds a boolean element.
46		* <p>
47		* This is a equivalent to {@link #addBoolean(boolean)} but less verbose.
48		* </p>
49		*
50		* @param value
51		* The boolean value.
52		* @return This {@link ArrayBuilder} for method chaining.
53		*/
54		public ArrayBuilder add(boolean value);
55
56		/**
57		* Adds a binary element.
58		* <p>
59		* This is a equivalent to {@link #addBinary(byte, byte[])} but less
60		* verbose.
61		* </p>
62		*
63		* @param subType
64		* The sub-type for the binary data.
65		* @param data
66		* The binary value.
67		* @return This {@link ArrayBuilder} for method chaining.
68		* @throws IllegalArgumentException
69		* If {@code data} is <code>null</code>.
70		*/
71		public ArrayBuilder add(byte subType, byte[] data)
72		throws IllegalArgumentException;
73
74		/**
75		* Adds a binary element using sub-type zero (the default).
76		* <p>
77		* This is a equivalent to {@link #addBinary(byte[])} but will insert a
78		* {@link NullElement} if the {@code data} is <code>null</code> instead of
79		* throwing an {@link IllegalArgumentException}.
80		* </p>
81		*
82		* @param data
83		* The binary value.
84		* @return This {@link ArrayBuilder} for method chaining.
85		*/
86		public ArrayBuilder add(byte[] data);
87
88		/**
89		* Adds a timestamp element. The timestamp is the number of milliseconds
90		* since the Unix epoch.
91		* <p>
92		* This is a equivalent to {@link #addTimestamp(long)
93		* addTimeStamp(timestamp.getTime())} but will insert a {@link NullElement}
94		* if the {@code timestamp} is <code>null</code> instead of throwing an
95		* {@link IllegalArgumentException}.
96		* </p>
97		*
98		* @param timestamp
99		* The number of milliseconds since the Unix epoch.
100		* @return This {@link ArrayBuilder} for method chaining.
101		*/
102		public ArrayBuilder add(Date timestamp);
103
104		/**
105		* Adds a pre-constructed document to the array.
106		* <p>
107		* This is a equivalent to {@link #addDocument(DocumentAssignable)} but will
108		* insert a {@link NullElement} if the {@code document} is <code>null</code>
109		* instead of throwing an {@link IllegalArgumentException}.
110		* </p>
111		*
112		* @param document
113		* The document to add to the array.
114		* @return This {@link ArrayBuilder} for method chaining.
115		*/
116		public ArrayBuilder add(DocumentAssignable document);
117
118		/**
119		* Adds a pre-constructed {@link DocumentElement} to the array.
120		* <p>
121		* This is a equivalent to {@link #addDocument(DocumentAssignable)} but will
122		* insert a {@link NullElement} if the {@code document} is <code>null</code>
123		* instead of throwing an {@link IllegalArgumentException}.
124		* </p>
125		* <p>
126		* Added to resolve ambiguity between the {@link DocumentElement} being both
127		* a {@link DocumentAssignable} and an {@link ElementAssignable}.
128		* </p>
129		*
130		* @param document
131		* The document to add to the array.
132		* @return This {@link ArrayBuilder} for method chaining.
133		*/
134		public ArrayBuilder add(DocumentElement document);
135
136		/**
137		* Adds a double element.
138		* <p>
139		* This is a equivalent to {@link #addDouble(double)} but less verbose.
140		* </p>
141		*
142		* @param value
143		* The double value.
144		* @return This {@link ArrayBuilder} for method chaining.
145		*/
146		public ArrayBuilder add(double value);
147
148		/**
149		* Adds a pre-built element to the document.
150		*
151		* @param element
152		* The element to add.
153		* @return This {@link ArrayBuilder} for method chaining.
154		* @throws IllegalArgumentException
155		* If {@code element} is <code>null</code>.
156		*/
157		public ArrayBuilder add(ElementAssignable element)
158		throws IllegalArgumentException;
159
160		/**
161		* Adds a integer (32-bit signed) element.
162		* <p>
163		* This is a equivalent to {@link #addInteger(int)} but less verbose.
164		* </p>
165		*
166		* @param value
167		* The integer value.
168		* @return This {@link ArrayBuilder} for method chaining.
169		*/
170		public ArrayBuilder add(int value);
171
172		/**
173		* Adds a long (64-bit signed) element.
174		* <p>
175		* This is a equivalent to {@link #addLong(long)} but less verbose.
176		* </p>
177		*
178		* @param value
179		* The long value.
180		* @return This {@link ArrayBuilder} for method chaining.
181		*/
182		public ArrayBuilder add(long value);
183
184		/**
185		* Adds the value to the array after trying to coerce the value into the
186		* best possible element type. If the coercion fails then an
187		* {@link IllegalArgumentException} is thrown.
188		* <p>
189		* This method does type inspection which can be slow. It is generally much
190		* faster to use the type specific methods of this interface.
191		* </p>
192		*
193		* @param value
194		* The Object value to coerce into an element.
195		* @return This {@link ArrayBuilder} for method chaining.
196		* @throws IllegalArgumentException
197		* If the {@code value} cannot be coerced into an element type.
198		*/
199		public ArrayBuilder add(Object value) throws IllegalArgumentException;
200
201		/**
202		* Adds an ObjectId element.
203		* <p>
204		* This is a equivalent to {@link #addObjectId(ObjectId)} but will insert a
205		* {@link NullElement} if the {@code id} is <code>null</code> instead of
206		* throwing an {@link IllegalArgumentException}.
207		* </p>
208		*
209		* @param id
210		* The ObjectId to add.
211		* @return This {@link ArrayBuilder} for method chaining.
212		*/
213		public ArrayBuilder add(ObjectId id);
214
215		/**
216		* Adds an ObjectId element.
217		* <p>
218		* This is a equivalent to {@link #addRegularExpression(Pattern)} but will
219		* insert a {@link NullElement} if the {@code pattern} is <code>null</code>
220		* instead of throwing an {@link IllegalArgumentException}.
221		* </p>
222		*
223		* @param pattern
224		* The pattern for the regular expression.
225		* @return This {@link ArrayBuilder} for method chaining.
226		*/
227		public ArrayBuilder add(Pattern pattern);
228
229		/**
230		* Adds a string element.
231		* <p>
232		* This is a equivalent to {@link #addString(String)} but will insert a
233		* {@link NullElement} if the {@code value} is <code>null</code> instead of
234		* throwing an {@link IllegalArgumentException}.
235		* </p>
236		*
237		* @param value
238		* The string value.
239		* @return This {@link ArrayBuilder} for method chaining.
240		*/
241		public ArrayBuilder add(String value);
242
243		/**
244		* Adds a deprecated DBPointer element.
245		* <p>
246		* This is a equivalent to {@link #addDBPointer(String, String, ObjectId)}
247		* but less verbose.
248		* </p>
249		*
250		* @param databaseName
251		* The name of the database containing the document.
252		* @param collectionName
253		* The name of the collection containing the document.
254		* @param id
255		* The id for the document.
256		* @return This {@link ArrayBuilder} for method chaining.
257		* @throws IllegalArgumentException
258		* If {@code databaseName}, {@code collectionName}, or
259		* {@code id} is <code>null</code>.
260		*
261		* @deprecated See BSON specification.
262		*/
263		@Deprecated
264		public ArrayBuilder add(String databaseName, String collectionName,
265		ObjectId id) throws IllegalArgumentException;
266
267		/**
268		* Adds a (sub-type 4) {@link UUID} binary element.
269		* <p>
270		* This is a equivalent to {@link #addUuid(UUID)} but will insert a
271		* {@link NullElement} if the {@code uuid} is <code>null</code> instead of
272		* throwing an {@link IllegalArgumentException}.
273		* </p>
274		*
275		* @param uuid
276		* The {@link UUID} to add.
277		* @return This {@link ArrayBuilder} for method chaining.
278		*/
279		public ArrayBuilder add(UUID uuid);
280
281		/**
282		* Adds a binary element.
283		*
284		* @param subType
285		* The sub-type for the binary data.
286		* @param data
287		* The binary value.
288		* @return This {@link ArrayBuilder} for method chaining.
289		* @throws IllegalArgumentException
290		* If {@code data} is <code>null</code>.
291		*/
292		public ArrayBuilder addBinary(byte subType, byte[] data)
293		throws IllegalArgumentException;
294
295		/**
296		* Adds a binary element using sub-type zero (the default).
297		* <p>
298		* This method throws an {@link IllegalArgumentException} if the
299		* {@code data} is <code>null</code>. If you would prefer a
300		* {@link NullElement} be inserted in the document use the
301		* {@link #add(byte[])} method instead.
302		* </p>
303		*
304		* @param data
305		* The binary value.
306		* @return This {@link ArrayBuilder} for method chaining.
307		* @throws IllegalArgumentException
308		* If {@code data} is <code>null</code>.
309		*/
310		public ArrayBuilder addBinary(byte[] data) throws IllegalArgumentException;
311
312		/**
313		* Adds a boolean element.
314		*
315		* @param value
316		* The boolean value.
317		* @return This {@link ArrayBuilder} for method chaining.
318		*/
319		public ArrayBuilder addBoolean(boolean value);
320
321		/**
322		* Adds a deprecated DBPointer element.
323		*
324		* @param databaseName
325		* The name of the database containing the document.
326		* @param collectionName
327		* The name of the collection containing the document.
328		* @param id
329		* The id for the document.
330		* @return This {@link ArrayBuilder} for method chaining.
331		* @throws IllegalArgumentException
332		* If {@code databaseName}, {@code collectionName}, or
333		* {@code id} is <code>null</code>.
334		*
335		* @deprecated See BSON specification.
336		*/
337		@Deprecated
338		public ArrayBuilder addDBPointer(String databaseName,
339		String collectionName, ObjectId id) throws IllegalArgumentException;
340
341		/**
342		* Adds a pre-constructed document to the array.
343		* <p>
344		* This method throws an {@link IllegalArgumentException} if the
345		* {@code document} is <code>null</code>. If you would prefer a
346		* {@link NullElement} be inserted in the document use the
347		* {@link #add(DocumentAssignable)} method instead.
348		* </p>
349		*
350		* @param document
351		* The document to add to the array.
352		* @return This {@link ArrayBuilder} for method chaining.
353		* @throws IllegalArgumentException
354		* If {@code document} is <code>null</code>.
355		*/
356		public ArrayBuilder addDocument(DocumentAssignable document)
357		throws IllegalArgumentException;
358
359		/**
360		* Adds a double element.
361		*
362		* @param value
363		* The double value.
364		* @return This {@link ArrayBuilder} for method chaining.
365		*/
366		public ArrayBuilder addDouble(double value);
367
368		/**
369		* Adds a integer (32-bit signed) element.
370		*
371		* @param value
372		* The integer value.
373		* @return This {@link ArrayBuilder} for method chaining.
374		*/
375		public ArrayBuilder addInteger(int value);
376
377		/**
378		* Adds a JavaScript element.
379		*
380		* @param code
381		* The java script code.
382		* @return This {@link ArrayBuilder} for method chaining.
383		* @throws IllegalArgumentException
384		* If {@code code} is <code>null</code>.
385		*/
386		public ArrayBuilder addJavaScript(String code)
387		throws IllegalArgumentException;
388
389		/**
390		* Adds a JavaScript with Scope element.
391		*
392		* @param code
393		* The java script code.
394		* @param scope
395		* The scope for the JacaScript code.
396		* @return This {@link ArrayBuilder} for method chaining.
397		* @throws IllegalArgumentException
398		* If {@code code} or {@code scope} is <code>null</code>.
399		*/
400		public ArrayBuilder addJavaScript(String code, DocumentAssignable scope)
401		throws IllegalArgumentException;
402
403		/**
404		* Adds a legacy (sub-type 3) {@link UUID} binary element.
405		* <p>
406		* This method throws an {@link IllegalArgumentException} if the
407		* {@code uuid} is <code>null</code>.
408		* </p>
409		*
410		* @param uuid
411		* The {@link UUID} to add.
412		* @return This {@link ArrayBuilder} for method chaining.
413		* @throws IllegalArgumentException
414		* If the {@code uuid} is <code>null</code>.
415		*/
416		public ArrayBuilder addLegacyUuid(UUID uuid)
417		throws IllegalArgumentException;
418
419		/**
420		* Adds a long (64-bit signed) element.
421		*
422		* @param value
423		* The long value.
424		* @return This {@link ArrayBuilder} for method chaining.
425		*/
426		public ArrayBuilder addLong(long value);
427
428		/**
429		* Adds a minimum key value element. Used as an absolute upper bounds.
430		*
431		* @return This {@link ArrayBuilder} for method chaining.
432		*/
433		public ArrayBuilder addMaxKey();
434
435		/**
436		* Adds a minimum key value element. Used as an absolute lower bounds.
437		*
438		* @return This {@link ArrayBuilder} for method chaining.
439		*/
440		public ArrayBuilder addMinKey();
441
442		/**
443		* Adds a MongoDB Timestamp element.
444		*
445		* @param value
446		* The mongoDB timstamp value.
447		* @return This {@link ArrayBuilder} for method chaining.
448		*/
449		public ArrayBuilder addMongoTimestamp(long value);
450
451		/**
452		* Adds a <code>null</code> valued element.
453		*
454		* @return This {@link ArrayBuilder} for method chaining.
455		*/
456		public ArrayBuilder addNull();
457
458		/**
459		* Adds an ObjectId element.
460		* <p>
461		* This method throws an {@link IllegalArgumentException} if the {@code id}
462		* is <code>null</code>. If you would prefer a {@link NullElement} be
463		* inserted in the document use the {@link #add(ObjectId)} method instead.
464		* </p>
465		*
466		* @param id
467		* The ObjectId to add.
468		* @return This {@link ArrayBuilder} for method chaining.
469		* @throws IllegalArgumentException
470		* If {@code id} is <code>null</code>.
471		*/
472		public ArrayBuilder addObjectId(ObjectId id)
473		throws IllegalArgumentException;
474
475		/**
476		* Adds a regular expression element.
477		* <p>
478		* This method throws an {@link IllegalArgumentException} if the
479		* {@code pattern} is <code>null</code>. If you would prefer a
480		* {@link NullElement} be inserted in the document use the
481		* {@link #add(Pattern)} method instead.
482		* </p>
483		*
484		* @param pattern
485		* The pattern for the regular expression.
486		* @return This {@link ArrayBuilder} for method chaining.
487		* @throws IllegalArgumentException
488		* If {@code pattern} is <code>null</code>.
489		*/
490		public ArrayBuilder addRegularExpression(Pattern pattern)
491		throws IllegalArgumentException;
492
493		/**
494		* Adds a regular expression element.
495		*
496		* @param pattern
497		* The pattern for the regular expression.
498		* @param options
499		* The regular expression options. See the BSON specification for
500		* details. These may be <code>null</code>.
501		* @return This {@link ArrayBuilder} for method chaining.
502		* @throws IllegalArgumentException
503		* If {@code pattern} is <code>null</code>. The options may be
504		* <code>null</code>.
505		*/
506		public ArrayBuilder addRegularExpression(String pattern, String options)
507		throws IllegalArgumentException;
508
509		/**
510		* Adds a string element.
511		* <p>
512		* This method throws an {@link IllegalArgumentException} if the
513		* {@code value} is <code>null</code>. If you would prefer a
514		* {@link NullElement} be inserted in the document use the
515		* {@link #add(String)} method instead.
516		* </p>
517		*
518		* @param value
519		* The string value.
520		* @return This {@link ArrayBuilder} for method chaining.
521		* @throws IllegalArgumentException
522		* If {@code value} is <code>null</code>.
523		*/
524		public ArrayBuilder addString(String value) throws IllegalArgumentException;
525
526		/**
527		* Adds a symbol element.
528		*
529		* @param symbol
530		* The symbol value.
531		* @return This {@link ArrayBuilder} for method chaining.
532		* @throws IllegalArgumentException
533		* If {@code symbol} is <code>null</code>.
534		*/
535		public ArrayBuilder addSymbol(String symbol)
536		throws IllegalArgumentException;
537
538		/**
539		* Adds a timestamp element. The timestamp is the number of milliseconds
540		* since the Unix epoch.
541		*
542		* @param timestamp
543		* The number of milliseconds since the Unix epoch.
544		* @return This {@link ArrayBuilder} for method chaining.
545		*/
546		public ArrayBuilder addTimestamp(long timestamp);
547
548		/**
549		* Adds a (sub-type 4) {@link UUID} binary element.
550		* <p>
551		* This method throws an {@link IllegalArgumentException} if the
552		* {@code uuid} is <code>null</code>. If you would prefer a
553		* {@link NullElement} be inserted in the array use the {@link #add(UUID)}
554		* method instead.
555		* </p>
556		*
557		* @param uuid
558		* The {@link UUID} to add.
559		* @return This {@link ArrayBuilder} for method chaining.
560		* @throws IllegalArgumentException
561		* If the {@code uuid} is <code>null</code>.
562		*/
563		public ArrayBuilder addUuid(UUID uuid) throws IllegalArgumentException;
564
565		/**
566		* Returns the array of {@link Element}s being constructed.
567		*
568		* @return The constructed array of {@link Element}.
569		*/
570		public Element[] build();
571
572		/**
573		* Pushes a context for constructing a sub-document.
574		*
575		* @return This {@link ArrayBuilder} for method chaining.
576		*/
577		public DocumentBuilder push();
578
579		/**
580		* Pushes a context for constructing a sub-array.
581		*
582		* @return This {@link ArrayBuilder} for method chaining.
583		*/
584		public ArrayBuilder pushArray();
585
586		/**
587		* {@inheritDoc}
588		* <p>
589		* Overridden to return an {@link ArrayBuilder} instance.
590		* </p>
591		*/
592		@Override
593		public ArrayBuilder reset();
594		}