1 /*
2 * #%L
3 * ParallelScan.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
21 package com.allanbank.mongodb.builder;
22
23 import com.allanbank.mongodb.ReadPreference;
24 import com.allanbank.mongodb.Version;
25
26 /**
27 * ParallelScan provides an immutable container for all of the options for a
28 * {@code parallelCollectionScan}.
29 * <p>
30 * <b>Note</b>: The {@code parallelCollectionScan} does not work with sharded
31 * clusters.
32 * <p>
33 *
34 * @see <a
35 * href="http://docs.mongodb.org/manual/reference/command/parallelCollectionScan/">parallelCollectionScan
36 * Command</a>
37 * @api.yes This class is part of the driver's API. Public and protected members
38 * will be deprecated for at least 1 non-bugfix release (version
39 * numbers are <major>.<minor>.<bugfix>) before being
40 * removed or modified.
41 * @copyright 2014, Allanbank Consulting, Inc., All Rights Reserved
42 */
43 public class ParallelScan {
44 /**
45 * The first version of MongoDB to support the
46 * {@code parallelCollectionScan} command.
47 */
48 public static final Version REQUIRED_VERSION = Version.parse("2.6.0");
49
50 /**
51 * Creates a new builder for a {@link ParallelScan}.
52 *
53 * @return The builder to construct a {@link ParallelScan}.
54 */
55 public static Builder builder() {
56 return new Builder();
57 }
58
59 /** The number of documents to be returned in each batch of results. */
60 private final int myBatchSize;
61
62 /** The preference for which servers to use to retrieve the results. */
63 private final ReadPreference myReadPreference;
64
65 /**
66 * The requested number of iterators/cursors to create. The server may
67 * return few than this number of iterators.
68 * <p>
69 * This value will be forced into the range [1, 10,000].
70 * </p>
71 */
72 private final int myRequestedIteratorCount;
73
74 /**
75 * Creates a new ParallelScan.
76 *
77 * @param builder
78 * The builder to copy the query fields from.
79 */
80 protected ParallelScan(final Builder builder) {
81 myBatchSize = builder.myBatchSize;
82 myReadPreference = builder.myReadPreference;
83 myRequestedIteratorCount = builder.myRequestedIteratorCount;
84 }
85
86 /**
87 * Returns the number of documents to be returned in each batch of results.
88 *
89 * @return The number of documents to be returned in each batch of results.
90 */
91 public int getBatchSize() {
92 return myBatchSize;
93 }
94
95 /**
96 * Returns the preference for the servers to retrieve the results from. May
97 * be <code>null</code> in which case the default read preference should be
98 * used.
99 *
100 * @return The preference for the servers to retrieve the results from.
101 */
102 public ReadPreference getReadPreference() {
103 return myReadPreference;
104 }
105
106 /**
107 * Returns the requested number of iterators/cursors to create. The server
108 * may return few than this number of iterators.
109 * <p>
110 * This value will be forced into the range [1, 10,000].
111 * </p>
112 *
113 * @return The requested number of iterators/cursors to create.
114 */
115 public int getRequestedIteratorCount() {
116 return myRequestedIteratorCount;
117 }
118
119 /**
120 * Helper for creating immutable {@link ParallelScan} queries.
121 *
122 * @api.yes This class is part of the driver's API. Public and protected
123 * members will be deprecated for at least 1 non-bugfix release
124 * (version numbers are <major>.<minor>.<bugfix>)
125 * before being removed or modified.
126 * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
127 */
128 public static class Builder {
129
130 /** The number of documents to be returned in each batch of results. */
131 protected int myBatchSize;
132
133 /** The preference for which servers to use to retrieve the results. */
134 protected ReadPreference myReadPreference;
135
136 /**
137 * The desired number of iterators/cursors to create. The server may
138 * return few than this number of iterators.
139 * <p>
140 * This value will be forced into the range [1, 10,000].
141 * </p>
142 */
143 protected int myRequestedIteratorCount;
144
145 /**
146 * Creates a new Builder.
147 */
148 public Builder() {
149 reset();
150 }
151
152 /**
153 * Sets the value of the number of documents to be returned in each
154 * batch.
155 * <p>
156 * This method delegates to {@link #setBatchSize(int)}.
157 * </p>
158 *
159 * @param batchSize
160 * The new value for the number of documents to be returned
161 * in each batch.
162 * @return This builder for chaining method calls.
163 */
164 public Builder batchSize(final int batchSize) {
165 return setBatchSize(batchSize);
166 }
167
168 /**
169 * Constructs a new {@link ParallelScan} object from the state of the
170 * builder.
171 *
172 * @return The new {@link ParallelScan} object.
173 */
174 public ParallelScan build() {
175 return new ParallelScan(this);
176 }
177
178 /**
179 * Sets the preference for the set of servers to retrieve the results
180 * from.
181 * <p>
182 * This method delegates to {@link #setReadPreference(ReadPreference)}.
183 * </p>
184 *
185 * @param readPreference
186 * The new value for the preference of which server to return
187 * the results from.
188 * @return This builder for chaining method calls.
189 */
190 public Builder readPreference(final ReadPreference readPreference) {
191 return setReadPreference(readPreference);
192 }
193
194 /**
195 * Sets the requested number of iterators/cursors to create to the new
196 * value.
197 * <p>
198 * This value will be forced into the range [1, 10,000].
199 * </p>
200 * <p>
201 * This method delegates to {@link #setRequestedIteratorCount(int)}.
202 * </p>
203 *
204 * @param numberOfIterators
205 * The requested number of iterators/cursors to create.
206 * @return This builder for chaining method calls.
207 */
208 public Builder requestedIteratorCount(final int numberOfIterators) {
209 return setRequestedIteratorCount(numberOfIterators);
210 }
211
212 /**
213 * Resets the builder back to its initial state for reuse.
214 *
215 * @return This builder for chaining method calls.
216 */
217 public Builder reset() {
218 myBatchSize = 0;
219 myReadPreference = null;
220 myRequestedIteratorCount = 1;
221
222 return this;
223 }
224
225 /**
226 * Sets the value of the number of documents to be returned in each
227 * batch.
228 *
229 * @param batchSize
230 * The new value for the number of documents to be returned
231 * in each batch.
232 * @return This builder for chaining method calls.
233 */
234 public Builder setBatchSize(final int batchSize) {
235 myBatchSize = batchSize;
236 return this;
237 }
238
239 /**
240 * Sets the preference for the set of servers to retrieve the results
241 * from.
242 *
243 * @param readPreference
244 * The new value for the preference of which server to return
245 * the results from.
246 * @return This builder for chaining method calls.
247 */
248 public Builder setReadPreference(final ReadPreference readPreference) {
249 myReadPreference = readPreference;
250 return this;
251 }
252
253 /**
254 * Sets the requested number of iterators/cursors to create to the new
255 * value.
256 * <p>
257 * This value will be forced into the range [1, 10,000].
258 * </p>
259 *
260 * @param numberOfIterators
261 * The requested number of iterators/cursors to create.
262 * @return This builder for chaining method calls.
263 */
264 public Builder setRequestedIteratorCount(final int numberOfIterators) {
265 myRequestedIteratorCount = Math.min(Math.max(numberOfIterators, 1),
266 10000);
267 return this;
268 }
269 }
270 }