Coverage Report

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

Classes in this File

Line Coverage

Branch Coverage

Complexity

AggregationGeoNear

100%

39/39

100%

10/10

1.176

AggregationGeoNear$Builder

97%

43/44

50%

1/2

1.176

 /*
  * #%L
  * AggregationGeoNear.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 static com.allanbank.mongodb.util.Assertions.assertNotNull;
 
 import java.awt.geom.Point2D;
 
 import com.allanbank.mongodb.bson.Document;
 import com.allanbank.mongodb.bson.DocumentAssignable;
 import com.allanbank.mongodb.bson.builder.BuilderFactory;
 import com.allanbank.mongodb.bson.builder.DocumentBuilder;
 
 /**
  * AggregationGeoNear provides the options for the {@code $geoNear} pipeline
  * stage of an aggregation.
  * 
  * @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 2013, Allanbank Consulting, Inc., All Rights Reserved
  * 
  * @since MongoDB 2.4
  */
 public class AggregationGeoNear implements DocumentAssignable {
 
     /**
      * Creates a new builder for an {@link AggregationGeoNear}.
      * 
      * @return The builder to construct an {@link AggregationGeoNear}.
      */
     public static Builder builder() {
         return new Builder();
     }
 
     /**
      * The name of the field to place the distance from the source
      * {@link #getLocation() location}.
      */
     private final String myDistanceField;
 
     /**
      * The distance multiplier to use in the {@code $geoNear}, if set.
      * <code>null</code> otherwise.
      */
     private final Double myDistanceMultiplier;
 
     /**
      * The maximum number of documents to return, if set. <code>null</code>
      * otherwise.
      */
     private final Long myLimit;
 
     /** The location to find documents near. */
     private final Point2D myLocation;
 
     /**
      * The name of the field to place the location information from the
      * document, if set. <code>null</code> otherwise.
      */
     private final String myLocationField;
 
     /**
      * The maximum distance to return documents from the specified location, if
      * set. <code>null</code> otherwise.
      */
     private final Double myMaxDistance;
 
     /**
      * The optional query for further refining the documents to add to the
      * pipeline.
      */
     private final Document myQuery;
 
     /**
      * If true the {@code $geoNear} should compute distances using spherical
      * coordinates instead of planar coordinates. Defaults to false.
      */
     private final boolean mySpherical;
 
     /**
      * If true the {@code $geoNear} should only return documents once. Defaults
      * to true.
      */
     private final boolean myUniqueDocs;
 
     /**
      * Creates a new AggregationGeoNear.
      * 
      * @param builder
      *            he builder for the AggregationGeoNear stage.
      * @throws IllegalArgumentException
      *             If the {@link #getLocation() location} or
      *             {@link #getDistanceField() distance field} have not been set.
      */
     protected AggregationGeoNear(final Builder builder)
             throws IllegalArgumentException {
 
         assertNotNull(builder.myLocation, "You must specify a location for "
                 + "a geoNear in an aggregation pipeline.");
         assertNotEmpty(builder.myDistanceField,
                 "You must specify a distance field locations for "
                         + "a geoNear in an aggregation pipeline.");
 
         myDistanceField = builder.myDistanceField;
         myDistanceMultiplier = builder.myDistanceMultiplier;
         myLocationField = builder.myLocationField;
         myLimit = builder.myLimit;
         myLocation = builder.myLocation;
         myMaxDistance = builder.myMaxDistance;
         myQuery = builder.myQuery;
         mySpherical = builder.mySpherical;
         myUniqueDocs = builder.myUniqueDocs;
     }
 
     /**
      * {@inheritDoc}
      * <p>
      * Overridden to return the $geoNear aggregation pipeline's options
      * document. This does not include the $geoNear operator, just the options
      * document.
      * </p>
      */
     @Override
     public Document asDocument() {
         final DocumentBuilder builder = BuilderFactory.start();
 
         GeoJson.addRaw(builder.pushArray("near"), myLocation);
         builder.add("distanceField", myDistanceField);
         builder.add("spherical", mySpherical);
         builder.add("uniqueDocs", myUniqueDocs);
 
         if (myLimit != null) {
             builder.add("limit", myLimit.longValue());
         }
         if (myMaxDistance != null) {
             builder.add("maxDistance", myMaxDistance);
         }
         if (myQuery != null) {
             builder.add("query", myQuery);
         }
         if (myDistanceMultiplier != null) {
             builder.add("distanceMultiplier",
                     myDistanceMultiplier.doubleValue());
         }
         if (myLocationField != null) {
             builder.add("includeLocs", myLocationField);
         }
 
         return builder.build();
     }
 
     /**
      * Returns the name of the field to place the distance from the source
      * {@link #getLocation() location}.
      * 
      * @return The name of the field to place the distance from the source
      *         {@link #getLocation() location}.
      */
     public String getDistanceField() {
         return myDistanceField;
     }
 
     /**
      * If set returns the distance multiplier to use in the {@code $geoNear}.
      * 
      * @return The distance multiplier to use in the {@code $geoNear}, if set.
      *         <code>null</code> otherwise.
      */
     public Double getDistanceMultiplier() {
         return myDistanceMultiplier;
     }
 
     /**
      * If set returns the maximum number of documents to return.
      * 
      * @return The maximum number of documents to return, if set.
      *         <code>null</code> otherwise.
      */
     public Long getLimit() {
         return myLimit;
     }
 
     /**
      * Returns the location to find documents near.
      * 
      * @return The location to find documents near.
      */
     public Point2D getLocation() {
         return myLocation;
     }
 
     /**
      * If set returns the name of the field to place the location information
      * from the document.
      * 
      * @return The name of the field to place the location information from the
      *         document, if set. <code>null</code> otherwise.
      */
     public String getLocationField() {
         return myLocationField;
     }
 
     /**
      * If set returns the maximum distance to return documents from the
      * specified location
      * 
      * @return The maximum distance to return documents from the specified
      *         location, if set. <code>null</code> otherwise.
      */
     public Double getMaxDistance() {
         return myMaxDistance;
     }
 
     /**
      * If set returns the optional query for further refining the documents to
      * add to the pipeline.
      * 
      * @return The optional query for further refining the documents to add to
      *         the pipeline, if set. <code>null</code> otherwise.
      */
     public Document getQuery() {
         return myQuery;
     }
 
     /**
      * Returns true if the {@code $geoNear} should compute distances using
      * spherical coordinates instead of planar coordinates. Defaults to false.
      * 
      * @return True if the {@code $geoNear} should compute distances using
      *         spherical coordinates instead of planar coordinates.
      */
     public boolean isSpherical() {
         return mySpherical;
     }
 
     /**
      * Returns true if the {@code $geoNear} should only return documents once.
      * Defaults to true.
      * 
      * @return True if the {@code $geoNear} should only return documents once.
      */
     public boolean isUniqueDocs() {
         return myUniqueDocs;
     }
 
     /**
      * Helper for creating immutable {@link Find} queries.
      * 
      * @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 2013, Allanbank Consulting, Inc., All Rights Reserved
      */
     public static class Builder {
         /**
          * The name of the field to place the distance from the source
          * {@link #getLocation() location}.
          */
         protected String myDistanceField;
 
         /**
          * The distance multiplier to use in the {@code $geoNear}, if set.
          * <code>null</code> otherwise.
          */
         protected Double myDistanceMultiplier;
 
         /**
          * The maximum number of documents to return, if set. <code>null</code>
          * otherwise.
          */
         protected Long myLimit;
 
         /** The location to find documents near. */
         protected Point2D myLocation;
 
         /**
          * The name of the field to place the location information from the
          * document, if set. <code>null</code> otherwise.
          */
         protected String myLocationField;
 
         /**
          * The maximum distance to return documents from the specified location,
          * if set. <code>null</code> otherwise.
          */
         protected Double myMaxDistance;
 
         /**
          * The optional query for further refining the documents to add to the
          * pipeline.
          */
         protected Document myQuery;
 
         /**
          * If true the {@code $geoNear} should compute distances using spherical
          * coordinates instead of planar coordinates. Defaults to false.
          */
         protected boolean mySpherical;
 
         /**
          * If true the {@code $geoNear} should only return documents once.
          * Defaults to true.
          */
         protected boolean myUniqueDocs;
 
         /**
          * Creates a new Builder.
          */
         public Builder() {
             reset();
         }
 
         /**
          * Constructs a new {@link AggregationGeoNear} object from the state of
          * the builder.
          * 
          * @return The new {@link AggregationGeoNear} object.
          * @throws IllegalArgumentException
          *             If the {@link #setLocation(Point2D) location} or
          *             {@link #setDistanceField(String) distance field} have not
          *             been set.
          */
         public AggregationGeoNear build() {
             return new AggregationGeoNear(this);
         }
 
         /**
          * Sets the name of the field to place the distance from the source
          * {@link #getLocation() location}.
          * <p>
          * This method delegates to {@link #setDistanceField(String)}.
          * </p>
          * 
          * @param distanceField
          *            The new name of the field to place the distance from the
          *            source {@link #setLocation(Point2D) location}.
          * @return This builder for chaining method calls.
          */
         public Builder distanceField(final String distanceField) {
             return setDistanceField(distanceField);
         }
 
         /**
          * Sets the distance multiplier to use in the {@code $geoNear}.
          * <p>
          * This method delegates to {@link #setDistanceMultiplier(double)}.
          * </p>
          * 
          * @param distanceMultiplier
          *            The new distance multiplier to use in the {@code $geoNear}
          *            .
          * @return This builder for chaining method calls.
          */
         public Builder distanceMultiplier(final double distanceMultiplier) {
             return setDistanceMultiplier(distanceMultiplier);
         }
 
         /**
          * Sets the maximum number of documents to return.
          * <p>
          * This method delegates to {@link #setLimit(long)}.
          * </p>
          * 
          * @param limit
          *            The new maximum number of documents to return.
          * @return This builder for chaining method calls.
          */
         public Builder limit(final long limit) {
             return setLimit(limit);
         }
 
         /**
          * Sets the location to find documents near.
          * <p>
          * This method delegates to {@link #setLocation(Point2D)}.
          * </p>
          * 
          * @param location
          *            The new location to find documents near.
          * @return This builder for chaining method calls.
          * @see GeoJson#p
          */
         public Builder location(final Point2D location) {
             return setLocation(location);
         }
 
         /**
          * Sets the name of the field to place the location information from the
          * document.
          * <p>
          * This method delegates to {@link #setLocationField(String)}.
          * </p>
          * 
          * @param locationField
          *            The new name of the field to place the location
          *            information from the document.
          * @return This builder for chaining method calls.
          */
         public Builder locationField(final String locationField) {
             return setLocationField(locationField);
         }
 
         /**
          * Sets the maximum distance to return documents from the specified
          * location.
          * <p>
          * This method delegates to {@link #setMaxDistance(double)}.
          * </p>
          * 
          * @param maxDistance
          *            The new maximum distance to return documents from the
          *            specified location.
          * @return This builder for chaining method calls.
          */
         public Builder maxDistance(final double maxDistance) {
             return setMaxDistance(maxDistance);
         }
 
         /**
          * Sets the optional query for further refining the documents to add to
          * the pipeline.
          * <p>
          * This method delegates to {@link #setQuery(DocumentAssignable)}.
          * </p>
          * 
          * @param query
          *            The new optional query for further refining the documents
          *            to add to the pipeline.
          * @return This builder for chaining method calls.
          */
         public Builder query(final DocumentAssignable query) {
             return setQuery(query);
         }
 
         /**
          * Resets the builder back to its initial state for reuse.
          * 
          * @return This builder for chaining method calls.
          */
         public Builder reset() {
             myDistanceField = null;
             myDistanceMultiplier = null;
             myLimit = null;
             myLocation = null;
             myLocationField = null;
             myMaxDistance = null;
             myQuery = null;
             mySpherical = false;
             myUniqueDocs = true;
             return this;
         }
 
         /**
          * Sets the name of the field to place the distance from the source
          * {@link #getLocation() location}.
          * 
          * @param distanceField
          *            The new name of the field to place the distance from the
          *            source {@link #setLocation(Point2D) location}.
          * @return This builder for chaining method calls.
          */
         public Builder setDistanceField(final String distanceField) {
             myDistanceField = distanceField;
             return this;
         }
 
         /**
          * Sets the distance multiplier to use in the {@code $geoNear}.
          * 
          * @param distanceMultiplier
          *            The new distance multiplier to use in the {@code $geoNear}
          *            .
          * @return This builder for chaining method calls.
          */
         public Builder setDistanceMultiplier(final double distanceMultiplier) {
             myDistanceMultiplier = Double.valueOf(distanceMultiplier);
             return this;
         }
 
         /**
          * Sets the maximum number of documents to return.
          * 
          * @param limit
          *            The new maximum number of documents to return.
          * @return This builder for chaining method calls.
          */
         public Builder setLimit(final long limit) {
             myLimit = Long.valueOf(limit);
             return this;
         }
 
         /**
          * Sets the location to find documents near.
          * 
          * @param location
          *            The new location to find documents near.
          * @return This builder for chaining method calls.
          * @see GeoJson#p
          */
         public Builder setLocation(final Point2D location) {
             myLocation = location;
             return this;
         }
 
         /**
          * Sets the name of the field to place the location information from the
          * document.
          * 
          * @param locationField
          *            The new name of the field to place the location
          *            information from the document.
          * @return This builder for chaining method calls.
          */
         public Builder setLocationField(final String locationField) {
             myLocationField = locationField;
             return this;
         }
 
         /**
          * Sets the maximum distance to return documents from the specified
          * location.
          * 
          * @param maxDistance
          *            The new maximum distance to return documents from the
          *            specified location.
          * @return This builder for chaining method calls.
          */
         public Builder setMaxDistance(final double maxDistance) {
             myMaxDistance = Double.valueOf(maxDistance);
             return this;
         }
 
         /**
          * Sets the optional query for further refining the documents to add to
          * the pipeline.
          * 
          * @param query
          *            The new optional query for further refining the documents
          *            to add to the pipeline.
          * @return This builder for chaining method calls.
          */
         public Builder setQuery(final DocumentAssignable query) {
             if (query != null) {
                 myQuery = query.asDocument();
             }
             else {
                 myQuery = null;
             }
             return this;
         }
 
         /**
          * Sets if (true) the {@code $geoNear} should compute distances using
          * spherical coordinates instead of planar coordinates. Defaults to
          * false.
          * 
          * @param spherical
          *            The new value for if the {@code $geoNear} should compute
          *            distances using spherical coordinates instead of planar
          *            coordinates
          * @return This builder for chaining method calls.
          */
         public Builder setSpherical(final boolean spherical) {
             mySpherical = spherical;
             return this;
         }
 
         /**
          * Sets if (true) the {@code $geoNear} should only return documents
          * once. Defaults to true.
          * 
          * @param uniqueDocs
          *            The new value for if the {@code $geoNear} should only
          *            return documents once.
          * @return This builder for chaining method calls.
          */
         public Builder setUniqueDocs(final boolean uniqueDocs) {
             myUniqueDocs = uniqueDocs;
             return this;
         }
 
         /**
          * Sets the {@code $geoNear} to compute distances using spherical
          * coordinates instead of planar coordinates.
          * <p>
          * This method delegates to {@link #setSpherical(boolean)
          * setSpherical(true)}.
          * </p>
          * 
          * 
          * @return This builder for chaining method calls.
          */
         public Builder spherical() {
             return setSpherical(true);
         }
 
         /**
          * Sets if (true) the {@code $geoNear} should compute distances using
          * spherical coordinates instead of planar coordinates. Defaults to
          * false.
          * <p>
          * This method delegates to {@link #setSpherical(boolean)}.
          * </p>
          * 
          * @param spherical
          *            The new value for if the {@code $geoNear} should compute
          *            distances using spherical coordinates instead of planar
          *            coordinates
          * @return This builder for chaining method calls.
          */
         public Builder spherical(final boolean spherical) {
             return setSpherical(spherical);
         }
 
         /**
          * Sets if (true) the {@code $geoNear} should only return documents
          * once. Defaults to true.
          * <p>
          * This method delegates to {@link #setUniqueDocs(boolean)}.
          * </p>
          * 
          * @param uniqueDocs
          *            The new value for if the {@code $geoNear} should only
          *            return documents once.
          * @return This builder for chaining method calls.
          */
         public Builder uniqueDocs(final boolean uniqueDocs) {
             return setUniqueDocs(uniqueDocs);
         }
     }
 }

