Coverage Report

Coverage Report - com.allanbank.mongodb.builder.Distinct

Classes in this File

Line Coverage

Branch Coverage

Complexity

Distinct

100%

13/13

N/A

Distinct$Builder

100%

21/21

N/A

 /*
  * #%L
  * Distinct.java - mongodb-async-driver - Allanbank Consulting, Inc.
  * %%
  * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  * 
  *      http://www.apache.org/licenses/LICENSE-2.0
  * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  * #L%
  */
 
 package com.allanbank.mongodb.builder;
 
 import static com.allanbank.mongodb.util.Assertions.assertNotEmpty;
 
 import java.util.concurrent.TimeUnit;
 
 import com.allanbank.mongodb.MongoCollection;
 import com.allanbank.mongodb.ReadPreference;
 import com.allanbank.mongodb.Version;
 import com.allanbank.mongodb.bson.Document;
 import com.allanbank.mongodb.bson.DocumentAssignable;
 
 /**
  * Distinct provides container for all of the options to a <tt>distinct</tt>
  * command. A {@link Builder} is provided to assist in creating a
  * {@link Distinct}.
  * 
  * @api.yes This class is part of the driver's API. Public and protected members
  *          will be deprecated for at least 1 non-bugfix release (version
  *          numbers are &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;) before being
  *          removed or modified.
  * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
  */
 public class Distinct {
     /**
      * The first version of MongoDB to support the {@code distinct} command with
      * the ability to limit the execution time on the server.
      */
     public static final Version MAX_TIMEOUT_VERSION = Find.MAX_TIMEOUT_VERSION;
 
     /**
      * Creates a new builder for a {@link Distinct}.
      * 
      * @return The builder to construct a {@link Distinct}.
      */
     public static Builder builder() {
         return new Builder();
     }
 
     /** The name of the key to collect distinct values for. */
     private final String myKey;
 
     /** The maximum amount of time to allow the command to run. */
     private final long myMaximumTimeMilliseconds;
 
     /** The query to select document to perform a distinct query across. */
     private final Document myQuery;
 
     /** The read preference to use. */
     private final ReadPreference myReadPreference;
 
     /**
      * Creates a new Distinct.
      * 
      * @param builder
      *            The builder to copy the state from.
      * @throws IllegalArgumentException
      *             If neither the {@link #getKey() key} is <code>null</code> or
      *             empty.
      */
     protected Distinct(final Builder builder) {
         assertNotEmpty(builder.myKey,
                 "The distinct's command key cannot be null or empty.");
 
         myKey = builder.myKey;
         myQuery = builder.myQuery;
         myReadPreference = builder.myReadPreference;
         myMaximumTimeMilliseconds = builder.myMaximumTimeMilliseconds;
     }
 
     /**
      * Returns the name of the key to collect distinct values for.
      * 
      * @return The name of the key to collect distinct values for.
      */
     public String getKey() {
         return myKey;
     }
 
     /**
      * Returns the maximum amount of time to allow the command to run on the
      * Server before it is aborted.
      * 
      * @return The maximum amount of time to allow the command to run on the
      *         Server before it is aborted.
      * 
      * @since MongoDB 2.6
      */
     public long getMaximumTimeMilliseconds() {
         return myMaximumTimeMilliseconds;
     }
 
     /**
      * Returns the query to select the documents to run the distinct against.
      * 
      * @return The query to select the documents to run the distinct against.
      */
     public Document getQuery() {
         return myQuery;
     }
 
     /**
      * Returns the {@link ReadPreference} specifying which servers may be used
      * to execute the {@link Distinct} command.
      * <p>
      * If <code>null</code> then the {@link MongoCollection} instance's
      * {@link ReadPreference} will be used.
      * </p>
      * 
      * @return The read preference to use.
      * 
      * @see MongoCollection#getReadPreference()
      */
     public ReadPreference getReadPreference() {
         return myReadPreference;
     }
 
     /**
      * Builder provides support for creating a {@link Distinct} object.
      * 
      * @api.yes This class is part of the driver's API. Public and protected
      *          members will be deprecated for at least 1 non-bugfix release
      *          (version numbers are &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
      *          before being removed or modified.
      * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
      */
     public static class Builder {
 
         /** The name of the key to collect distinct values for. */
         protected String myKey;
 
         /** The maximum amount of time to allow the command to run. */
         protected long myMaximumTimeMilliseconds;
 
         /** The query to select document to perform a distinct query across. */
         protected Document myQuery;
 
         /** The read preference to use. */
         protected ReadPreference myReadPreference;
 
         /**
          * Creates a new Builder.
          */
         public Builder() {
             reset();
         }
 
         /**
          * Creates a new {@link GroupBy} based on the current state of the
          * builder.
          * 
          * @return A new {@link GroupBy} based on the current state of the
          *         builder.
          * @throws IllegalArgumentException
          *             If neither the {@link #setKey key} is <code>null</code>
          *             or empty.
          */
         public Distinct build() throws IllegalArgumentException {
             return new Distinct(this);
         }
 
         /**
          * Sets the name of the key to collect distinct values for.
          * <p>
          * This method delegates to {@link #setKey(String)}.
          * </p>
          * 
          * @param key
          *            The new name of the key to collect distinct values for.
          * @return This {@link Builder} for method call chaining.
          */
         public Builder key(final String key) {
             return setKey(key);
         }
 
         /**
          * Sets the maximum number of milliseconds to allow the command to run
          * before aborting the request on the server.
          * <p>
          * This method equivalent to {@link #setMaximumTimeMilliseconds(long)
          * setMaximumTimeMilliseconds(timeLimitUnits.toMillis(timeLimit)}.
          * </p>
          * 
          * @param timeLimit
          *            The new maximum amount of time to allow the command to
          *            run.
          * @param timeLimitUnits
          *            The units for the maximum amount of time to allow the
          *            command to run.
          * 
          * @return This {@link Builder} for method call chaining.
          * 
          * @since MongoDB 2.6
          */
         public Builder maximumTime(final long timeLimit,
                 final TimeUnit timeLimitUnits) {
             return setMaximumTimeMilliseconds(timeLimitUnits
                     .toMillis(timeLimit));
         }
 
         /**
          * Sets the value of the query to select the documents to run the
          * distinct against.
          * <p>
          * This method delegates to {@link #setQuery(DocumentAssignable)}.
          * </p>
          * 
          * @param query
          *            The new value for the query to select the documents to run
          *            the distinct against.
          * @return This {@link Builder} for method call chaining.
          */
         public Builder query(final DocumentAssignable query) {
             return setQuery(query);
         }
 
         /**
          * Sets the {@link ReadPreference} specifying which servers may be used
          * to execute the {@link Distinct} command.
          * <p>
          * If not set or set to <code>null</code> then the
          * {@link MongoCollection} instance's {@link ReadPreference} will be
          * used.
          * </p>
          * <p>
          * This method delegates to {@link #setReadPreference(ReadPreference)}.
          * </p>
          * 
          * @param readPreference
          *            The read preferences specifying which servers may be used.
          * @return This builder for chaining method calls.
          * 
          * @see MongoCollection#getReadPreference()
          */
         public Builder readPreference(final ReadPreference readPreference) {
             return setReadPreference(readPreference);
         }
 
         /**
          * Resets the builder back to its initial state.
          * 
          * @return This {@link Builder} for method call chaining.
          */
         public Builder reset() {
             myKey = null;
             myQuery = null;
             myReadPreference = null;
             myMaximumTimeMilliseconds = 0;
 
             return this;
         }
 
         /**
          * Sets the name of the key to collect distinct values for.
          * 
          * @param key
          *            The new name of the key to collect distinct values for.
          * @return This {@link Builder} for method call chaining.
          */
         public Builder setKey(final String key) {
             myKey = key;
             return this;
         }
 
         /**
          * Sets the maximum number of milliseconds to allow the command to run
          * before aborting the request on the server.
          * 
          * @param maximumTimeMilliseconds
          *            The new maximum number of milliseconds to allow the
          *            command to run.
          * @return This {@link Builder} for method call chaining.
          * 
          * @since MongoDB 2.6
          */
         public Builder setMaximumTimeMilliseconds(
                 final long maximumTimeMilliseconds) {
             myMaximumTimeMilliseconds = maximumTimeMilliseconds;
             return this;
         }
 
         /**
          * Sets the value of the query to select the documents to run the
          * distinct against.
          * 
          * @param query
          *            The new value for the query to select the documents to run
          *            the distinct against.
          * @return This {@link Builder} for method call chaining.
          */
         public Builder setQuery(final DocumentAssignable query) {
             myQuery = query.asDocument();
             return this;
         }
 
         /**
          * Sets the {@link ReadPreference} specifying which servers may be used
          * to execute the {@link Distinct} command.
          * <p>
          * If not set or set to <code>null</code> then the
          * {@link MongoCollection} instance's {@link ReadPreference} will be
          * used.
          * </p>
          * 
          * @param readPreference
          *            The read preferences specifying which servers may be used.
          * @return This builder for chaining method calls.
          * 
          * @see MongoCollection#getReadPreference()
          */
         public Builder setReadPreference(final ReadPreference readPreference) {
             myReadPreference = readPreference;
             return this;
         }
     }
 }

