View Javadoc
1   /*
2    * #%L
3    * GeospatialOperator.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.Version;
24  
25  /**
26   * GeospatialOperator provides the enumeration of geospatial operators.
27   * 
28   * @api.yes This enumeration is part of the driver's API. Public and protected
29   *          members will be deprecated for at least 1 non-bugfix release
30   *          (version numbers are <major>.<minor>.<bugfix>)
31   *          before being removed or modified.
32   * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
33   */
34  public enum GeospatialOperator implements Operator {
35  
36      /**
37       * Operator to return documents that are within a GeoJSON shape.
38       * 
39       * @since MongoDB 2.4
40       */
41      GEO_WITHIN("$geoWithin", Version.VERSION_2_4),
42  
43      /**
44       * Operator to return documents that intersect the GeoJSON shape.
45       * 
46       * @since MongoDB 2.4
47       */
48      INTERSECT("$geoIntersects", Version.VERSION_2_4),
49  
50      /**
51       * The modifier for the {@link #NEAR} operator to limit the documents
52       * returned based on their distance from the the center point.
53       */
54      MAX_DISTANCE_MODIFIER("$maxDistance"),
55  
56      /** Operator to return documents near a given point. */
57      NEAR("$near"),
58  
59      /** Operator to return documents near a given point. */
60      NEAR_SPHERE("$nearSphere"),
61  
62      /** Operator to return documents within a bounding shape. */
63      WITHIN("$within");
64  
65      /** The name for the rectangular region with a {@link #WITHIN} query. */
66      public static final String BOX = "$box";
67  
68      /** The name for the circular region with a {@link #WITHIN} query. */
69      public static final String CIRCLE = "$center";
70  
71      /** The name for the GeoJSON region with a {@link #INTERSECT} query. */
72      public static final String GEOMETRY = "$geometry";
73  
74      /**
75       * The name for the polygon region with a {@link #WITHIN} query.
76       * 
77       * @since MongoDB 2.0
78       */
79      public static final String POLYGON = "$polygon";
80  
81      /**
82       * The version (2.0) of the MongoDB server that added support for the
83       * {@value #POLYGON} modifier of {@link #WITHIN $within}
84       */
85      public static final Version POLYGON_VERSION = Version.parse("2.0");
86  
87      /**
88       * The name for the circular region on a sphere with a {@link #WITHIN}
89       * query.
90       */
91      public static final String SPHERICAL_CIRCLE = "$centerSphere";
92  
93      /**
94       * The modifier for the {@link #WITHIN} operator to determine if duplicate
95       * documents should be returned.
96       * 
97       * @deprecated Support for {@value} was removed in MongoDB 2.6.
98       */
99      @Deprecated
100     public static final String UNIQUE_DOCS_MODIFIER = "$uniqueDocs";
101 
102     /**
103      * The version (2.5) of the MongoDB server that removed support for the
104      * {@value #UNIQUE_DOCS_MODIFIER} modifier.
105      */
106     public static final Version UNIQUE_DOCS_REMOVED_VERSION = Version
107             .parse("2.5");
108 
109     /** The operator's token to use when sending to the server. */
110     private final String myToken;
111 
112     /** The first MongoDB version to support the operator. */
113     private final Version myVersion;
114 
115     /**
116      * Creates a new GeospatialOperator.
117      * 
118      * @param token
119      *            The token to use when sending to the server.
120      */
121     private GeospatialOperator(final String token) {
122         this(token, null);
123     }
124 
125     /**
126      * Creates a new GeospatialOperator.
127      * 
128      * @param token
129      *            The token to use when sending to the server.
130      * @param version
131      *            The first MongoDB version to support the operator.
132      */
133     private GeospatialOperator(final String token, final Version version) {
134         myToken = token;
135         myVersion = version;
136     }
137 
138     /**
139      * The token for the operator that can be sent to the server.
140      * 
141      * @return The token for the operator.
142      */
143     @Override
144     public String getToken() {
145         return myToken;
146     }
147 
148     /**
149      * Returns the first MongoDB version to support the operator.
150      * 
151      * @return The first MongoDB version to support the operator. If
152      *         <code>null</code> then the version is not known and can be
153      *         assumed to be all currently supported versions.
154      */
155     @Override
156     public Version getVersion() {
157         return myVersion;
158     }
159 }