1 | /* |
2 | * Copyright 2012 the original author or authors. |
3 | * |
4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
5 | * you may not use this file except in compliance with the License. |
6 | * You may obtain a copy of the License at |
7 | * |
8 | * http://www.apache.org/licenses/LICENSE-2.0 |
9 | * |
10 | * Unless required by applicable law or agreed to in writing, software |
11 | * distributed under the License is distributed on an "AS IS" BASIS, |
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
13 | * See the License for the specific language governing permissions and |
14 | * limitations under the License. |
15 | */ |
16 | package org.springframework.data.elasticsearch.core.query; |
17 | |
18 | import java.util.ArrayList; |
19 | import java.util.Arrays; |
20 | import java.util.Collection; |
21 | import java.util.Collections; |
22 | import java.util.LinkedHashSet; |
23 | import java.util.List; |
24 | import java.util.Set; |
25 | |
26 | import org.apache.commons.lang.StringUtils; |
27 | import org.springframework.dao.InvalidDataAccessApiUsageException; |
28 | import org.springframework.util.Assert; |
29 | |
30 | /** |
31 | * Criteria is the central class when constructing queries. It follows more or less a fluent API style, which allows to |
32 | * easily chain together multiple criteria. |
33 | * |
34 | */ |
35 | public class Criteria { |
36 | |
37 | public static final String WILDCARD = "*"; |
38 | public static final String CRITERIA_VALUE_SEPERATOR = " "; |
39 | |
40 | private static final String OR_OPERATOR = " OR "; |
41 | private static final String AND_OPERATOR = " AND "; |
42 | |
43 | private Field field; |
44 | private float boost = Float.NaN; |
45 | private boolean negating = false; |
46 | |
47 | private List<Criteria> criteriaChain = new ArrayList<Criteria>(1); |
48 | |
49 | private Set<CriteriaEntry> criteria = new LinkedHashSet<CriteriaEntry>(); |
50 | |
51 | public Criteria() { |
52 | } |
53 | |
54 | /** |
55 | * Creates a new CriterSimpleFieldia for the Filed with provided name |
56 | * |
57 | * @param fieldname |
58 | */ |
59 | public Criteria(String fieldname) { |
60 | this(new SimpleField(fieldname)); |
61 | } |
62 | |
63 | /** |
64 | * Creates a new Criteria for the given field |
65 | * |
66 | * @param field |
67 | */ |
68 | public Criteria(Field field) { |
69 | Assert.notNull(field, "Field for criteria must not be null"); |
70 | Assert.hasText(field.getName(), "Field.name for criteria must not be null/empty"); |
71 | |
72 | this.criteriaChain.add(this); |
73 | this.field = field; |
74 | } |
75 | |
76 | protected Criteria(List<Criteria> criteriaChain, String fieldname) { |
77 | this(criteriaChain, new SimpleField(fieldname)); |
78 | } |
79 | |
80 | protected Criteria(List<Criteria> criteriaChain, Field field) { |
81 | Assert.notNull(criteriaChain, "CriteriaChain must not be null"); |
82 | Assert.notNull(field, "Field for criteria must not be null"); |
83 | Assert.hasText(field.getName(), "Field.name for criteria must not be null/empty"); |
84 | |
85 | this.criteriaChain.addAll(criteriaChain); |
86 | this.criteriaChain.add(this); |
87 | this.field = field; |
88 | } |
89 | |
90 | /** |
91 | * Static factory method to create a new Criteria for field with given name |
92 | * |
93 | * @param field |
94 | * @return |
95 | */ |
96 | public static Criteria where(String field) { |
97 | return where(new SimpleField(field)); |
98 | } |
99 | |
100 | /** |
101 | * Static factory method to create a new Criteria for provided field |
102 | * |
103 | * @param field |
104 | * @return |
105 | */ |
106 | public static Criteria where(Field field) { |
107 | return new Criteria(field); |
108 | } |
109 | |
110 | /** |
111 | * Chain using {@code AND} |
112 | * |
113 | * @param field |
114 | * @return |
115 | */ |
116 | public Criteria and(Field field) { |
117 | return new Criteria(this.criteriaChain, field); |
118 | } |
119 | |
120 | /** |
121 | * Chain using {@code AND} |
122 | * |
123 | * @param fieldName |
124 | * @return |
125 | */ |
126 | public Criteria and(String fieldName) { |
127 | return new Criteria(this.criteriaChain, fieldName); |
128 | } |
129 | |
130 | /** |
131 | * Chain using {@code AND} |
132 | * |
133 | * @param criteria |
134 | * @return |
135 | */ |
136 | public Criteria and(Criteria criteria) { |
137 | this.criteriaChain.add(criteria); |
138 | return this; |
139 | } |
140 | |
141 | /** |
142 | * Chain using {@code AND} |
143 | * |
144 | * @param criterias |
145 | * @return |
146 | */ |
147 | public Criteria and(Criteria... criterias) { |
148 | this.criteriaChain.addAll(Arrays.asList(criterias)); |
149 | return this; |
150 | } |
151 | |
152 | /** |
153 | * Chain using {@code OR} |
154 | * |
155 | * @param field |
156 | * @return |
157 | */ |
158 | public Criteria or(Field field) { |
159 | return new OrCriteria(this.criteriaChain, field); |
160 | } |
161 | |
162 | /** |
163 | * Chain using {@code OR} |
164 | * |
165 | * @param criteria |
166 | * @return |
167 | */ |
168 | public Criteria or(Criteria criteria) { |
169 | Assert.notNull(criteria, "Cannot chain 'null' criteria."); |
170 | |
171 | Criteria orConnectedCritiera = new OrCriteria(this.criteriaChain, criteria.getField()); |
172 | orConnectedCritiera.criteria.addAll(criteria.criteria); |
173 | return orConnectedCritiera; |
174 | } |
175 | |
176 | /** |
177 | * Chain using {@code OR} |
178 | * |
179 | * @param fieldName |
180 | * @return |
181 | */ |
182 | public Criteria or(String fieldName) { |
183 | return or(new SimpleField(fieldName)); |
184 | } |
185 | |
186 | /** |
187 | * Crates new CriteriaEntry without any wildcards |
188 | * |
189 | * @param o |
190 | * @return |
191 | */ |
192 | public Criteria is(Object o) { |
193 | criteria.add(new CriteriaEntry(OperationKey.EQUALS, o)); |
194 | return this; |
195 | } |
196 | |
197 | /** |
198 | * Crates new CriteriaEntry with leading and trailing wildcards <br/> |
199 | * <strong>NOTE: </strong> mind your schema as leading wildcards may not be supported and/or execution might be slow. |
200 | * |
201 | * @param s |
202 | * @return |
203 | */ |
204 | public Criteria contains(String s) { |
205 | assertNoBlankInWildcardedQuery(s, true, true); |
206 | criteria.add(new CriteriaEntry(OperationKey.CONTAINS, s)); |
207 | return this; |
208 | } |
209 | |
210 | /** |
211 | * Crates new CriteriaEntry with trailing wildcard |
212 | * |
213 | * @param s |
214 | * @return |
215 | */ |
216 | public Criteria startsWith(String s) { |
217 | assertNoBlankInWildcardedQuery(s, true, false); |
218 | criteria.add(new CriteriaEntry(OperationKey.STARTS_WITH, s)); |
219 | return this; |
220 | } |
221 | |
222 | /** |
223 | * Crates new CriteriaEntry with leading wildcard <br /> |
224 | * <strong>NOTE: </strong> mind your schema and execution times as leading wildcards may not be supported. |
225 | * |
226 | * @param s |
227 | * @return |
228 | */ |
229 | public Criteria endsWith(String s) { |
230 | assertNoBlankInWildcardedQuery(s, false, true); |
231 | criteria.add(new CriteriaEntry(OperationKey.ENDS_WITH, s)); |
232 | return this; |
233 | } |
234 | |
235 | /** |
236 | * Crates new CriteriaEntry with trailing - |
237 | * |
238 | * @return |
239 | */ |
240 | public Criteria not() { |
241 | this.negating = true; |
242 | return this; |
243 | } |
244 | |
245 | /** |
246 | * Crates new CriteriaEntry with trailing ~ |
247 | * |
248 | * @param s |
249 | * @return |
250 | */ |
251 | public Criteria fuzzy(String s) { |
252 | criteria.add(new CriteriaEntry(OperationKey.FUZZY, s)); |
253 | return this; |
254 | } |
255 | |
256 | |
257 | /** |
258 | * Crates new CriteriaEntry allowing native elasticsearch expressions |
259 | * |
260 | * @param s |
261 | * @return |
262 | */ |
263 | public Criteria expression(String s) { |
264 | criteria.add(new CriteriaEntry(OperationKey.EXPRESSION, s)); |
265 | return this; |
266 | } |
267 | |
268 | /** |
269 | * Boost positive hit with given factor. eg. ^2.3 |
270 | * |
271 | * @param boost |
272 | * @return |
273 | */ |
274 | public Criteria boost(float boost) { |
275 | if (boost < 0) { |
276 | throw new InvalidDataAccessApiUsageException("Boost must not be negative."); |
277 | } |
278 | this.boost = boost; |
279 | return this; |
280 | } |
281 | |
282 | /** |
283 | * Crates new CriteriaEntry for {@code RANGE [lowerBound TO upperBound]} |
284 | * |
285 | * @param lowerBound |
286 | * @param upperBound |
287 | * @return |
288 | */ |
289 | public Criteria between(Object lowerBound, Object upperBound) { |
290 | if (lowerBound == null && upperBound == null) { |
291 | throw new InvalidDataAccessApiUsageException("Range [* TO *] is not allowed"); |
292 | } |
293 | |
294 | criteria.add(new CriteriaEntry(OperationKey.BETWEEN, new Object[] { lowerBound, upperBound })); |
295 | return this; |
296 | } |
297 | |
298 | /** |
299 | * Crates new CriteriaEntry for {@code RANGE [* TO upperBound]} |
300 | * |
301 | * @param upperBound |
302 | * @return |
303 | */ |
304 | public Criteria lessThanEqual(Object upperBound) { |
305 | between(null, upperBound); |
306 | return this; |
307 | } |
308 | |
309 | /** |
310 | * Crates new CriteriaEntry for {@code RANGE [lowerBound TO *]} |
311 | * |
312 | * @param lowerBound |
313 | * @return |
314 | */ |
315 | public Criteria greaterThanEqual(Object lowerBound) { |
316 | between(lowerBound, null); |
317 | return this; |
318 | } |
319 | |
320 | /** |
321 | * Crates new CriteriaEntry for multiple values {@code (arg0 arg1 arg2 ...)} |
322 | * |
323 | * @param values |
324 | * @return |
325 | */ |
326 | public Criteria in(Object... values) { |
327 | if (values.length == 0 || (values.length > 1 && values[1] instanceof Collection)) { |
328 | throw new InvalidDataAccessApiUsageException("At least one element " |
329 | + (values.length > 0 ? ("of argument of type " + values[1].getClass().getName()) : "") |
330 | + " has to be present."); |
331 | } |
332 | return in(Arrays.asList(values)); |
333 | } |
334 | |
335 | /** |
336 | * Crates new CriteriaEntry for multiple values {@code (arg0 arg1 arg2 ...)} |
337 | * |
338 | * @param values the collection containing the values to match against |
339 | * @return |
340 | */ |
341 | public Criteria in(Iterable<?> values) { |
342 | Assert.notNull(values, "Collection of 'in' values must not be null"); |
343 | criteria.add(new CriteriaEntry(OperationKey.IN, values)); |
344 | return this; |
345 | } |
346 | |
347 | |
348 | private void assertNoBlankInWildcardedQuery(String searchString, boolean leadingWildcard, boolean trailingWildcard) { |
349 | if (StringUtils.contains(searchString, CRITERIA_VALUE_SEPERATOR)) { |
350 | throw new InvalidDataAccessApiUsageException("Cannot constructQuery '" + (leadingWildcard ? "*" : "") + "\"" |
351 | + searchString + "\"" + (trailingWildcard ? "*" : "") + "'. Use epxression or mulitple clauses instead."); |
352 | } |
353 | } |
354 | |
355 | /** |
356 | * Field targeted by this Criteria |
357 | * |
358 | * @return |
359 | */ |
360 | public Field getField() { |
361 | return this.field; |
362 | } |
363 | |
364 | public Set<CriteriaEntry> getCriteriaEntries() { |
365 | return Collections.unmodifiableSet(this.criteria); |
366 | } |
367 | |
368 | /** |
369 | * Conjunction to be used with this criteria (AND | OR) |
370 | * |
371 | * @return |
372 | */ |
373 | public String getConjunctionOperator() { |
374 | return AND_OPERATOR; |
375 | } |
376 | |
377 | public List<Criteria> getCriteriaChain() { |
378 | return Collections.unmodifiableList(this.criteriaChain); |
379 | } |
380 | |
381 | public boolean isNegating() { |
382 | return this.negating; |
383 | } |
384 | |
385 | public boolean isAnd(){ |
386 | return AND_OPERATOR == getConjunctionOperator(); |
387 | } |
388 | |
389 | public boolean isOr(){ |
390 | return OR_OPERATOR == getConjunctionOperator(); |
391 | } |
392 | |
393 | public float getBoost() { |
394 | return this.boost; |
395 | } |
396 | |
397 | static class OrCriteria extends Criteria { |
398 | |
399 | public OrCriteria() { |
400 | super(); |
401 | } |
402 | |
403 | public OrCriteria(Field field) { |
404 | super(field); |
405 | } |
406 | |
407 | public OrCriteria(List<Criteria> criteriaChain, Field field) { |
408 | super(criteriaChain, field); |
409 | } |
410 | |
411 | public OrCriteria(List<Criteria> criteriaChain, String fieldname) { |
412 | super(criteriaChain, fieldname); |
413 | } |
414 | |
415 | public OrCriteria(String fieldname) { |
416 | super(fieldname); |
417 | } |
418 | |
419 | @Override |
420 | public String getConjunctionOperator() { |
421 | return OR_OPERATOR; |
422 | } |
423 | |
424 | } |
425 | |
426 | public enum OperationKey { |
427 | EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, EXPRESSION, BETWEEN, FUZZY, IN; |
428 | } |
429 | |
430 | public static class CriteriaEntry { |
431 | |
432 | private OperationKey key; |
433 | private Object value; |
434 | |
435 | CriteriaEntry(OperationKey key, Object value) { |
436 | this.key = key; |
437 | this.value = value; |
438 | } |
439 | |
440 | public OperationKey getKey() { |
441 | return key; |
442 | } |
443 | |
444 | public Object getValue() { |
445 | return value; |
446 | } |
447 | |
448 | } |
449 | |
450 | } |