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 }