001/*
002 * Copyright 2020 Global Biodiversity Information Facility (GBIF)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.gbif.api.service.occurrence;
017
018import org.gbif.api.model.common.search.FacetedSearchRequest;
019import org.gbif.api.model.common.search.SearchResponse;
020import org.gbif.api.model.occurrence.Occurrence;
021import org.gbif.api.model.occurrence.search.OccurrencePredicateSearchRequest;
022import org.gbif.api.model.occurrence.search.OccurrenceSearchParameter;
023import org.gbif.api.model.occurrence.search.OccurrenceSearchRequest;
024import org.gbif.api.service.common.SearchService;
025
026import java.util.List;
027
028import javax.annotation.Nullable;
029import javax.validation.constraints.Min;
030
031/**
032 * Interface that provides search operations over Occurrences.
033 * As the occurrence Solr index doesn't store values we use the full Occurrence class for search responses
034 * as we need to do lookups by key anyways.
035 */
036public interface OccurrenceSearchService
037  extends SearchService<Occurrence, OccurrenceSearchParameter, OccurrenceSearchRequest> {
038
039  /** Occurrence search implementation that uses a predicate instead of request parameters.*/
040  SearchResponse<Occurrence, OccurrenceSearchParameter> search(OccurrencePredicateSearchRequest request);
041
042  /**
043   * Searches catalog numbers which start with the input prefix.
044   * If the limit is set to a number less than 0, then no maximum limit is enforced.
045   * If limit contains a null value, a default value is set by the service implementation.
046   *
047   * @param prefix search pattern
048   * @param limit maximum number of results to return
049   * @return of catalog numbers
050   */
051  List<String> suggestCatalogNumbers(@Min(1) String prefix, @Nullable Integer limit);
052
053  /**
054   * Searches collection codes which start with the input prefix.
055   * If the limit is set to a number less than 0, then no maximum limit is enforced.
056   * If limit contains a null value, a default value is set by the service implementation.
057   *
058   * @param prefix search pattern
059   * @param limit maximum number of results to return
060   * @return of collection names
061   */
062  List<String> suggestCollectionCodes(@Min(1) String prefix, @Nullable Integer limit);
063
064  /**
065   * Searches collector names (dwc:recordedBy) which start with the input prefix.
066   * If the limit is set to a number less than 0, then no maximum limit is enforced.
067   * If limit contains a null value, a default value is set by the service implementation.
068   *
069   * @param prefix search pattern
070   * @param limit maximum number of results to return
071   * @return of collector names
072   */
073  List<String> suggestRecordedBy(@Min(1) String prefix, @Nullable Integer limit);
074
075  /**
076   * Searches collector names (dwc:identifiedBy) which start with the input prefix.
077   * If the limit is set to a number less than 0, then no maximum limit is enforced.
078   * If limit contains a null value, a default value is set by the service implementation.
079   *
080   * @param prefix search pattern
081   * @param limit maximum number of results to return
082   * @return of collector names
083   */
084  List<String> suggestIdentifiedBy(@Min(1) String prefix, @Nullable Integer limit);
085
086  /**
087   * Searches record numbers which start with the input prefix.
088   * If the limit is set to a number less than 0, then no maximum limit is enforced.
089   * If limit contains a null value, a default value is set by the service implementation.
090   *
091   * @param prefix search pattern
092   * @param limit maximum number of results to return
093   * @return of collector names
094   */
095  List<String> suggestRecordNumbers(@Min(1) String prefix, @Nullable Integer limit);
096
097  /**
098   * Searches institution codes which start with the input prefix.
099   * If the limit is set to a number less than 0, then no maximum limit is enforced.
100   * If limit contains a null value, a default value is set by the service implementation.
101   *
102   * @param prefix search pattern
103   * @param limit maximum number of results to return
104   * @return of institution codes
105   */
106  List<String> suggestInstitutionCodes(@Min(1) String prefix, @Nullable Integer limit);
107
108  /**
109   * Searches DwC occurrenceIds which start with the input prefix.
110   * If the limit is set to a number less than 0, then no maximum limit is enforced.
111   * If limit contains a null value, a default value is set by the service implementation.
112   *
113   * @param prefix search pattern
114   * @param limit maximum number of results to return
115   * @return of occurrenceIds
116   */
117  List<String> suggestOccurrenceIds(@Min(1) String prefix, @Nullable Integer limit);
118
119  /**
120   * Searches DwC organismsIds which start with the input prefix.
121   * If the limit is set to a number less than 0, then no maximum limit is enforced.
122   * If limit contains a null value, a default value is set by the service implementation.
123   *
124   * @param prefix search pattern
125   * @param limit maximum number of results to return
126   * @return of organismIds
127   */
128  List<String> suggestOrganismIds(@Min(1) String prefix, @Nullable Integer limit);
129
130  /**
131   * Searches DwC localities which start with the input prefix.
132   * If the limit is set to a number less than 0, then no maximum limit is enforced.
133   * If limit contains a null value, a default value is set by the service implementation.
134   *
135   * @param prefix search pattern
136   * @param limit maximum number of results to return
137   * @return of localities
138   */
139  List<String> suggestLocalities(@Min(1) String prefix, @Nullable Integer limit);
140
141  /**
142   * Searches DwC water bodies which start with the input prefix.
143   * If the limit is set to a number less than 0, then no maximum limit is enforced.
144   * If limit contains a null value, a default value is set by the service implementation.
145   *
146   * @param prefix search pattern
147   * @param limit maximum number of results to return
148   * @return of water bodies
149   */
150  List<String> suggestWaterBodies(@Min(1) String prefix, @Nullable Integer limit);
151
152  /**
153   * Searches DwC state/provinces which start with the input prefix.
154   * If the limit is set to a number less than 0, then no maximum limit is enforced.
155   * If limit contains a null value, a default value is set by the service implementation.
156   *
157   * @param prefix search pattern
158   * @param limit maximum number of results to return
159   * @return of state provinces
160   */
161  List<String> suggestStateProvinces(@Min(1) String prefix, @Nullable Integer limit);
162
163
164  /**
165   * Searches DwC sampling protocols which start with the input prefix.
166   * If the limit is set to a number less than 0, then no maximum limit is enforced.
167   * If limit contains a null value, a default value is set by the service implementation.
168   *
169   * @param prefix search pattern
170   * @param limit maximum number of results to return
171   * @return of state provinces
172   */
173  List<String> suggestSamplingProtocol(@Min(1) String prefix, @Nullable Integer limit);
174
175  /**
176   * Searches DwC eventIds which start with the input prefix.
177   * If the limit is set to a number less than 0, then no maximum limit is enforced.
178   * If limit contains a null value, a default value is set by the service implementation.
179   *
180   * @param prefix search pattern
181   * @param limit maximum number of results to return
182   * @return of state provinces
183   */
184  List<String> suggestEventId(@Min(1) String prefix, @Nullable Integer limit);
185
186
187  /**
188   * Searches DwC parentEventIds which start with the input prefix.
189   * If the limit is set to a number less than 0, then no maximum limit is enforced.
190   * If limit contains a null value, a default value is set by the service implementation.
191   *
192   * @param prefix search pattern
193   * @param limit maximum number of results to return
194   * @return of state provinces
195   */
196  List<String> suggestParentEventId(@Min(1) String prefix, @Nullable Integer limit);
197
198  /**
199   * Searches other catalog numbers which start with the input prefix.
200   * If the limit is set to a number less than 0, then no maximum limit is enforced.
201   * If limit contains a null value, a default value is set by the service implementation.
202   *
203   * @param prefix search pattern
204   * @param limit maximum number of results to return
205   * @return of other catalog numbers
206   */
207  List<String> suggestOtherCatalogNumbers(@Min(1) String prefix, @Nullable Integer limit);
208
209  /**
210   * Searches dataset names which start with the input prefix.
211   * If the limit is set to a number less than 0, then no maximum limit is enforced.
212   * If limit contains a null value, a default value is set by the service implementation.
213   *
214   * @param prefix search pattern
215   * @param limit maximum number of results to return
216   * @return of dataset names
217   */
218  List<String> suggestDatasetName(@Min(1) String prefix, @Nullable Integer limit);
219}