1 /*
2 * #%L
3 * DocumentBuilder.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.Document;
27 import com.allanbank.mongodb.bson.DocumentAssignable;
28 import com.allanbank.mongodb.bson.Element;
29 import com.allanbank.mongodb.bson.ElementAssignable;
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 document.
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 DocumentBuilder extends Builder, DocumentAssignable {
43 /**
44 * Adds a pre-built element to the document.
45 *
46 * @param element
47 * The element to add.
48 * @return This {@link DocumentBuilder} for method chaining.
49 * @throws IllegalArgumentException
50 * If the {@code element} is <code>null</code>.
51 */
52 public DocumentBuilder add(ElementAssignable element)
53 throws IllegalArgumentException;
54
55 /**
56 * Adds a boolean element.
57 * <p>
58 * This is a equivalent to {@link #addBoolean(String,boolean)} but less
59 * verbose.
60 * </p>
61 *
62 * @param name
63 * The name of the element.
64 * @param value
65 * The boolean value.
66 * @return This {@link DocumentBuilder} for method chaining.
67 * @throws IllegalArgumentException
68 * If the {@code name} is <code>null</code>.
69 */
70 public DocumentBuilder add(String name, boolean value)
71 throws IllegalArgumentException;
72
73 /**
74 * Adds a binary element.
75 * <p>
76 * This is a equivalent to {@link #addBinary(String,byte, byte[])} but less
77 * verbose.
78 * </p>
79 *
80 * @param name
81 * The name of the element.
82 * @param subType
83 * The sub-type for the binary data.
84 * @param data
85 * The binary value.
86 * @return This {@link DocumentBuilder} for method chaining.
87 * @throws IllegalArgumentException
88 * If the {@code name} or {@code data} is <code>null</code>.
89 */
90 public DocumentBuilder add(String name, byte subType, byte[] data)
91 throws IllegalArgumentException;
92
93 /**
94 * Adds a binary element using sub-type zero (the default).
95 * <p>
96 * This is a equivalent to {@link #addBinary(String,byte[])} but will insert
97 * a {@link NullElement} if the {@code data} is <code>null</code> instead of
98 * throwing an {@link IllegalArgumentException}.
99 * </p>
100 *
101 * @param name
102 * The name of the element.
103 * @param data
104 * The binary value.
105 * @return This {@link DocumentBuilder} for method chaining.
106 * @throws IllegalArgumentException
107 * If the {@code name} is <code>null</code>.
108 */
109 public DocumentBuilder add(String name, byte[] data)
110 throws IllegalArgumentException;
111
112 /**
113 * Adds a timestamp element. The timestamp is the number of milliseconds
114 * since the Unix epoch.
115 * <p>
116 * This is a equivalent to {@link #addTimestamp(String,long)
117 * addTimeStamp(timestamp.getTime())} but will insert a {@link NullElement}
118 * if the {@code timestamp} is <code>null</code> instead of throwing an
119 * {@link IllegalArgumentException}.
120 * </p>
121 *
122 * @param name
123 * The name of the element.
124 * @param timestamp
125 * The number of milliseconds since the Unix epoch.
126 * @return This {@link DocumentBuilder} for method chaining.
127 * @throws IllegalArgumentException
128 * If the {@code name} is <code>null</code>.
129 */
130 public DocumentBuilder add(String name, Date timestamp)
131 throws IllegalArgumentException;
132
133 /**
134 * Adds a pre-constructed document to the array.
135 * <p>
136 * This is a equivalent to {@link #addDocument(String,DocumentAssignable)}
137 * but will insert a {@link NullElement} if the {@code document} is
138 * <code>null</code> instead of throwing an {@link IllegalArgumentException}
139 * .
140 * </p>
141 *
142 * @param name
143 * The name of the element.
144 * @param document
145 * The document to add to the array.
146 * @return This {@link DocumentBuilder} for method chaining.
147 * @throws IllegalArgumentException
148 * If the {@code name} is <code>null</code>.
149 */
150 public DocumentBuilder add(String name, DocumentAssignable document)
151 throws IllegalArgumentException;
152
153 /**
154 * Adds a double element.
155 * <p>
156 * This is a equivalent to {@link #addDouble(String,double)} but less
157 * verbose.
158 * </p>
159 *
160 * @param name
161 * The name of the element.
162 * @param value
163 * The double value.
164 * @return This {@link DocumentBuilder} for method chaining.
165 * @throws IllegalArgumentException
166 * If the {@code name} is <code>null</code>.
167 */
168 public DocumentBuilder add(String name, double value)
169 throws IllegalArgumentException;
170
171 /**
172 * Adds a integer (32-bit signed) element.
173 * <p>
174 * This is a equivalent to {@link #addInteger(String,int)} but less verbose.
175 * </p>
176 *
177 * @param name
178 * The name of the element.
179 * @param value
180 * The integer value.
181 * @return This {@link DocumentBuilder} for method chaining.
182 * @throws IllegalArgumentException
183 * If the {@code name} is <code>null</code>.
184 */
185 public DocumentBuilder add(String name, int value)
186 throws IllegalArgumentException;
187
188 /**
189 * Adds a long (64-bit signed) element.
190 * <p>
191 * This is a equivalent to {@link #addLong(String,long)} but less verbose.
192 * </p>
193 *
194 * @param name
195 * The name of the element.
196 * @param value
197 * The long value.
198 * @return This {@link DocumentBuilder} for method chaining.
199 * @throws IllegalArgumentException
200 * If the {@code name} is <code>null</code>.
201 */
202 public DocumentBuilder add(String name, long value)
203 throws IllegalArgumentException;
204
205 /**
206 * Adds the value to the document after trying to coerce the value into the
207 * best possible element type. If the coercion fails then an
208 * {@link IllegalArgumentException} is thrown.
209 * <p>
210 * This method does type inspection which can be slow. It is generally much
211 * faster to use the type specific methods of this interface.
212 * </p>
213 *
214 * @param name
215 * The name of the element.
216 * @param value
217 * The Object value to coerce into an element.
218 * @return This {@link DocumentBuilder} for method chaining.
219 * @throws IllegalArgumentException
220 * If the {@code name} is <code>null</code> or the {@code value}
221 * cannot be coerced into an element type.
222 */
223 public DocumentBuilder add(String name, Object value)
224 throws IllegalArgumentException;
225
226 /**
227 * Adds an ObjectId element.
228 * <p>
229 * This is a equivalent to {@link #addObjectId(String,ObjectId)} but will
230 * insert a {@link NullElement} if the {@code id} is <code>null</code>
231 * instead of throwing an {@link IllegalArgumentException}.
232 * </p>
233 *
234 * @param name
235 * The name of the element.
236 * @param id
237 * The ObjectId to add.
238 * @return This {@link DocumentBuilder} for method chaining.
239 * @throws IllegalArgumentException
240 * If the {@code name} or {@code id} is <code>null</code>.
241 */
242 public DocumentBuilder add(String name, ObjectId id)
243 throws IllegalArgumentException;
244
245 /**
246 * Adds an ObjectId element.
247 * <p>
248 * This is a equivalent to {@link #addRegularExpression(String,Pattern)} but
249 * will insert a {@link NullElement} if the {@code pattern} is
250 * <code>null</code> instead of throwing an {@link IllegalArgumentException}
251 * .
252 * </p>
253 *
254 * @param name
255 * The name of the element.
256 * @param pattern
257 * The pattern for the regular expression.
258 * @return This {@link DocumentBuilder} for method chaining.
259 * @throws IllegalArgumentException
260 * If the {@code name} is <code>null</code>.
261 */
262 public DocumentBuilder add(String name, Pattern pattern)
263 throws IllegalArgumentException;
264
265 /**
266 * Adds a string element.
267 * <p>
268 * This is a equivalent to {@link #addString(String,String)} but will insert
269 * a {@link NullElement} if the {@code value} is <code>null</code> instead
270 * of throwing an {@link IllegalArgumentException}.
271 * </p>
272 *
273 * @param name
274 * The name of the element.
275 * @param value
276 * The string value.
277 * @return This {@link DocumentBuilder} for method chaining.
278 * @throws IllegalArgumentException
279 * If the {@code name} is <code>null</code>.
280 */
281 public DocumentBuilder add(String name, String value)
282 throws IllegalArgumentException;
283
284 /**
285 * Adds a deprecated DBPointer element.
286 * <p>
287 * This is a equivalent to
288 * {@link #addDBPointer(String,String, String, ObjectId)} but less verbose.
289 * </p>
290 *
291 * @param name
292 * The name of the element.
293 * @param databaseName
294 * The name of the database containing the document.
295 * @param collectionName
296 * The name of the collection containing the document.
297 * @param id
298 * The id for the document.
299 * @return This {@link DocumentBuilder} for method chaining.
300 * @throws IllegalArgumentException
301 * If the {@code name}, {@code databaseName},
302 * {@code collectionName}, or {@code id} is <code>null</code>.
303 *
304 * @deprecated See BSON specification.
305 */
306 @Deprecated
307 public DocumentBuilder add(String name, String databaseName,
308 String collectionName, ObjectId id) throws IllegalArgumentException;
309
310 /**
311 * Adds a (sub-type 4) {@link UUID} binary element.
312 * <p>
313 * This is a equivalent to {@link #addUuid(String,UUID)} but will insert a
314 * {@link NullElement} if the {@code uuid} is <code>null</code> instead of
315 * throwing an {@link IllegalArgumentException}.
316 * </p>
317 *
318 * @param name
319 * The name of the element.
320 * @param uuid
321 * The {@link UUID} to add.
322 * @return This {@link DocumentBuilder} for method chaining.
323 * @throws IllegalArgumentException
324 * If the {@code name} is <code>null</code>.
325 */
326 public DocumentBuilder add(String name, UUID uuid)
327 throws IllegalArgumentException;
328
329 /**
330 * Adds a binary element using sub-type zero (the default).
331 *
332 * @param name
333 * The name of the element.
334 * @param subType
335 * The sub-type for the binary data.
336 * @param data
337 * The binary value.
338 * @return This {@link DocumentBuilder} for method chaining.
339 * @throws IllegalArgumentException
340 * If the {@code name} or {@code data} is <code>null</code>.
341 */
342 public DocumentBuilder addBinary(String name, byte subType, byte[] data)
343 throws IllegalArgumentException;
344
345 /**
346 * Adds a binary element using sub-type zero (the default).
347 * <p>
348 * This method throws an {@link IllegalArgumentException} if the
349 * {@code data} is <code>null</code>. If you would prefer a
350 * {@link NullElement} be inserted in the document use the
351 * {@link #add(String, byte[])} method instead.
352 * </p>
353 *
354 * @param name
355 * The name of the element.
356 * @param data
357 * The binary value.
358 * @return This {@link DocumentBuilder} for method chaining.
359 * @throws IllegalArgumentException
360 * If the {@code name} or {@code value} is <code>null</code>.
361 */
362 public DocumentBuilder addBinary(String name, byte[] data)
363 throws IllegalArgumentException;
364
365 /**
366 * Adds a boolean element.
367 *
368 * @param name
369 * The name of the element.
370 * @param value
371 * The boolean value.
372 * @return This {@link DocumentBuilder} for method chaining.
373 * @throws IllegalArgumentException
374 * If the {@code name} is <code>null</code>.
375 */
376 public DocumentBuilder addBoolean(String name, boolean value)
377 throws IllegalArgumentException;
378
379 /**
380 * Adds a deprecated DBPointer element.
381 *
382 * @param name
383 * The name of the element.
384 * @param databaseName
385 * The name of the database containing the document.
386 * @param collectionName
387 * The name of the collection containing the document.
388 * @param id
389 * The id for the document.
390 * @return This {@link DocumentBuilder} for method chaining.
391 * @throws IllegalArgumentException
392 * If the {@code name}, {@code databaseName},
393 * {@code collectionName}, or {@code id} is <code>null</code>.
394 *
395 * @deprecated See BSON specification.
396 */
397 @Deprecated
398 public DocumentBuilder addDBPointer(String name, String databaseName,
399 String collectionName, ObjectId id) throws IllegalArgumentException;
400
401 /**
402 * Adds a pre-built document element. Can also {@link #push(String)} a sub
403 * document.
404 * <p>
405 * This method throws an {@link IllegalArgumentException} if the
406 * {@code value} is <code>null</code>. If you would prefer a
407 * {@link NullElement} be inserted in the document use the
408 * {@link #add(String, DocumentAssignable)} method instead.
409 * </p>
410 *
411 * @param name
412 * The name of the element.
413 * @param value
414 * The document value.
415 * @return This {@link DocumentBuilder} for method chaining.
416 * @throws IllegalArgumentException
417 * If the {@code name} or {@code value} is <code>null</code>.
418 */
419 public DocumentBuilder addDocument(String name, DocumentAssignable value)
420 throws IllegalArgumentException;
421
422 /**
423 * Adds a double element.
424 *
425 * @param name
426 * The name of the element.
427 * @param value
428 * The double value.
429 * @return This {@link DocumentBuilder} for method chaining.
430 * @throws IllegalArgumentException
431 * If the {@code name} is <code>null</code>.
432 */
433 public DocumentBuilder addDouble(String name, double value)
434 throws IllegalArgumentException;
435
436 /**
437 * Adds a integer (32-bit signed) element.
438 *
439 * @param name
440 * The name of the element.
441 * @param value
442 * The integer value.
443 * @return This {@link DocumentBuilder} for method chaining.
444 * @throws IllegalArgumentException
445 * If the {@code name} is <code>null</code>.
446 */
447 public DocumentBuilder addInteger(String name, int value)
448 throws IllegalArgumentException;
449
450 /**
451 * Adds a JavaScript element.
452 *
453 * @param name
454 * The name of the element.
455 * @param code
456 * The java script code.
457 * @return This {@link DocumentBuilder} for method chaining.
458 * @throws IllegalArgumentException
459 * If the {@code name} or {@code code} is <code>null</code>.
460 */
461 public DocumentBuilder addJavaScript(String name, String code)
462 throws IllegalArgumentException;
463
464 /**
465 * Adds a JavaScript with Scope element.
466 *
467 * @param name
468 * The name of the element.
469 * @param code
470 * The java script code.
471 * @param scope
472 * The scope for the JacaScript code.
473 * @return This {@link DocumentBuilder} for method chaining.
474 * @throws IllegalArgumentException
475 * If the {@code name}, {@code value}, or {@code scope} is
476 * <code>null</code>.
477 */
478 public DocumentBuilder addJavaScript(String name, String code,
479 DocumentAssignable scope) throws IllegalArgumentException;
480
481 /**
482 * Adds a legacy (sub-type 3) {@link UUID} binary element.
483 * <p>
484 * This method throws an {@link IllegalArgumentException} if the
485 * {@code uuid} is <code>null</code>.
486 * </p>
487 *
488 * @param name
489 * The name of the element.
490 * @param uuid
491 * The {@link UUID} to add.
492 * @return This {@link DocumentBuilder} for method chaining.
493 * @throws IllegalArgumentException
494 * If the {@code name} or {@code uuid} is <code>null</code>.
495 */
496 public DocumentBuilder addLegacyUuid(String name, UUID uuid)
497 throws IllegalArgumentException;
498
499 /**
500 * Adds a long (64-bit signed) element.
501 *
502 * @param name
503 * The name of the element.
504 * @param value
505 * The long value.
506 * @return This {@link DocumentBuilder} for method chaining.
507 * @throws IllegalArgumentException
508 * If the {@code name} is <code>null</code>.
509 */
510 public DocumentBuilder addLong(String name, long value)
511 throws IllegalArgumentException;
512
513 /**
514 * Adds a minimum key value element. Used as an absolute upper bounds.
515 *
516 * @param name
517 * The name of the element.
518 * @return This {@link DocumentBuilder} for method chaining.
519 * @throws IllegalArgumentException
520 * If the {@code name} is <code>null</code>.
521 */
522 public DocumentBuilder addMaxKey(String name)
523 throws IllegalArgumentException;
524
525 /**
526 * Adds a minimum key value element. Used as an absolute lower bounds.
527 *
528 * @param name
529 * The name of the element.
530 * @return This {@link DocumentBuilder} for method chaining.
531 * @throws IllegalArgumentException
532 * If the {@code name} is <code>null</code>.
533 */
534 public DocumentBuilder addMinKey(String name)
535 throws IllegalArgumentException;
536
537 /**
538 * Adds a MongoDB Timestamp element.
539 *
540 * @param name
541 * The name of the element.
542 * @param value
543 * The mongoDB timstamp value.
544 * @return This {@link DocumentBuilder} for method chaining.
545 * @throws IllegalArgumentException
546 * If the {@code name} is <code>null</code>.
547 */
548 public DocumentBuilder addMongoTimestamp(String name, long value)
549 throws IllegalArgumentException;
550
551 /**
552 * Adds a <code>null</code> valued element.
553 *
554 * @param name
555 * The name of the element.
556 * @return This {@link DocumentBuilder} for method chaining.
557 * @throws IllegalArgumentException
558 * If the {@code name} is <code>null</code>.
559 */
560 public DocumentBuilder addNull(String name) throws IllegalArgumentException;
561
562 /**
563 * Adds an ObjectId element.
564 * <p>
565 * This method throws an {@link IllegalArgumentException} if the {@code id}
566 * is <code>null</code>. If you would prefer a {@link NullElement} be
567 * inserted in the document use the {@link #add(String, ObjectId)} method
568 * instead.
569 * </p>
570 *
571 * @param name
572 * The name of the element.
573 * @param id
574 * The ObjectId to add.
575 * @return This {@link DocumentBuilder} for method chaining.
576 * @throws IllegalArgumentException
577 * If the {@code name} or {@code id} is <code>null</code>.
578 */
579 public DocumentBuilder addObjectId(String name, ObjectId id)
580 throws IllegalArgumentException;
581
582 /**
583 * Adds a regular expression element.
584 * <p>
585 * This method throws an {@link IllegalArgumentException} if the
586 * {@code pattern} is <code>null</code>. If you would prefer a
587 * {@link NullElement} be inserted in the document use the
588 * {@link #add(String, Pattern)} method instead.
589 * </p>
590 *
591 * @param name
592 * The name of the element.
593 * @param pattern
594 * The pattern for the regular expression.
595 * @return This {@link DocumentBuilder} for method chaining.
596 * @throws IllegalArgumentException
597 * If the {@code name} or {@code pattern} is <code>null</code>.
598 */
599 public DocumentBuilder addRegularExpression(String name, Pattern pattern)
600 throws IllegalArgumentException;
601
602 /**
603 * Adds a regular expression element.
604 *
605 * @param name
606 * The name of the element.
607 * @param pattern
608 * The pattern for the regular expression.
609 * @param options
610 * The regular expression options. See the BSON specification for
611 * details. The options may be <code>null</code>.
612 * @return This {@link DocumentBuilder} for method chaining.
613 * @throws IllegalArgumentException
614 * If the {@code name} or {@code pattern} is <code>null</code>.
615 * Note the {@code options} may be <code>null</code>.
616 */
617 public DocumentBuilder addRegularExpression(String name, String pattern,
618 String options) throws IllegalArgumentException;
619
620 /**
621 * Adds a string element.
622 * <p>
623 * This method throws an {@link IllegalArgumentException} if the
624 * {@code value} is <code>null</code>. If you would prefer a
625 * {@link NullElement} be inserted in the document use the
626 * {@link #add(String, String)} method instead.
627 * </p>
628 *
629 * @param name
630 * The name of the element.
631 * @param value
632 * The string value.
633 * @return This {@link DocumentBuilder} for method chaining.
634 * @throws IllegalArgumentException
635 * If the {@code name} or {@code value} is <code>null</code>.
636 */
637 public DocumentBuilder addString(String name, String value)
638 throws IllegalArgumentException;
639
640 /**
641 * Adds a symbol element.
642 *
643 * @param name
644 * The name of the element.
645 * @param symbol
646 * The symbol value.
647 * @return This {@link DocumentBuilder} for method chaining.
648 * @throws IllegalArgumentException
649 * If the {@code name} or {@code symbol} is <code>null</code>.
650 */
651 public DocumentBuilder addSymbol(String name, String symbol)
652 throws IllegalArgumentException;
653
654 /**
655 * Adds a timestamp element. The timestamp is the number of milliseconds
656 * since the Unix epoch.
657 *
658 * @param name
659 * The name of the element.
660 * @param timestamp
661 * The number of milliseconds since the Unix epoch.
662 * @return This {@link DocumentBuilder} for method chaining.
663 * @throws IllegalArgumentException
664 * If the {@code name} is <code>null</code>.
665 */
666 public DocumentBuilder addTimestamp(String name, long timestamp)
667 throws IllegalArgumentException;
668
669 /**
670 * Adds a (sub-type 4) {@link UUID} binary element.
671 * <p>
672 * This method throws an {@link IllegalArgumentException} if the
673 * {@code uuid} is <code>null</code>. If you would prefer a
674 * {@link NullElement} be inserted in the document use the
675 * {@link #add(String, UUID)} method instead.
676 * </p>
677 *
678 * @param name
679 * The name of the element.
680 * @param uuid
681 * The {@link UUID} to add.
682 * @return This {@link DocumentBuilder} for method chaining.
683 * @throws IllegalArgumentException
684 * If the {@code name} or {@code uuid} is <code>null</code>.
685 */
686 public DocumentBuilder addUuid(String name, UUID uuid)
687 throws IllegalArgumentException;
688
689 /**
690 * Returns the {@link Document} being constructed.
691 *
692 * @return The constructed {@link Document}.
693 */
694 public Document build();
695
696 /**
697 * Pushes a context for constructing a sub-document.
698 *
699 * @param name
700 * The name of the sub-document.
701 * @return A {@link DocumentBuilder} for constructing the sub-document.
702 * @throws IllegalArgumentException
703 * If the {@code name} is <code>null</code>.
704 */
705 public DocumentBuilder push(String name) throws IllegalArgumentException;
706
707 /**
708 * Pushes a context for constructing a sub-array.
709 *
710 * @param name
711 * The name of the sub-array.
712 * @return A {@link ArrayBuilder} for constructing the sub-array.
713 * @throws IllegalArgumentException
714 * If the {@code name} is <code>null</code>.
715 */
716 public ArrayBuilder pushArray(String name) throws IllegalArgumentException;
717
718 /**
719 * Removes all {@link Element}s that have the provided name from the
720 * document being built.
721 * <p>
722 * Note that adding a new element with the same name adds that element to
723 * the end of document's element list.
724 * </p>
725 *
726 * @param name
727 * The name of the element to remove.
728 * @return This {@link DocumentBuilder} for method chaining.
729 */
730 public DocumentBuilder remove(String name);
731
732 /**
733 * {@inheritDoc}
734 * <p>
735 * Overridden to return an {@link DocumentBuilder} instance.
736 * </p>
737 */
738 @Override
739 public DocumentBuilder reset();
740 }