1 /*
2 * #%L
3 * MongoCursorControl.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
24 import com.allanbank.mongodb.bson.Document;
25 import com.allanbank.mongodb.builder.Find;
26
27 /**
28 * MongoCursorControl provides the controls for a MongoDB cursor interaction.
29 * Normally this interface is used via a {@link MongoIterator} but in the case
30 * of streaming only the controls are returned.
31 *
32 * @api.yes This interface is part of the driver's API. Public and protected
33 * members will be deprecated for at least 1 non-bugfix release
34 * (version numbers are <major>.<minor>.<bugfix>)
35 * before being removed or modified.
36 * @copyright 2013, Allanbank Consulting, Inc., All Rights Reserved
37 */
38 public interface MongoCursorControl extends Closeable {
39 /** The batch size field in the cursor document. */
40 public static final String BATCH_SIZE_FIELD = "batch_size";
41
42 /** The cursor id field in the cursor document. */
43 public static final String CURSOR_ID_FIELD = "cursor_id";
44
45 /** The remaining limit field in the cursor document. */
46 public static final String LIMIT_FIELD = "limit";
47
48 /** The name space field in the cursor document. */
49 public static final String NAME_SPACE_FIELD = "ns";
50
51 /** The server name field in the cursor document. */
52 public static final String SERVER_FIELD = "server";
53
54 /**
55 * Returns a {@link Document} that can be used to restart the
56 * cursor/iterator.
57 * <p>
58 * If this iterator is exhausted or closed then the cursor is also closed on
59 * the server and this method will return null.
60 * </p>
61 * <p>
62 * If the cursor/{@link Find} was not created with out a timeout then
63 * eventually the server will automatically remove the cursor and the
64 * restart will fail.
65 * </p>
66 * <p>
67 * Returns the active cursor in the form:<blockquote>
68 *
69 * <pre>
70 * <code>
71 * {
72 * {@value #NAME_SPACE_FIELD} : '<database_name>.$lt;collection_name>',
73 * {@value #CURSOR_ID_FIELD} : <cursor_id>,
74 * {@value #SERVER_FIELD} : '<server>',
75 * {@value #LIMIT_FIELD} : <remaining_limit>
76 * {@value #BATCH_SIZE_FIELD} : <batch_size>
77 * }</code>
78 * </pre>
79 *
80 * </blockquote>
81 *
82 * @return A document that can be used to restart the cursor.
83 * <code>null</code> if the server's cursor has been exhausted or
84 * closed.
85 */
86 public Document asDocument();
87
88 /**
89 * Close the iterator and release any resources it is holding.
90 */
91 @Override
92 public void close();
93
94 /**
95 * Returns the size for batches of documents that are requested.
96 *
97 * @return The size of the batches of documents that are requested.
98 */
99 public int getBatchSize();
100
101 /**
102 * Sets the size for future batch sizes.
103 *
104 * @param batchSize
105 * The size to request for future batch sizes.
106 */
107 public void setBatchSize(int batchSize);
108
109 /**
110 * Stops the iterator after consuming any received and/or requested batches.
111 * <p>
112 * <b>WARNING</b>: This will leave the cursor open on the server. Even a
113 * {@link #close()} on this object will not close the cursor on the server.
114 * Users should persist the state of the cursor as returned from
115 * {@link #asDocument()} and restart the cursor using one of the
116 * {@link MongoClient#restart(com.allanbank.mongodb.bson.DocumentAssignable)}
117 * or
118 * {@link MongoClient#restart(StreamCallback, com.allanbank.mongodb.bson.DocumentAssignable)}
119 * methods. Use {@link #stop()} with extreme caution.
120 * </p>
121 * <p>
122 * The iterator or stream will naturally stop (
123 * {@link MongoIterator#hasNext()} will return false or the stream's call
124 * back {@link StreamCallback#done()} method will be called) when the
125 * current batch and any batches already requested are exhausted.
126 * </p>
127 */
128 public void stop();
129
130 }