Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
MongoCursorControl |
|
| 1.0;1 |
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 | } |