1 /*
2 * #%L
3 * Sort.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.bson.element.IntegerElement;
24 import com.allanbank.mongodb.bson.element.StringElement;
25
26 /**
27 * Provides the ability to easily specify the sort direction for an index or
28 * sort specification.
29 * <p>
30 * MongoDB supports many different index types in addition to the simple
31 * ascending and descending order. See the {@link Index} helper for more
32 * information.
33 * </p>
34 *
35 * @api.yes This class is part of the driver's API. Public and protected members
36 * will be deprecated for at least 1 non-bugfix release (version
37 * numbers are <major>.<minor>.<bugfix>) before being
38 * removed or modified.
39 * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
40 */
41 public final class Sort {
42
43 /** The value to indicate an ascending sort order. */
44 public static final int ASCENDING = 1;
45
46 /** The value to indicate an descending sort order. */
47 public static final int DESCENDING = -1;
48
49 /**
50 * Creates an ascending order specification, e.g.,
51 * <tt>{ <field> : 1 }</tt>.
52 * <p>
53 * This method is equivalent to {@link Index#asc(String)} method.
54 * </p>
55 *
56 * @param field
57 * The field to create the ascending sort on.
58 * @return The ascending sort specification.
59 */
60 public static IntegerElement asc(final String field) {
61 return new IntegerElement(field, ASCENDING);
62 }
63
64 /**
65 * Creates an descending order specification, e.g.,
66 * <tt>{ <field> : -1 }</tt>.
67 * <p>
68 * This method is equivalent to {@link Index#desc(String)} method.
69 * </p>
70 *
71 * @param field
72 * The field to create the descending sort on.
73 * @return The descending sort specification.
74 */
75 public static IntegerElement desc(final String field) {
76 return new IntegerElement(field, DESCENDING);
77 }
78
79 /**
80 * Creates an 2D index specification, e.g.,
81 * <tt>{ <field> : "2d" }</tt>.
82 *
83 * @param field
84 * The field to create the '2d' sort on.
85 * @return The 2D index specification.
86 * @deprecated Moved to the {@link Index} class as {@link Index#geo2d} to
87 * live with the other other index types. This method will be
88 * removed after the 1.3.0 release.
89 */
90 @Deprecated
91 public static StringElement geo2d(final String field) {
92 return Index.geo2d(field);
93 }
94
95 /**
96 * Creates an natural ascending order sort specification, e.g.,
97 * <tt>{ "$natural" : 1 }</tt>.
98 *
99 * @return The natural ascending sort specification.
100 */
101 public static IntegerElement natural() {
102 return natural(ASCENDING);
103 }
104
105 /**
106 * Creates an natural order sort specification with the specified
107 * {@link #ASCENDING} or {@link #DESCENDING} order, e.g.,
108 * <tt>{ "$natural" : <direction> }</tt>.
109 *
110 * @param direction
111 * The direction for the natural ordering, either
112 * {@link #ASCENDING} or {@link #DESCENDING}.
113 * @return The descending sort specification.
114 */
115 public static IntegerElement natural(final int direction) {
116 return new IntegerElement("$natural", direction);
117 }
118
119 /**
120 * Creates a new Sort.
121 */
122 private Sort() {
123 super();
124 }
125 }