Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
MongoDatabase |
|
| 1.0;1 |
1 | /* | |
2 | * #%L | |
3 | * MongoDatabase.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; | |
21 | ||
22 | import java.util.List; | |
23 | ||
24 | import com.allanbank.mongodb.bson.Document; | |
25 | import com.allanbank.mongodb.bson.DocumentAssignable; | |
26 | ||
27 | /** | |
28 | * Interface for interacting with a MongoDB database. Primarily used to | |
29 | * {@link #getCollection(String) get} a {@link MongoCollection} . | |
30 | * | |
31 | * @api.yes This interface is part of the driver's API. Public and protected | |
32 | * members will be deprecated for at least 1 non-bugfix release | |
33 | * (version numbers are <major>.<minor>.<bugfix>) | |
34 | * before being removed or modified. | |
35 | * @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved | |
36 | */ | |
37 | public interface MongoDatabase { | |
38 | /** The name of the administration database. */ | |
39 | public static final String ADMIN_NAME = MongoClientConfiguration.ADMIN_DB_NAME; | |
40 | ||
41 | /** The name of the configuration database for a sharded configuration. */ | |
42 | public static final String CONFIG_NAME = "config"; | |
43 | ||
44 | /** The name of the local database. */ | |
45 | public static final String LOCAL_NAME = "local"; | |
46 | ||
47 | /** The name of the test database. */ | |
48 | public static final String TEST_NAME = "test"; | |
49 | ||
50 | /** | |
51 | * Creates the capped collection with the specified name and size on the | |
52 | * server. | |
53 | * | |
54 | * @param name | |
55 | * The name of the collection. | |
56 | * @param size | |
57 | * The size of the collection in bytes. | |
58 | * @return True if the collection was created, false otherwise (including it | |
59 | * already exists). | |
60 | * @throws MongoDbException | |
61 | * On a failure to create the collection. | |
62 | */ | |
63 | public boolean createCappedCollection(String name, long size) | |
64 | throws MongoDbException; | |
65 | ||
66 | /** | |
67 | * Creates the collection with the specified name on the server. | |
68 | * | |
69 | * @param name | |
70 | * The name of the collection. | |
71 | * @param options | |
72 | * The options for the collection being created. | |
73 | * @return True if the collection was created, false otherwise (including it | |
74 | * already exists). | |
75 | * @throws MongoDbException | |
76 | * On a failure to create the collection. | |
77 | */ | |
78 | public boolean createCollection(String name, DocumentAssignable options) | |
79 | throws MongoDbException; | |
80 | ||
81 | /** | |
82 | * Drops the database. | |
83 | * | |
84 | * @return True if the database was successfully dropped, false otherwise. | |
85 | * @throws MongoDbException | |
86 | * On an error issuing the drop command or in running the | |
87 | * command | |
88 | */ | |
89 | public boolean drop() throws MongoDbException; | |
90 | ||
91 | /** | |
92 | * Returns true if this database already exists on the server. | |
93 | * <p> | |
94 | * This method is simply a helper name to check if this database's name | |
95 | * appears in the parent {@link MongoClient client's} list of databases. | |
96 | * </p> | |
97 | * | |
98 | * @return True if the parent client's returns this database's name in its | |
99 | * list of database's names. | |
100 | * @throws MongoDbException | |
101 | * On an error retrieving the list of database's. | |
102 | */ | |
103 | public boolean exists() throws MongoDbException; | |
104 | ||
105 | /** | |
106 | * Returns the MongoCollection with the specified name. This method does not | |
107 | * validate that the collection already exists in the MongoDB database. | |
108 | * | |
109 | * @param name | |
110 | * The name of the collection. | |
111 | * @return The {@link MongoCollection}. | |
112 | */ | |
113 | public MongoCollection getCollection(String name); | |
114 | ||
115 | /** | |
116 | * Returns the durability for write operations sent to the server from this | |
117 | * {@link MongoDatabase} instance. | |
118 | * <p> | |
119 | * Defaults to the {@link Durability} from the {@link Mongo}'s | |
120 | * configuration. | |
121 | * </p> | |
122 | * | |
123 | * @return The durability for write operations on the server. | |
124 | * | |
125 | * @see MongoClientConfiguration#getDefaultDurability() | |
126 | */ | |
127 | public Durability getDurability(); | |
128 | ||
129 | /** | |
130 | * Returns the name of the database. | |
131 | * | |
132 | * @return The name of the database. | |
133 | */ | |
134 | public String getName(); | |
135 | ||
136 | /** | |
137 | * Retrieves the profiling level for the database. | |
138 | * | |
139 | * @return The current profiling level. | |
140 | * @throws MongoDbException | |
141 | * On a failure to create the collection. | |
142 | * @see <a | |
143 | * href="http://docs.mongodb.org/manual/reference/command/profile/">profile | |
144 | * Command Reference</a> | |
145 | */ | |
146 | public ProfilingStatus getProfilingStatus() throws MongoDbException; | |
147 | ||
148 | /** | |
149 | * Returns the read preference for queries from this {@link MongoDatabase} | |
150 | * instance. | |
151 | * <p> | |
152 | * Defaults to {@link ReadPreference} from the {@link Mongo}'s | |
153 | * configuration. | |
154 | * </p> | |
155 | * | |
156 | * @return The default read preference for a query. | |
157 | * | |
158 | * @see MongoClientConfiguration#getDefaultReadPreference() | |
159 | */ | |
160 | public ReadPreference getReadPreference(); | |
161 | ||
162 | /** | |
163 | * Returns the list of the collections contained within the database. | |
164 | * | |
165 | * @return The list of the collections contained within the database. | |
166 | * @throws MongoDbException | |
167 | * On an error listing the collections. | |
168 | */ | |
169 | public List<String> listCollectionNames() throws MongoDbException; | |
170 | ||
171 | /** | |
172 | * Returns the list of the collections contained within the database. | |
173 | * | |
174 | * @return The list of the collections contained within the database. | |
175 | * @throws MongoDbException | |
176 | * On an error listing the collections. | |
177 | * @deprecated Use the {@link #listCollectionNames()} method instead. | |
178 | */ | |
179 | @Deprecated | |
180 | public List<String> listCollections() throws MongoDbException; | |
181 | ||
182 | /** | |
183 | * Runs an administrative command against the 'admin' database. | |
184 | * | |
185 | * @param command | |
186 | * The name of the command to run. | |
187 | * @return The result of the command. | |
188 | * @throws MongoDbException | |
189 | * On an error issuing the command or in running the command | |
190 | */ | |
191 | public Document runAdminCommand(String command) throws MongoDbException; | |
192 | ||
193 | /** | |
194 | * Runs an administrative command against the 'admin' database. | |
195 | * | |
196 | * @param command | |
197 | * The name of the command to run. | |
198 | * @param options | |
199 | * Optional (may be null) options for the command. | |
200 | * @return The result of the command. | |
201 | * @throws MongoDbException | |
202 | * On an error issuing the command or in running the command | |
203 | */ | |
204 | public Document runAdminCommand(String command, DocumentAssignable options) | |
205 | throws MongoDbException; | |
206 | ||
207 | /** | |
208 | * Runs an administrative command against the 'admin' database. | |
209 | * | |
210 | * @param commandName | |
211 | * The name of the command to run. | |
212 | * @param commandValue | |
213 | * The name of the command to run. | |
214 | * @param options | |
215 | * Optional (may be null) options for the command. | |
216 | * @return The result of the command. | |
217 | * @throws MongoDbException | |
218 | * On an error issuing the command or in running the command | |
219 | */ | |
220 | public Document runAdminCommand(String commandName, String commandValue, | |
221 | DocumentAssignable options) throws MongoDbException; | |
222 | ||
223 | /** | |
224 | * Runs a command against the database. | |
225 | * | |
226 | * @param command | |
227 | * The command document to run. | |
228 | * @return The result of the command. | |
229 | * @throws MongoDbException | |
230 | * On an error issuing the command or in running the command | |
231 | */ | |
232 | public Document runCommand(DocumentAssignable command) | |
233 | throws MongoDbException; | |
234 | ||
235 | /** | |
236 | * Runs a command against the database. | |
237 | * | |
238 | * @param command | |
239 | * The name of the command to run. | |
240 | * @return The result of the command. | |
241 | * @throws MongoDbException | |
242 | * On an error issuing the command or in running the command | |
243 | */ | |
244 | public Document runCommand(String command) throws MongoDbException; | |
245 | ||
246 | /** | |
247 | * Runs a command against the database. | |
248 | * | |
249 | * @param command | |
250 | * The name of the command to run. | |
251 | * @param options | |
252 | * Optional (may be null) options for the command. | |
253 | * @return The result of the command. | |
254 | * @throws MongoDbException | |
255 | * On an error issuing the command or in running the command | |
256 | */ | |
257 | public Document runCommand(String command, DocumentAssignable options) | |
258 | throws MongoDbException; | |
259 | ||
260 | /** | |
261 | * Runs a command against the database. | |
262 | * | |
263 | * @param commandName | |
264 | * The name of the command to run. | |
265 | * @param commandValue | |
266 | * The name of the command to run. | |
267 | * @param options | |
268 | * Optional (may be null) options for the command. | |
269 | * @return The result of the command. | |
270 | * @throws MongoDbException | |
271 | * On an error issuing the command or in running the command | |
272 | */ | |
273 | public Document runCommand(String commandName, int commandValue, | |
274 | DocumentAssignable options) throws MongoDbException; | |
275 | ||
276 | /** | |
277 | * Runs a command against the database. | |
278 | * | |
279 | * @param commandName | |
280 | * The name of the command to run. | |
281 | * @param commandValue | |
282 | * The name of the command to run. | |
283 | * @param options | |
284 | * Optional (may be null) options for the command. | |
285 | * @return The result of the command. | |
286 | * @throws MongoDbException | |
287 | * On an error issuing the command or in running the command | |
288 | */ | |
289 | public Document runCommand(String commandName, String commandValue, | |
290 | DocumentAssignable options) throws MongoDbException; | |
291 | ||
292 | /** | |
293 | * Runs a command against the database. | |
294 | * | |
295 | * @param reply | |
296 | * {@link Callback} that will be notified of the command results. | |
297 | * @param command | |
298 | * The command document to run. | |
299 | * @throws MongoDbException | |
300 | * On an error issuing the command or in running the command | |
301 | */ | |
302 | public void runCommandAsync(Callback<Document> reply, | |
303 | DocumentAssignable command) throws MongoDbException; | |
304 | ||
305 | /** | |
306 | * Runs a command against the database. | |
307 | * | |
308 | * @param reply | |
309 | * {@link Callback} that will be notified of the command results. | |
310 | * @param command | |
311 | * The command document to run. | |
312 | * @param requiredServerVersion | |
313 | * The minimum required server version to support the command. | |
314 | * @throws MongoDbException | |
315 | * On an error issuing the command or in running the command | |
316 | */ | |
317 | public void runCommandAsync(Callback<Document> reply, | |
318 | DocumentAssignable command, Version requiredServerVersion) | |
319 | throws MongoDbException; | |
320 | ||
321 | /** | |
322 | * Runs a command against the database. | |
323 | * | |
324 | * @param reply | |
325 | * {@link Callback} that will be notified of the command results. | |
326 | * @param command | |
327 | * The name of the command to run. | |
328 | * @throws MongoDbException | |
329 | * On an error issuing the command or in running the command | |
330 | */ | |
331 | public void runCommandAsync(Callback<Document> reply, String command) | |
332 | throws MongoDbException; | |
333 | ||
334 | /** | |
335 | * Runs a command against the database. | |
336 | * | |
337 | * @param reply | |
338 | * {@link Callback} that will be notified of the command results. | |
339 | * @param command | |
340 | * The name of the command to run. | |
341 | * @param options | |
342 | * Optional (may be null) options for the command. | |
343 | * @throws MongoDbException | |
344 | * On an error issuing the command or in running the command | |
345 | */ | |
346 | public void runCommandAsync(Callback<Document> reply, String command, | |
347 | DocumentAssignable options) throws MongoDbException; | |
348 | ||
349 | /** | |
350 | * Runs a command against the database. | |
351 | * | |
352 | * @param reply | |
353 | * {@link Callback} that will be notified of the command results. | |
354 | * @param commandName | |
355 | * The name of the command to run. | |
356 | * @param commandValue | |
357 | * The name of the command to run. | |
358 | * @param options | |
359 | * Optional (may be null) options for the command. | |
360 | * @throws MongoDbException | |
361 | * On an error issuing the command or in running the command | |
362 | */ | |
363 | public void runCommandAsync(Callback<Document> reply, String commandName, | |
364 | int commandValue, DocumentAssignable options) | |
365 | throws MongoDbException; | |
366 | ||
367 | /** | |
368 | * Runs a command against the database. | |
369 | * | |
370 | * @param reply | |
371 | * {@link Callback} that will be notified of the command results. | |
372 | * @param commandName | |
373 | * The name of the command to run. | |
374 | * @param commandValue | |
375 | * The name of the command to run. | |
376 | * @param options | |
377 | * Optional (may be null) options for the command. | |
378 | * @throws MongoDbException | |
379 | * On an error issuing the command or in running the command | |
380 | */ | |
381 | public void runCommandAsync(Callback<Document> reply, String commandName, | |
382 | String commandValue, DocumentAssignable options) | |
383 | throws MongoDbException; | |
384 | ||
385 | /** | |
386 | * Runs a command against the database. | |
387 | * | |
388 | * @param command | |
389 | * The command document to run. | |
390 | * @return The result of the command. | |
391 | * @throws MongoDbException | |
392 | * On an error issuing the command or in running the command | |
393 | */ | |
394 | public ListenableFuture<Document> runCommandAsync(DocumentAssignable command) | |
395 | throws MongoDbException; | |
396 | ||
397 | /** | |
398 | * Runs a command against the database. | |
399 | * | |
400 | * @param reply | |
401 | * {@link LambdaCallback} that will be notified of the command | |
402 | * results. | |
403 | * @param command | |
404 | * The command document to run. | |
405 | * @throws MongoDbException | |
406 | * On an error issuing the command or in running the command | |
407 | */ | |
408 | public void runCommandAsync(LambdaCallback<Document> reply, | |
409 | DocumentAssignable command) throws MongoDbException; | |
410 | ||
411 | /** | |
412 | * Runs a command against the database. | |
413 | * | |
414 | * @param reply | |
415 | * {@link LambdaCallback} that will be notified of the command | |
416 | * results. | |
417 | * @param command | |
418 | * The command document to run. | |
419 | * @param requiredServerVersion | |
420 | * The minimum required server version to support the command. | |
421 | * @throws MongoDbException | |
422 | * On an error issuing the command or in running the command | |
423 | */ | |
424 | public void runCommandAsync(LambdaCallback<Document> reply, | |
425 | DocumentAssignable command, Version requiredServerVersion) | |
426 | throws MongoDbException; | |
427 | ||
428 | /** | |
429 | * Runs a command against the database. | |
430 | * | |
431 | * @param reply | |
432 | * {@link LambdaCallback} that will be notified of the command | |
433 | * results. | |
434 | * @param command | |
435 | * The name of the command to run. | |
436 | * @throws MongoDbException | |
437 | * On an error issuing the command or in running the command | |
438 | */ | |
439 | public void runCommandAsync(LambdaCallback<Document> reply, String command) | |
440 | throws MongoDbException; | |
441 | ||
442 | /** | |
443 | * Runs a command against the database. | |
444 | * | |
445 | * @param reply | |
446 | * {@link LambdaCallback} that will be notified of the command | |
447 | * results. | |
448 | * @param command | |
449 | * The name of the command to run. | |
450 | * @param options | |
451 | * Optional (may be null) options for the command. | |
452 | * @throws MongoDbException | |
453 | * On an error issuing the command or in running the command | |
454 | */ | |
455 | public void runCommandAsync(LambdaCallback<Document> reply, String command, | |
456 | DocumentAssignable options) throws MongoDbException; | |
457 | ||
458 | /** | |
459 | * Runs a command against the database. | |
460 | * | |
461 | * @param reply | |
462 | * {@link LambdaCallback} that will be notified of the command | |
463 | * results. | |
464 | * @param commandName | |
465 | * The name of the command to run. | |
466 | * @param commandValue | |
467 | * The name of the command to run. | |
468 | * @param options | |
469 | * Optional (may be null) options for the command. | |
470 | * @throws MongoDbException | |
471 | * On an error issuing the command or in running the command | |
472 | */ | |
473 | public void runCommandAsync(LambdaCallback<Document> reply, | |
474 | String commandName, int commandValue, DocumentAssignable options) | |
475 | throws MongoDbException; | |
476 | ||
477 | /** | |
478 | * Runs a command against the database. | |
479 | * | |
480 | * @param reply | |
481 | * {@link LambdaCallback} that will be notified of the command | |
482 | * results. | |
483 | * @param commandName | |
484 | * The name of the command to run. | |
485 | * @param commandValue | |
486 | * The name of the command to run. | |
487 | * @param options | |
488 | * Optional (may be null) options for the command. | |
489 | * @throws MongoDbException | |
490 | * On an error issuing the command or in running the command | |
491 | */ | |
492 | public void runCommandAsync(LambdaCallback<Document> reply, | |
493 | String commandName, String commandValue, DocumentAssignable options) | |
494 | throws MongoDbException; | |
495 | ||
496 | /** | |
497 | * Runs a command against the database. | |
498 | * | |
499 | * @param command | |
500 | * The name of the command to run. | |
501 | * @return The result of the command. | |
502 | * @throws MongoDbException | |
503 | * On an error issuing the command or in running the command | |
504 | */ | |
505 | public ListenableFuture<Document> runCommandAsync(String command) | |
506 | throws MongoDbException; | |
507 | ||
508 | /** | |
509 | * Runs a command against the database. | |
510 | * | |
511 | * @param command | |
512 | * The name of the command to run. | |
513 | * @param options | |
514 | * Optional (may be null) options for the command. | |
515 | * @return The result of the command. | |
516 | * @throws MongoDbException | |
517 | * On an error issuing the command or in running the command | |
518 | */ | |
519 | public ListenableFuture<Document> runCommandAsync(String command, | |
520 | DocumentAssignable options) throws MongoDbException; | |
521 | ||
522 | /** | |
523 | * Runs a command against the database. | |
524 | * | |
525 | * @param commandName | |
526 | * The name of the command to run. | |
527 | * @param commandValue | |
528 | * The name of the command to run. | |
529 | * @param options | |
530 | * Optional (may be null) options for the command. | |
531 | * @return The result of the command. | |
532 | * @throws MongoDbException | |
533 | * On an error issuing the command or in running the command | |
534 | */ | |
535 | public ListenableFuture<Document> runCommandAsync(String commandName, | |
536 | int commandValue, DocumentAssignable options) | |
537 | throws MongoDbException; | |
538 | ||
539 | /** | |
540 | * Runs a command against the database. | |
541 | * | |
542 | * @param commandName | |
543 | * The name of the command to run. | |
544 | * @param commandValue | |
545 | * The name of the command to run. | |
546 | * @param options | |
547 | * Optional (may be null) options for the command. | |
548 | * @return The result of the command. | |
549 | * @throws MongoDbException | |
550 | * On an error issuing the command or in running the command | |
551 | */ | |
552 | public ListenableFuture<Document> runCommandAsync(String commandName, | |
553 | String commandValue, DocumentAssignable options) | |
554 | throws MongoDbException; | |
555 | ||
556 | /** | |
557 | * Sets the durability for write operations from this {@link MongoDatabase} | |
558 | * instance. | |
559 | * <p> | |
560 | * Defaults to the {@link Durability} from the {@link Mongo}'s configuration | |
561 | * if set to <code>null</code>. | |
562 | * </p> | |
563 | * | |
564 | * @param durability | |
565 | * The durability for write operations on the server. | |
566 | * | |
567 | * @see MongoClientConfiguration#getDefaultDurability() | |
568 | */ | |
569 | public void setDurability(final Durability durability); | |
570 | ||
571 | /** | |
572 | * Sets the profiling level for the database. | |
573 | * | |
574 | * @param profileLevel | |
575 | * The desired profiling level | |
576 | * @return True if the profiling level was changed. Note if the level | |
577 | * provided matches the profiling level already set then this method | |
578 | * returns <code>false</code>. | |
579 | * @throws MongoDbException | |
580 | * On a failure to create the collection. | |
581 | * @see <a | |
582 | * href="http://docs.mongodb.org/manual/reference/command/profile/">profile | |
583 | * Command Reference</a> | |
584 | */ | |
585 | public boolean setProfilingStatus(ProfilingStatus profileLevel) | |
586 | throws MongoDbException; | |
587 | ||
588 | /** | |
589 | * Sets the value of the read preference for a queries from this | |
590 | * {@link MongoDatabase} instance. | |
591 | * <p> | |
592 | * Defaults to the {@link ReadPreference} from the {@link Mongo}'s | |
593 | * configuration if set to <code>null</code>. | |
594 | * </p> | |
595 | * | |
596 | * @param readPreference | |
597 | * The read preference for a query. | |
598 | * | |
599 | * @see MongoClientConfiguration#getDefaultReadPreference() | |
600 | */ | |
601 | public void setReadPreference(final ReadPreference readPreference); | |
602 | ||
603 | /** | |
604 | * Returns the statistics for the database. | |
605 | * | |
606 | * @return The results document with the database statistics. | |
607 | * @throws MongoDbException | |
608 | * On an error collecting the database statistics. | |
609 | * @see <a | |
610 | * href="http://docs.mongodb.org/manual/reference/command/dbStats/">dbStats | |
611 | * Command Reference</a> | |
612 | */ | |
613 | public Document stats() throws MongoDbException; | |
614 | } |