1		/*
2		* #%L
3		* AggregationGeoNear.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		import static com.allanbank.mongodb.util.Assertions.assertNotNull;
25
26		import java.awt.geom.Point2D;
27
28		import com.allanbank.mongodb.bson.Document;
29		import com.allanbank.mongodb.bson.DocumentAssignable;
30		import com.allanbank.mongodb.bson.builder.BuilderFactory;
31		import com.allanbank.mongodb.bson.builder.DocumentBuilder;
32
33		/**
34		* AggregationGeoNear provides the options for the {@code $geoNear} pipeline
35		* stage of an aggregation.
36		*
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 2013, Allanbank Consulting, Inc., All Rights Reserved
42		*
43		* @since MongoDB 2.4
44		*/
45		public class AggregationGeoNear implements DocumentAssignable {
46
47		/**
48		* Creates a new builder for an {@link AggregationGeoNear}.
49		*
50		* @return The builder to construct an {@link AggregationGeoNear}.
51		*/
52		public static Builder builder() {
53	7	return new Builder();
54		}
55
56		/**
57		* The name of the field to place the distance from the source
58		* {@link #getLocation() location}.
59		*/
60		private final String myDistanceField;
61
62		/**
63		* The distance multiplier to use in the {@code $geoNear}, if set.
64		* <code>null</code> otherwise.
65		*/
66		private final Double myDistanceMultiplier;
67
68		/**
69		* The maximum number of documents to return, if set. <code>null</code>
70		* otherwise.
71		*/
72		private final Long myLimit;
73
74		/** The location to find documents near. */
75		private final Point2D myLocation;
76
77		/**
78		* The name of the field to place the location information from the
79		* document, if set. <code>null</code> otherwise.
80		*/
81		private final String myLocationField;
82
83		/**
84		* The maximum distance to return documents from the specified location, if
85		* set. <code>null</code> otherwise.
86		*/
87		private final Double myMaxDistance;
88
89		/**
90		* The optional query for further refining the documents to add to the
91		* pipeline.
92		*/
93		private final Document myQuery;
94
95		/**
96		* If true the {@code $geoNear} should compute distances using spherical
97		* coordinates instead of planar coordinates. Defaults to false.
98		*/
99		private final boolean mySpherical;
100
101		/**
102		* If true the {@code $geoNear} should only return documents once. Defaults
103		* to true.
104		*/
105		private final boolean myUniqueDocs;
106
107		/**
108		* Creates a new AggregationGeoNear.
109		*
110		* @param builder
111		* he builder for the AggregationGeoNear stage.
112		* @throws IllegalArgumentException
113		* If the {@link #getLocation() location} or
114		* {@link #getDistanceField() distance field} have not been set.
115		*/
116		protected AggregationGeoNear(final Builder builder)
117	9	throws IllegalArgumentException {
118
119	9	assertNotNull(builder.myLocation, "You must specify a location for "
120		+ "a geoNear in an aggregation pipeline.");
121	7	assertNotEmpty(builder.myDistanceField,
122		"You must specify a distance field locations for "
123		+ "a geoNear in an aggregation pipeline.");
124
125	6	myDistanceField = builder.myDistanceField;
126	6	myDistanceMultiplier = builder.myDistanceMultiplier;
127	6	myLocationField = builder.myLocationField;
128	6	myLimit = builder.myLimit;
129	6	myLocation = builder.myLocation;
130	6	myMaxDistance = builder.myMaxDistance;
131	6	myQuery = builder.myQuery;
132	6	mySpherical = builder.mySpherical;
133	6	myUniqueDocs = builder.myUniqueDocs;
134	6	}
135
136		/**
137		* {@inheritDoc}
138		* <p>
139		* Overridden to return the $geoNear aggregation pipeline's options
140		* document. This does not include the $geoNear operator, just the options
141		* document.
142		* </p>
143		*/
144		@Override
145		public Document asDocument() {
146	4	final DocumentBuilder builder = BuilderFactory.start();
147
148	4	GeoJson.addRaw(builder.pushArray("near"), myLocation);
149	4	builder.add("distanceField", myDistanceField);
150	4	builder.add("spherical", mySpherical);
151	4	builder.add("uniqueDocs", myUniqueDocs);
152
153	4	if (myLimit != null) {
154	3	builder.add("limit", myLimit.longValue());
155		}
156	4	if (myMaxDistance != null) {
157	3	builder.add("maxDistance", myMaxDistance);
158		}
159	4	if (myQuery != null) {
160	3	builder.add("query", myQuery);
161		}
162	4	if (myDistanceMultiplier != null) {
163	3	builder.add("distanceMultiplier",
164		myDistanceMultiplier.doubleValue());
165		}
166	4	if (myLocationField != null) {
167	3	builder.add("includeLocs", myLocationField);
168		}
169
170	4	return builder.build();
171		}
172
173		/**
174		* Returns the name of the field to place the distance from the source
175		* {@link #getLocation() location}.
176		*
177		* @return The name of the field to place the distance from the source
178		* {@link #getLocation() location}.
179		*/
180		public String getDistanceField() {
181	5	return myDistanceField;
182		}
183
184		/**
185		* If set returns the distance multiplier to use in the {@code $geoNear}.
186		*
187		* @return The distance multiplier to use in the {@code $geoNear}, if set.
188		* <code>null</code> otherwise.
189		*/
190		public Double getDistanceMultiplier() {
191	5	return myDistanceMultiplier;
192		}
193
194		/**
195		* If set returns the maximum number of documents to return.
196		*
197		* @return The maximum number of documents to return, if set.
198		* <code>null</code> otherwise.
199		*/
200		public Long getLimit() {
201	5	return myLimit;
202		}
203
204		/**
205		* Returns the location to find documents near.
206		*
207		* @return The location to find documents near.
208		*/
209		public Point2D getLocation() {
210	5	return myLocation;
211		}
212
213		/**
214		* If set returns the name of the field to place the location information
215		* from the document.
216		*
217		* @return The name of the field to place the location information from the
218		* document, if set. <code>null</code> otherwise.
219		*/
220		public String getLocationField() {
221	5	return myLocationField;
222		}
223
224		/**
225		* If set returns the maximum distance to return documents from the
226		* specified location
227		*
228		* @return The maximum distance to return documents from the specified
229		* location, if set. <code>null</code> otherwise.
230		*/
231		public Double getMaxDistance() {
232	5	return myMaxDistance;
233		}
234
235		/**
236		* If set returns the optional query for further refining the documents to
237		* add to the pipeline.
238		*
239		* @return The optional query for further refining the documents to add to
240		* the pipeline, if set. <code>null</code> otherwise.
241		*/
242		public Document getQuery() {
243	5	return myQuery;
244		}
245
246		/**
247		* Returns true if the {@code $geoNear} should compute distances using
248		* spherical coordinates instead of planar coordinates. Defaults to false.
249		*
250		* @return True if the {@code $geoNear} should compute distances using
251		* spherical coordinates instead of planar coordinates.
252		*/
253		public boolean isSpherical() {
254	5	return mySpherical;
255		}
256
257		/**
258		* Returns true if the {@code $geoNear} should only return documents once.
259		* Defaults to true.
260		*
261		* @return True if the {@code $geoNear} should only return documents once.
262		*/
263		public boolean isUniqueDocs() {
264	5	return myUniqueDocs;
265		}
266
267		/**
268		* Helper for creating immutable {@link Find} queries.
269		*
270		* @api.yes This class is part of the driver's API. Public and protected
271		* members will be deprecated for at least 1 non-bugfix release
272		* (version numbers are <major>.<minor>.<bugfix>)
273		* before being removed or modified.
274		* @copyright 2013, Allanbank Consulting, Inc., All Rights Reserved
275		*/
276		public static class Builder {
277		/**
278		* The name of the field to place the distance from the source
279		* {@link #getLocation() location}.
280		*/
281		protected String myDistanceField;
282
283		/**
284		* The distance multiplier to use in the {@code $geoNear}, if set.
285		* <code>null</code> otherwise.
286		*/
287		protected Double myDistanceMultiplier;
288
289		/**
290		* The maximum number of documents to return, if set. <code>null</code>
291		* otherwise.
292		*/
293		protected Long myLimit;
294
295		/** The location to find documents near. */
296		protected Point2D myLocation;
297
298		/**
299		* The name of the field to place the location information from the
300		* document, if set. <code>null</code> otherwise.
301		*/
302		protected String myLocationField;
303
304		/**
305		* The maximum distance to return documents from the specified location,
306		* if set. <code>null</code> otherwise.
307		*/
308		protected Double myMaxDistance;
309
310		/**
311		* The optional query for further refining the documents to add to the
312		* pipeline.
313		*/
314		protected Document myQuery;
315
316		/**
317		* If true the {@code $geoNear} should compute distances using spherical
318		* coordinates instead of planar coordinates. Defaults to false.
319		*/
320		protected boolean mySpherical;
321
322		/**
323		* If true the {@code $geoNear} should only return documents once.
324		* Defaults to true.
325		*/
326		protected boolean myUniqueDocs;
327
328		/**
329		* Creates a new Builder.
330		*/
331	7	public Builder() {
332	7	reset();
333	7	}
334
335		/**
336		* Constructs a new {@link AggregationGeoNear} object from the state of
337		* the builder.
338		*
339		* @return The new {@link AggregationGeoNear} object.
340		* @throws IllegalArgumentException
341		* If the {@link #setLocation(Point2D) location} or
342		* {@link #setDistanceField(String) distance field} have not
343		* been set.
344		*/
345		public AggregationGeoNear build() {
346	9	return new AggregationGeoNear(this);
347		}
348
349		/**
350		* Sets the name of the field to place the distance from the source
351		* {@link #getLocation() location}.
352		* <p>
353		* This method delegates to {@link #setDistanceField(String)}.
354		* </p>
355		*
356		* @param distanceField
357		* The new name of the field to place the distance from the
358		* source {@link #setLocation(Point2D) location}.
359		* @return This builder for chaining method calls.
360		*/
361		public Builder distanceField(final String distanceField) {
362	8	return setDistanceField(distanceField);
363		}
364
365		/**
366		* Sets the distance multiplier to use in the {@code $geoNear}.
367		* <p>
368		* This method delegates to {@link #setDistanceMultiplier(double)}.
369		* </p>
370		*
371		* @param distanceMultiplier
372		* The new distance multiplier to use in the {@code $geoNear}
373		* .
374		* @return This builder for chaining method calls.
375		*/
376		public Builder distanceMultiplier(final double distanceMultiplier) {
377	4	return setDistanceMultiplier(distanceMultiplier);
378		}
379
380		/**
381		* Sets the maximum number of documents to return.
382		* <p>
383		* This method delegates to {@link #setLimit(long)}.
384		* </p>
385		*
386		* @param limit
387		* The new maximum number of documents to return.
388		* @return This builder for chaining method calls.
389		*/
390		public Builder limit(final long limit) {
391	4	return setLimit(limit);
392		}
393
394		/**
395		* Sets the location to find documents near.
396		* <p>
397		* This method delegates to {@link #setLocation(Point2D)}.
398		* </p>
399		*
400		* @param location
401		* The new location to find documents near.
402		* @return This builder for chaining method calls.
403		* @see GeoJson#p
404		*/
405		public Builder location(final Point2D location) {
406	8	return setLocation(location);
407		}
408
409		/**
410		* Sets the name of the field to place the location information from the
411		* document.
412		* <p>
413		* This method delegates to {@link #setLocationField(String)}.
414		* </p>
415		*
416		* @param locationField
417		* The new name of the field to place the location
418		* information from the document.
419		* @return This builder for chaining method calls.
420		*/
421		public Builder locationField(final String locationField) {
422	4	return setLocationField(locationField);
423		}
424
425		/**
426		* Sets the maximum distance to return documents from the specified
427		* location.
428		* <p>
429		* This method delegates to {@link #setMaxDistance(double)}.
430		* </p>
431		*
432		* @param maxDistance
433		* The new maximum distance to return documents from the
434		* specified location.
435		* @return This builder for chaining method calls.
436		*/
437		public Builder maxDistance(final double maxDistance) {
438	4	return setMaxDistance(maxDistance);
439		}
440
441		/**
442		* Sets the optional query for further refining the documents to add to
443		* the pipeline.
444		* <p>
445		* This method delegates to {@link #setQuery(DocumentAssignable)}.
446		* </p>
447		*
448		* @param query
449		* The new optional query for further refining the documents
450		* to add to the pipeline.
451		* @return This builder for chaining method calls.
452		*/
453		public Builder query(final DocumentAssignable query) {
454	4	return setQuery(query);
455		}
456
457		/**
458		* Resets the builder back to its initial state for reuse.
459		*
460		* @return This builder for chaining method calls.
461		*/
462		public Builder reset() {
463	8	myDistanceField = null;
464	8	myDistanceMultiplier = null;
465	8	myLimit = null;
466	8	myLocation = null;
467	8	myLocationField = null;
468	8	myMaxDistance = null;
469	8	myQuery = null;
470	8	mySpherical = false;
471	8	myUniqueDocs = true;
472	8	return this;
473		}
474
475		/**
476		* Sets the name of the field to place the distance from the source
477		* {@link #getLocation() location}.
478		*
479		* @param distanceField
480		* The new name of the field to place the distance from the
481		* source {@link #setLocation(Point2D) location}.
482		* @return This builder for chaining method calls.
483		*/
484		public Builder setDistanceField(final String distanceField) {
485	8	myDistanceField = distanceField;
486	8	return this;
487		}
488
489		/**
490		* Sets the distance multiplier to use in the {@code $geoNear}.
491		*
492		* @param distanceMultiplier
493		* The new distance multiplier to use in the {@code $geoNear}
494		* .
495		* @return This builder for chaining method calls.
496		*/
497		public Builder setDistanceMultiplier(final double distanceMultiplier) {
498	4	myDistanceMultiplier = Double.valueOf(distanceMultiplier);
499	4	return this;
500		}
501
502		/**
503		* Sets the maximum number of documents to return.
504		*
505		* @param limit
506		* The new maximum number of documents to return.
507		* @return This builder for chaining method calls.
508		*/
509		public Builder setLimit(final long limit) {
510	4	myLimit = Long.valueOf(limit);
511	4	return this;
512		}
513
514		/**
515		* Sets the location to find documents near.
516		*
517		* @param location
518		* The new location to find documents near.
519		* @return This builder for chaining method calls.
520		* @see GeoJson#p
521		*/
522		public Builder setLocation(final Point2D location) {
523	8	myLocation = location;
524	8	return this;
525		}
526
527		/**
528		* Sets the name of the field to place the location information from the
529		* document.
530		*
531		* @param locationField
532		* The new name of the field to place the location
533		* information from the document.
534		* @return This builder for chaining method calls.
535		*/
536		public Builder setLocationField(final String locationField) {
537	4	myLocationField = locationField;
538	4	return this;
539		}
540
541		/**
542		* Sets the maximum distance to return documents from the specified
543		* location.
544		*
545		* @param maxDistance
546		* The new maximum distance to return documents from the
547		* specified location.
548		* @return This builder for chaining method calls.
549		*/
550		public Builder setMaxDistance(final double maxDistance) {
551	4	myMaxDistance = Double.valueOf(maxDistance);
552	4	return this;
553		}
554
555		/**
556		* Sets the optional query for further refining the documents to add to
557		* the pipeline.
558		*
559		* @param query
560		* The new optional query for further refining the documents
561		* to add to the pipeline.
562		* @return This builder for chaining method calls.
563		*/
564		public Builder setQuery(final DocumentAssignable query) {
565	4	if (query != null) {
566	4	myQuery = query.asDocument();
567		}
568		else {
569	0	myQuery = null;
570		}
571	4	return this;
572		}
573
574		/**
575		* Sets if (true) the {@code $geoNear} should compute distances using
576		* spherical coordinates instead of planar coordinates. Defaults to
577		* false.
578		*
579		* @param spherical
580		* The new value for if the {@code $geoNear} should compute
581		* distances using spherical coordinates instead of planar
582		* coordinates
583		* @return This builder for chaining method calls.
584		*/
585		public Builder setSpherical(final boolean spherical) {
586	4	mySpherical = spherical;
587	4	return this;
588		}
589
590		/**
591		* Sets if (true) the {@code $geoNear} should only return documents
592		* once. Defaults to true.
593		*
594		* @param uniqueDocs
595		* The new value for if the {@code $geoNear} should only
596		* return documents once.
597		* @return This builder for chaining method calls.
598		*/
599		public Builder setUniqueDocs(final boolean uniqueDocs) {
600	4	myUniqueDocs = uniqueDocs;
601	4	return this;
602		}
603
604		/**
605		* Sets the {@code $geoNear} to compute distances using spherical
606		* coordinates instead of planar coordinates.
607		* <p>
608		* This method delegates to {@link #setSpherical(boolean)
609		* setSpherical(true)}.
610		* </p>
611		*
612		*
613		* @return This builder for chaining method calls.
614		*/
615		public Builder spherical() {
616	2	return setSpherical(true);
617		}
618
619		/**
620		* Sets if (true) the {@code $geoNear} should compute distances using
621		* spherical coordinates instead of planar coordinates. Defaults to
622		* false.
623		* <p>
624		* This method delegates to {@link #setSpherical(boolean)}.
625		* </p>
626		*
627		* @param spherical
628		* The new value for if the {@code $geoNear} should compute
629		* distances using spherical coordinates instead of planar
630		* coordinates
631		* @return This builder for chaining method calls.
632		*/
633		public Builder spherical(final boolean spherical) {
634	2	return setSpherical(spherical);
635		}
636
637		/**
638		* Sets if (true) the {@code $geoNear} should only return documents
639		* once. Defaults to true.
640		* <p>
641		* This method delegates to {@link #setUniqueDocs(boolean)}.
642		* </p>
643		*
644		* @param uniqueDocs
645		* The new value for if the {@code $geoNear} should only
646		* return documents once.
647		* @return This builder for chaining method calls.
648		*/
649		public Builder uniqueDocs(final boolean uniqueDocs) {
650	4	return setUniqueDocs(uniqueDocs);
651		}
652		}
653		}