001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.gbif.api.model.common.search;
015
016
017import io.swagger.v3.oas.annotations.Hidden;
018import java.util.Date;
019import java.util.Map;
020import java.util.Set;
021import org.gbif.api.annotation.Experimental;
022import org.gbif.api.model.common.paging.Pageable;
023import org.gbif.api.util.IsoDateInterval;
024
025/**
026 * Generic request class for search operations. This class contains a list of parameters, a list of
027 * desired facets and paging options (page size and offset).
028 */
029public interface SearchRequest<P extends SearchParameter> extends Pageable {
030
031  /**
032   * This flag enables the use of case-sensitive matches and aggregations on certain search
033   * parameters.
034   *
035   * <p>Fields that support this feature are: occurrenceId, recordedBy, samplingProtocol,
036   * catalogNumber, collectionCode, institutionCode, eventId, parentEventId, waterBody,
037   * stateProvince, recordNumber, identifiedBy, organismId and locality.
038   *
039   * <p>This is an experimental feature, and its implementation may change or be removed at any
040   * time.
041   *
042   * <p>Be aware that this is not a per-field flag, all possible fields will match case sensitively.
043   */
044  @Experimental
045  Boolean isMatchCase();
046
047  interface QueryField {}
048
049  /**
050   * @return true if highlighted search matches are requested
051   */
052  boolean isHighlight();
053
054  /**
055   * @param highlight the highlight to set
056   */
057  void setHighlight(boolean highlight);
058
059  /**
060   * @return true if spellCheck search is requested
061   */
062  boolean isSpellCheck();
063
064  /**
065   * @param spellCheck the highlight to set
066   */
067  void setSpellCheck(boolean spellCheck);
068
069  /**
070   * @return max number of spell check suggestions requested
071   */
072  int getSpellCheckCount();
073
074  /**
075   * @param spellCheckCount number of spell check suggestions
076   */
077  void setSpellCheckCount(int spellCheckCount);
078
079  /** Defines whether to match against fields with scientific or vernacular names or both. */
080  @Hidden
081  Set<QueryField> getQFields();
082
083  @Hidden
084  void setQFields(Set<QueryField> qFields);
085
086  /** Defines the fields to be highlighted if highlighting is activated. */
087  Set<QueryField> getHighlightFields();
088
089  void setHighlightFields(Set<QueryField> highlightFields);
090
091  /**
092   * List of input parameters of the search operation. The parameters are handled as the parameter
093   * name and the string representation of its value.
094   *
095   * @return the list of parameters
096   */
097  Map<P, Set<String>> getParameters();
098
099  /** Sets the list of parameters. */
100  void setParameters(Map<P, Set<String>> parameters);
101
102  /**
103   * Query parameter.
104   *
105   * @return the q
106   */
107  String getQ();
108
109  /**
110   * @param q the q to set
111   */
112  void setQ(String q);
113
114  /**
115   * Adds the specified parameter.
116   *
117   * @param parameter parameter to add values for
118   * @param values list of values of the parameter to add
119   */
120  void addParameter(P parameter, Iterable<String> values);
121
122  /**
123   * Adds the specified parameter.
124   *
125   * @param parameter parameter to add values for
126   * @param values list of values of the parameter to add
127   */
128  void addParameter(P parameter, String... values);
129
130  /**
131   * Adds the specified parameter.
132   *
133   * @param parameter parameter to add values for
134   * @param value value of the parameter to add
135   */
136  void addParameter(P parameter, String value);
137
138  /**
139   * Adds the specified long parameter.
140   *
141   * @param parameter parameter to add values for
142   * @param value value of the parameter to add
143   */
144  void addParameter(P parameter, long value);
145
146  /**
147   * Adds the specified int parameter.
148   *
149   * @param parameter parameter to add values for
150   * @param value value of the parameter to add
151   */
152  void addParameter(P parameter, int value);
153
154  /**
155   * Adds the specified double parameter.
156   *
157   * @param parameter parameter to add values for
158   * @param value value of the parameter to add
159   */
160  void addParameter(P parameter, double value);
161
162  /**
163   * Adds the specified boolean parameter.
164   *
165   * @param parameter parameter to add values for
166   * @param value value of the parameter to add
167   */
168  void addParameter(P parameter, boolean value);
169
170  /**
171   * Adds the specified parameter.
172   *
173   * @param parameter parameter to add values for
174   * @param value enum value of the parameter to add
175   */
176  void addParameter(P parameter, Enum<?> value);
177
178  /**
179   * Adds the specified date parameter as an ISO date.
180   *
181   * @param parameter parameter to add date for
182   * @param value date value of the parameter to add
183   */
184  void addParameter(P parameter, Date value);
185
186  /**
187   * Adds the specified date parameter as an ISO date interval.
188   *
189   * @param parameter parameter to add date interval for
190   * @param value date value of the parameter to add
191   */
192  void addParameter(P parameter, IsoDateInterval value);
193
194  /**
195   * Utility method to copy paging values.
196   */
197  void copyPagingValues(Pageable pageable);
198}