1		/*
2		* #%L
3		* Distinct.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 static com.allanbank.mongodb.util.Assertions.assertNotEmpty;
24
25		import java.util.concurrent.TimeUnit;
26
27		import com.allanbank.mongodb.MongoCollection;
28		import com.allanbank.mongodb.ReadPreference;
29		import com.allanbank.mongodb.Version;
30		import com.allanbank.mongodb.bson.Document;
31		import com.allanbank.mongodb.bson.DocumentAssignable;
32
33		/**
34		* Distinct provides container for all of the options to a <tt>distinct</tt>
35		* command. A {@link Builder} is provided to assist in creating a
36		* {@link Distinct}.
37		*
38		* @api.yes This class is part of the driver's API. Public and protected members
39		* will be deprecated for at least 1 non-bugfix release (version
40		* numbers are <major>.<minor>.<bugfix>) before being
41		* removed or modified.
42		* @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
43		*/
44		public class Distinct {
45		/**
46		* The first version of MongoDB to support the {@code distinct} command with
47		* the ability to limit the execution time on the server.
48		*/
49	1	public static final Version MAX_TIMEOUT_VERSION = Find.MAX_TIMEOUT_VERSION;
50
51		/**
52		* Creates a new builder for a {@link Distinct}.
53		*
54		* @return The builder to construct a {@link Distinct}.
55		*/
56		public static Builder builder() {
57	1	return new Builder();
58		}
59
60		/** The name of the key to collect distinct values for. */
61		private final String myKey;
62
63		/** The maximum amount of time to allow the command to run. */
64		private final long myMaximumTimeMilliseconds;
65
66		/** The query to select document to perform a distinct query across. */
67		private final Document myQuery;
68
69		/** The read preference to use. */
70		private final ReadPreference myReadPreference;
71
72		/**
73		* Creates a new Distinct.
74		*
75		* @param builder
76		* The builder to copy the state from.
77		* @throws IllegalArgumentException
78		* If neither the {@link #getKey() key} is <code>null</code> or
79		* empty.
80		*/
81	26	protected Distinct(final Builder builder) {
82	26	assertNotEmpty(builder.myKey,
83		"The distinct's command key cannot be null or empty.");
84
85	23	myKey = builder.myKey;
86	23	myQuery = builder.myQuery;
87	23	myReadPreference = builder.myReadPreference;
88	23	myMaximumTimeMilliseconds = builder.myMaximumTimeMilliseconds;
89	23	}
90
91		/**
92		* Returns the name of the key to collect distinct values for.
93		*
94		* @return The name of the key to collect distinct values for.
95		*/
96		public String getKey() {
97	14	return myKey;
98		}
99
100		/**
101		* Returns the maximum amount of time to allow the command to run on the
102		* Server before it is aborted.
103		*
104		* @return The maximum amount of time to allow the command to run on the
105		* Server before it is aborted.
106		*
107		* @since MongoDB 2.6
108		*/
109		public long getMaximumTimeMilliseconds() {
110	14	return myMaximumTimeMilliseconds;
111		}
112
113		/**
114		* Returns the query to select the documents to run the distinct against.
115		*
116		* @return The query to select the documents to run the distinct against.
117		*/
118		public Document getQuery() {
119	26	return myQuery;
120		}
121
122		/**
123		* Returns the {@link ReadPreference} specifying which servers may be used
124		* to execute the {@link Distinct} command.
125		* <p>
126		* If <code>null</code> then the {@link MongoCollection} instance's
127		* {@link ReadPreference} will be used.
128		* </p>
129		*
130		* @return The read preference to use.
131		*
132		* @see MongoCollection#getReadPreference()
133		*/
134		public ReadPreference getReadPreference() {
135	12	return myReadPreference;
136		}
137
138		/**
139		* Builder provides support for creating a {@link Distinct} object.
140		*
141		* @api.yes This class is part of the driver's API. Public and protected
142		* members will be deprecated for at least 1 non-bugfix release
143		* (version numbers are <major>.<minor>.<bugfix>)
144		* before being removed or modified.
145		* @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
146		*/
147		public static class Builder {
148
149		/** The name of the key to collect distinct values for. */
150		protected String myKey;
151
152		/** The maximum amount of time to allow the command to run. */
153		protected long myMaximumTimeMilliseconds;
154
155		/** The query to select document to perform a distinct query across. */
156		protected Document myQuery;
157
158		/** The read preference to use. */
159		protected ReadPreference myReadPreference;
160
161		/**
162		* Creates a new Builder.
163		*/
164	18	public Builder() {
165	18	reset();
166	18	}
167
168		/**
169		* Creates a new {@link GroupBy} based on the current state of the
170		* builder.
171		*
172		* @return A new {@link GroupBy} based on the current state of the
173		* builder.
174		* @throws IllegalArgumentException
175		* If neither the {@link #setKey key} is <code>null</code>
176		* or empty.
177		*/
178		public Distinct build() throws IllegalArgumentException {
179	26	return new Distinct(this);
180		}
181
182		/**
183		* Sets the name of the key to collect distinct values for.
184		* <p>
185		* This method delegates to {@link #setKey(String)}.
186		* </p>
187		*
188		* @param key
189		* The new name of the key to collect distinct values for.
190		* @return This {@link Builder} for method call chaining.
191		*/
192		public Builder key(final String key) {
193	5	return setKey(key);
194		}
195
196		/**
197		* Sets the maximum number of milliseconds to allow the command to run
198		* before aborting the request on the server.
199		* <p>
200		* This method equivalent to {@link #setMaximumTimeMilliseconds(long)
201		* setMaximumTimeMilliseconds(timeLimitUnits.toMillis(timeLimit)}.
202		* </p>
203		*
204		* @param timeLimit
205		* The new maximum amount of time to allow the command to
206		* run.
207		* @param timeLimitUnits
208		* The units for the maximum amount of time to allow the
209		* command to run.
210		*
211		* @return This {@link Builder} for method call chaining.
212		*
213		* @since MongoDB 2.6
214		*/
215		public Builder maximumTime(final long timeLimit,
216		final TimeUnit timeLimitUnits) {
217	2	return setMaximumTimeMilliseconds(timeLimitUnits
218		.toMillis(timeLimit));
219		}
220
221		/**
222		* Sets the value of the query to select the documents to run the
223		* distinct against.
224		* <p>
225		* This method delegates to {@link #setQuery(DocumentAssignable)}.
226		* </p>
227		*
228		* @param query
229		* The new value for the query to select the documents to run
230		* the distinct against.
231		* @return This {@link Builder} for method call chaining.
232		*/
233		public Builder query(final DocumentAssignable query) {
234	3	return setQuery(query);
235		}
236
237		/**
238		* Sets the {@link ReadPreference} specifying which servers may be used
239		* to execute the {@link Distinct} command.
240		* <p>
241		* If not set or set to <code>null</code> then the
242		* {@link MongoCollection} instance's {@link ReadPreference} will be
243		* used.
244		* </p>
245		* <p>
246		* This method delegates to {@link #setReadPreference(ReadPreference)}.
247		* </p>
248		*
249		* @param readPreference
250		* The read preferences specifying which servers may be used.
251		* @return This builder for chaining method calls.
252		*
253		* @see MongoCollection#getReadPreference()
254		*/
255		public Builder readPreference(final ReadPreference readPreference) {
256	2	return setReadPreference(readPreference);
257		}
258
259		/**
260		* Resets the builder back to its initial state.
261		*
262		* @return This {@link Builder} for method call chaining.
263		*/
264		public Builder reset() {
265	19	myKey = null;
266	19	myQuery = null;
267	19	myReadPreference = null;
268	19	myMaximumTimeMilliseconds = 0;
269
270	19	return this;
271		}
272
273		/**
274		* Sets the name of the key to collect distinct values for.
275		*
276		* @param key
277		* The new name of the key to collect distinct values for.
278		* @return This {@link Builder} for method call chaining.
279		*/
280		public Builder setKey(final String key) {
281	18	myKey = key;
282	18	return this;
283		}
284
285		/**
286		* Sets the maximum number of milliseconds to allow the command to run
287		* before aborting the request on the server.
288		*
289		* @param maximumTimeMilliseconds
290		* The new maximum number of milliseconds to allow the
291		* command to run.
292		* @return This {@link Builder} for method call chaining.
293		*
294		* @since MongoDB 2.6
295		*/
296		public Builder setMaximumTimeMilliseconds(
297		final long maximumTimeMilliseconds) {
298	3	myMaximumTimeMilliseconds = maximumTimeMilliseconds;
299	3	return this;
300		}
301
302		/**
303		* Sets the value of the query to select the documents to run the
304		* distinct against.
305		*
306		* @param query
307		* The new value for the query to select the documents to run
308		* the distinct against.
309		* @return This {@link Builder} for method call chaining.
310		*/
311		public Builder setQuery(final DocumentAssignable query) {
312	11	myQuery = query.asDocument();
313	11	return this;
314		}
315
316		/**
317		* Sets the {@link ReadPreference} specifying which servers may be used
318		* to execute the {@link Distinct} command.
319		* <p>
320		* If not set or set to <code>null</code> then the
321		* {@link MongoCollection} instance's {@link ReadPreference} will be
322		* used.
323		* </p>
324		*
325		* @param readPreference
326		* The read preferences specifying which servers may be used.
327		* @return This builder for chaining method calls.
328		*
329		* @see MongoCollection#getReadPreference()
330		*/
331		public Builder setReadPreference(final ReadPreference readPreference) {
332	4	myReadPreference = readPreference;
333	4	return this;
334		}
335		}
336		}