1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21
22
23 package org.opencastproject.elasticsearch.api;
24 import org.opencastproject.util.requests.SortCriterion.Order;
25
26 import java.util.Collection;
27 import java.util.Map;
28
29 /**
30 * Interface for the implementation of search queries.
31 */
32 public interface SearchQuery {
33
34 /**
35 * Return documents of the given types.
36 *
37 * @param types
38 * the resource types to look up
39 * @return the query extended by this criterion
40 */
41 SearchQuery withTypes(String... types);
42
43 /**
44 * Returns the document types or or an empty array if no types were specified.
45 *
46 * @return the type
47 */
48 String[] getTypes();
49
50 /**
51 * Sets the number of results that are returned.
52 *
53 * @param limit
54 * the number of results
55 * @return the search query
56 */
57 SearchQuery withLimit(int limit);
58
59 /**
60 * Returns the number of results that are returned, starting at the offset returned by <code>getOffset()</code>. If no
61 * limit was specified, this method returns <code>-1</code>.
62 *
63 * @return the maximum number of results
64 */
65 int getLimit();
66
67 /**
68 * Sets the starting offset. Search results will be returned starting at that offset and until the limit is reached,
69 * as specified by <code>getLimit()</code>.
70 *
71 * @param offset
72 * the starting offset
73 * @return the search query
74 */
75 SearchQuery withOffset(int offset);
76
77 /**
78 * Returns the starting offset within the search result or <code>0</code> if no offset was specified.
79 *
80 * @return the offset
81 */
82 int getOffset();
83
84 /**
85 * Returns documents that contain the given text.
86 *
87 * @param text
88 * the text to look up
89 * @return the query extended by this criterion
90 */
91 SearchQuery withText(String text);
92
93 /**
94 * Returns documents that contain the given text.
95 *
96 * @param wildcardSearch
97 * <code>True</code> to perform a (much slower) wildcard search
98 * @param text
99 * the text to look up
100 *
101 * @return the query extended by this criterion
102 */
103 SearchQuery withText(boolean wildcardSearch, String text);
104
105 /**
106 * Returns documents that contain the given text.
107 * <p>
108 * Depending on the quantifier, either documents are returned that contain at least one of the terms are only
109 * documents containing all of the terms.
110 *
111 * @param text
112 * the text to look up
113 * @param quantifier
114 * whether all or some of the terms need to be matched
115 * @param fuzzy
116 * <code>true</code> to perform a fuzzy search
117 * @return the query extended by this criterion
118 */
119 SearchQuery withText(boolean fuzzy, SearchTerms.Quantifier quantifier, String... text);
120
121 /**
122 * Returns the search terms or an empty collection if no terms were specified.
123 *
124 * @return the terms
125 */
126 Collection<SearchTerms<String>> getTerms();
127
128 /**
129 * Returns the search text or <code>null</code> if no text was specified.
130 *
131 * @return the text
132 */
133 String getQueryString();
134
135 /**
136 * Returns <code>true</code> if the current search operation should be performed using fuzzy searching.
137 *
138 * @return <code>true</code> if fuzzy search should be used
139 */
140 boolean isFuzzySearch();
141
142 /**
143 * Returns documents that match the search query <i>and</i> the text filter.
144 *
145 * @param filter
146 * the filter text
147 * @return the search query
148 */
149 SearchQuery withFilter(String filter);
150
151 /**
152 * Returns the filter expression.
153 *
154 * @return the filter
155 */
156 String getFilter();
157
158 /**
159 * Returns the fields that should be returned by the query. If all fields should be returned, the method will return
160 * an empty array.
161 *
162 * @return the names of the fields to return
163 */
164 String[] getFields();
165
166 /**
167 * Adds a field that needs to be returned by the query. If no fields are being set, all fields will be returned.
168 *
169 * @param field
170 * the field name
171 * @return the query
172 */
173 SearchQuery withField(String field);
174
175 /**
176 * Adds the fields that need to be returned by the query. If no fields are being set, all fields will be returned.
177 *
178 * @param fields
179 * the field names
180 * @return the query
181 */
182 SearchQuery withFields(String... fields);
183
184 /**
185 * Sort the result set by the field and the given order. The insertion-order is kept.
186 *
187 * @param field
188 * the field name, must not be {@code null}
189 * @param order
190 * the order direction, must not be {@code null}
191 * @return the updated search query
192 */
193 SearchQuery withSortOrder(String field, Order order);
194
195 /**
196 * Returns all the known sort orders. The insertion-order is kept.
197 *
198 * @return a map with all known sort orders
199 */
200 Map<String, Order> getSortOrders();
201
202 /**
203 * Returns the sort order of a field. If no sort order has been set for the given field, {@link Order#None} is
204 * returned.
205 *
206 * @param field
207 * the field name, must not be {@code null}
208 * @return the sort order
209 */
210 Order getSortOrder(String field);
211
212 }