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 }