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 | for (Object value : values) { |
344 | if (value instanceof Collection) { |
345 | in((Collection<?>) value); |
346 | } else { |
347 | is(value); |
348 | } |
349 | } |
350 | return this; |
351 | } |
352 | |
353 | |
354 | private void assertNoBlankInWildcardedQuery(String searchString, boolean leadingWildcard, boolean trailingWildcard) { |
355 | if (StringUtils.contains(searchString, CRITERIA_VALUE_SEPERATOR)) { |
356 | throw new InvalidDataAccessApiUsageException("Cannot constructQuery '" + (leadingWildcard ? "*" : "") + "\"" |
357 | + searchString + "\"" + (trailingWildcard ? "*" : "") + "'. Use epxression or mulitple clauses instead."); |
358 | } |
359 | } |
360 | |
361 | /** |
362 | * Field targeted by this Criteria |
363 | * |
364 | * @return |
365 | */ |
366 | public Field getField() { |
367 | return this.field; |
368 | } |
369 | |
370 | public Set<CriteriaEntry> getCriteriaEntries() { |
371 | return Collections.unmodifiableSet(this.criteria); |
372 | } |
373 | |
374 | /** |
375 | * Conjunction to be used with this criteria (AND | OR) |
376 | * |
377 | * @return |
378 | */ |
379 | public String getConjunctionOperator() { |
380 | return AND_OPERATOR; |
381 | } |
382 | |
383 | public List<Criteria> getCriteriaChain() { |
384 | return Collections.unmodifiableList(this.criteriaChain); |
385 | } |
386 | |
387 | public boolean isNegating() { |
388 | return this.negating; |
389 | } |
390 | |
391 | public boolean isAnd(){ |
392 | return AND_OPERATOR == getConjunctionOperator(); |
393 | } |
394 | |
395 | public boolean isOr(){ |
396 | return OR_OPERATOR == getConjunctionOperator(); |
397 | } |
398 | |
399 | public float getBoost() { |
400 | return this.boost; |
401 | } |
402 | |
403 | static class OrCriteria extends Criteria { |
404 | |
405 | public OrCriteria() { |
406 | super(); |
407 | } |
408 | |
409 | public OrCriteria(Field field) { |
410 | super(field); |
411 | } |
412 | |
413 | public OrCriteria(List<Criteria> criteriaChain, Field field) { |
414 | super(criteriaChain, field); |
415 | } |
416 | |
417 | public OrCriteria(List<Criteria> criteriaChain, String fieldname) { |
418 | super(criteriaChain, fieldname); |
419 | } |
420 | |
421 | public OrCriteria(String fieldname) { |
422 | super(fieldname); |
423 | } |
424 | |
425 | @Override |
426 | public String getConjunctionOperator() { |
427 | return OR_OPERATOR; |
428 | } |
429 | |
430 | } |
431 | |
432 | public enum OperationKey { |
433 | EQUALS, CONTAINS, STARTS_WITH, ENDS_WITH, EXPRESSION, BETWEEN, FUZZY; |
434 | } |
435 | |
436 | public static class CriteriaEntry { |
437 | |
438 | private OperationKey key; |
439 | private Object value; |
440 | |
441 | CriteriaEntry(OperationKey key, Object value) { |
442 | this.key = key; |
443 | this.value = value; |
444 | } |
445 | |
446 | public OperationKey getKey() { |
447 | return key; |
448 | } |
449 | |
450 | public Object getValue() { |
451 | return value; |
452 | } |
453 | |
454 | } |
455 | |
456 | } |