1 /*
2 * #%L
3 * Client.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.client;
21
22 import com.allanbank.mongodb.Durability;
23 import com.allanbank.mongodb.MongoClientConfiguration;
24 import com.allanbank.mongodb.MongoCursorControl;
25 import com.allanbank.mongodb.MongoDbException;
26 import com.allanbank.mongodb.MongoIterator;
27 import com.allanbank.mongodb.ReadPreference;
28 import com.allanbank.mongodb.StreamCallback;
29 import com.allanbank.mongodb.bson.Document;
30 import com.allanbank.mongodb.bson.DocumentAssignable;
31 import com.allanbank.mongodb.client.callback.ReplyCallback;
32
33 /**
34 * Unified client interface to MongoDB.
35 *
36 * @api.no This class is <b>NOT</b> part of the drivers API. This class may be
37 * mutated in incompatible ways between any two releases of the driver.
38 * @copyright 2011-2014, Allanbank Consulting, Inc., All Rights Reserved
39 */
40 public interface Client {
41 /**
42 * The absolute maximum size for a BSON document supported by all versions
43 * of MongoDB servers: 16MiB ({@value} ).
44 */
45 public static final int MAX_DOCUMENT_SIZE = 16 * 1024 * 1024;
46
47 /**
48 * Closes the client.
49 */
50 public void close();
51
52 /**
53 * Returns the meta-data on the current cluster.
54 *
55 * @return The meta-data on the current cluster.
56 */
57 public ClusterStats getClusterStats();
58
59 /**
60 * Returns the type of cluster the client is connected to.
61 *
62 * @return The type of cluster the client is connected to.
63 */
64 public ClusterType getClusterType();
65
66 /**
67 * Returns the configuration being used by the logical MongoDB connection.
68 *
69 * @return The configuration being used by the logical MongoDB connection.
70 */
71 public MongoClientConfiguration getConfig();
72
73 /**
74 * Returns the {@link Durability} from the {@link MongoClientConfiguration}.
75 *
76 * @return The default durability from the {@link MongoClientConfiguration}.
77 */
78 public Durability getDefaultDurability();
79
80 /**
81 * Returns the {@link ReadPreference} from the
82 * {@link MongoClientConfiguration}.
83 *
84 * @return The default read preference from the
85 * {@link MongoClientConfiguration} .
86 */
87 public ReadPreference getDefaultReadPreference();
88
89 /**
90 * Restarts an iterator that was previously saved.
91 *
92 * @param cursorDocument
93 * The document containing the state of the cursor.
94 * @return The restarted iterator.
95 * @throws IllegalArgumentException
96 * If the document does not contain a valid cursor state.
97 */
98 public MongoIterator<Document> restart(DocumentAssignable cursorDocument)
99 throws IllegalArgumentException;
100
101 /**
102 * Restarts a document stream from a cursor that was previously saved.
103 *
104 * @param results
105 * Callback that will be notified of the results of the cursor.
106 * @param cursorDocument
107 * The document containing the state of the cursor.
108 * @return A {@link MongoCursorControl} to control the cursor streaming
109 * documents to the caller. This includes the ability to stop the
110 * cursor and persist its state.
111 * @throws IllegalArgumentException
112 * If the document does not contain a valid cursor state.
113 */
114 public MongoCursorControl restart(final StreamCallback<Document> results,
115 DocumentAssignable cursorDocument) throws IllegalArgumentException;
116
117 /**
118 * Sends a message on the connection.
119 *
120 * @param message1
121 * The first message to send on the connection.
122 * @param message2
123 * The second message to send on the connection.
124 * @param replyCallback
125 * The callback to notify of responses to the {@code message2}.
126 * May be <code>null</code>.
127 * @throws MongoDbException
128 * On an error sending the message.
129 */
130 public void send(Message message1, Message message2,
131 ReplyCallback replyCallback) throws MongoDbException;
132
133 /**
134 * Sends a message on the connection.
135 *
136 * @param message
137 * The message to send on the connection.
138 * @param replyCallback
139 * The callback to notify of responses to the messages. May be
140 * <code>null</code>.
141 * @throws MongoDbException
142 * On an error sending the message.
143 */
144 public void send(Message message, ReplyCallback replyCallback)
145 throws MongoDbException;
146 }