View Javadoc
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 &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;) 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 &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
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 }