1 /*
2 * #%L
3 * MongoClient.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.io.Closeable;
23 import java.util.List;
24
25 import com.allanbank.mongodb.bson.Document;
26 import com.allanbank.mongodb.bson.DocumentAssignable;
27
28 /**
29 * Interface to bootstrap into interactions with MongoDB.
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 MongoClient extends Closeable {
38
39 /**
40 * Returns a MongoClient instance that shares connections with this
41 * MongoClient instance but serializes all of its requests on a single
42 * connection.
43 * <p>
44 * While the returned MongoClient instance is thread safe it is intended to
45 * be used by a single logical thread to ensure requests issued to the
46 * MongoDB server are guaranteed to be processed in the same order they are
47 * requested.
48 * </p>
49 * <p>
50 * Creation of the serial instance is lightweight with minimal object
51 * allocation and no server interaction.
52 * </p>
53 *
54 * @return A serialized view of the MongoDB connections.
55 */
56 public MongoClient asSerializedClient();
57
58 /**
59 * Returns the configuration being used by the logical MongoDB connection.
60 *
61 * @return The configuration being used by the logical MongoDB connection.
62 */
63 public MongoClientConfiguration getConfig();
64
65 /**
66 * Returns the MongoDatabase with the specified name. This method does not
67 * validate that the database already exists in the MongoDB instance.
68 *
69 * @param name
70 * The name of the existing database.
71 * @return The {@link MongoDatabase}.
72 */
73 public MongoDatabase getDatabase(String name);
74
75 /**
76 * Returns a list of database names.
77 *
78 * @return A list of available database names.
79 */
80 public List<String> listDatabaseNames();
81
82 /**
83 * Returns a list of database names.
84 *
85 * @return A list of available database names.
86 * @deprecated Use the {@link #listDatabaseNames()} method instead.
87 */
88 @Deprecated
89 public List<String> listDatabases();
90
91 /**
92 * Restarts an iterator that was previously saved.
93 *
94 * @param cursorDocument
95 * The document containing the state of the cursor.
96 * @return The restarted iterator.
97 * @throws IllegalArgumentException
98 * If the document does not contain a valid cursor state.
99 */
100 public MongoIterator<Document> restart(DocumentAssignable cursorDocument)
101 throws IllegalArgumentException;
102
103 /**
104 * Restarts a document stream from a cursor that was previously saved.
105 * <p>
106 * The sequence of callbacks will be terminated by either calling the
107 * {@link LambdaCallback#accept(Throwable, Object) results.accept(...)}
108 * method with <code>null</code> for both parameters or by calling the
109 * method with an error for the first parameter.
110 * </p>
111 *
112 * @param results
113 * Callback that will be notified of the results of the cursor.
114 * @param cursorDocument
115 * The document containing the state of the cursor.
116 * @return A {@link MongoCursorControl} to control the cursor streaming
117 * documents to the caller. This includes the ability to stop the
118 * cursor and persist its state.
119 * @throws IllegalArgumentException
120 * If the document does not contain a valid cursor state.
121 */
122 public MongoCursorControl restart(final LambdaCallback<Document> results,
123 DocumentAssignable cursorDocument) throws IllegalArgumentException;
124
125 /**
126 * Restarts a document stream from a cursor that was previously saved.
127 *
128 * @param results
129 * Callback that will be notified of the results of the cursor.
130 * @param cursorDocument
131 * The document containing the state of the cursor.
132 * @return A {@link MongoCursorControl} to control the cursor streaming
133 * documents to the caller. This includes the ability to stop the
134 * cursor and persist its state.
135 * @throws IllegalArgumentException
136 * If the document does not contain a valid cursor state.
137 */
138 public MongoCursorControl restart(final StreamCallback<Document> results,
139 DocumentAssignable cursorDocument) throws IllegalArgumentException;
140
141 }