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