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.model.predicate.Predicate;
025import org.gbif.api.service.common.SearchService;
026
027import java.util.List;
028
029import javax.annotation.Nullable;
030import javax.validation.constraints.Min;
031
032/**
033 * Interface that provides search operations over Occurrences.
034 * As the occurrence Solr index doesn't store values we use the full Occurrence class for search responses
035 * as we need to do lookups by key anyways.
036 */
037public interface OccurrenceSearchService
038  extends SearchService<Occurrence, OccurrenceSearchParameter, OccurrenceSearchRequest> {
039
040  /** Occurrence search implementation that uses a predicate instead of request parameters.*/
041  SearchResponse<Occurrence, OccurrenceSearchParameter> search(OccurrencePredicateSearchRequest request);
042
043  /** Get the record count from a predicate search. */
044  long countRecords(Predicate predicate);
045
046  /**
047   * Searches catalog numbers which start with the input prefix.
048   * If the limit is set to a number less than 0, then no maximum limit is enforced.
049   * If limit contains a null value, a default value is set by the service implementation.
050   *
051   * @param prefix search pattern
052   * @param limit maximum number of results to return
053   * @return of catalog numbers
054   */
055  List<String> suggestCatalogNumbers(@Min(1) String prefix, @Nullable Integer limit);
056
057  /**
058   * Searches collection codes which start with the input prefix.
059   * If the limit is set to a number less than 0, then no maximum limit is enforced.
060   * If limit contains a null value, a default value is set by the service implementation.
061   *
062   * @param prefix search pattern
063   * @param limit maximum number of results to return
064   * @return of collection names
065   */
066  List<String> suggestCollectionCodes(@Min(1) String prefix, @Nullable Integer limit);
067
068  /**
069   * Searches collector names (dwc:recordedBy) which start with the input prefix.
070   * If the limit is set to a number less than 0, then no maximum limit is enforced.
071   * If limit contains a null value, a default value is set by the service implementation.
072   *
073   * @param prefix search pattern
074   * @param limit maximum number of results to return
075   * @return of collector names
076   */
077  List<String> suggestRecordedBy(@Min(1) String prefix, @Nullable Integer limit);
078
079  /**
080   * Searches collector names (dwc:identifiedBy) which start with the input prefix.
081   * If the limit is set to a number less than 0, then no maximum limit is enforced.
082   * If limit contains a null value, a default value is set by the service implementation.
083   *
084   * @param prefix search pattern
085   * @param limit maximum number of results to return
086   * @return of collector names
087   */
088  List<String> suggestIdentifiedBy(@Min(1) String prefix, @Nullable Integer limit);
089
090  /**
091   * Searches record numbers which start with the input prefix.
092   * If the limit is set to a number less than 0, then no maximum limit is enforced.
093   * If limit contains a null value, a default value is set by the service implementation.
094   *
095   * @param prefix search pattern
096   * @param limit maximum number of results to return
097   * @return of collector names
098   */
099  List<String> suggestRecordNumbers(@Min(1) String prefix, @Nullable Integer limit);
100
101  /**
102   * Searches institution codes which start with the input prefix.
103   * If the limit is set to a number less than 0, then no maximum limit is enforced.
104   * If limit contains a null value, a default value is set by the service implementation.
105   *
106   * @param prefix search pattern
107   * @param limit maximum number of results to return
108   * @return of institution codes
109   */
110  List<String> suggestInstitutionCodes(@Min(1) String prefix, @Nullable Integer limit);
111
112  /**
113   * Searches DwC occurrenceIds which start with the input prefix.
114   * If the limit is set to a number less than 0, then no maximum limit is enforced.
115   * If limit contains a null value, a default value is set by the service implementation.
116   *
117   * @param prefix search pattern
118   * @param limit maximum number of results to return
119   * @return of occurrenceIds
120   */
121  List<String> suggestOccurrenceIds(@Min(1) String prefix, @Nullable Integer limit);
122
123  /**
124   * Searches DwC organismsIds which start with the input prefix.
125   * If the limit is set to a number less than 0, then no maximum limit is enforced.
126   * If limit contains a null value, a default value is set by the service implementation.
127   *
128   * @param prefix search pattern
129   * @param limit maximum number of results to return
130   * @return of organismIds
131   */
132  List<String> suggestOrganismIds(@Min(1) String prefix, @Nullable Integer limit);
133
134  /**
135   * Searches DwC localities which start with the input prefix.
136   * If the limit is set to a number less than 0, then no maximum limit is enforced.
137   * If limit contains a null value, a default value is set by the service implementation.
138   *
139   * @param prefix search pattern
140   * @param limit maximum number of results to return
141   * @return of localities
142   */
143  List<String> suggestLocalities(@Min(1) String prefix, @Nullable Integer limit);
144
145  /**
146   * Searches DwC water bodies which start with the input prefix.
147   * If the limit is set to a number less than 0, then no maximum limit is enforced.
148   * If limit contains a null value, a default value is set by the service implementation.
149   *
150   * @param prefix search pattern
151   * @param limit maximum number of results to return
152   * @return of water bodies
153   */
154  List<String> suggestWaterBodies(@Min(1) String prefix, @Nullable Integer limit);
155
156  /**
157   * Searches DwC state/provinces which start with the input prefix.
158   * If the limit is set to a number less than 0, then no maximum limit is enforced.
159   * If limit contains a null value, a default value is set by the service implementation.
160   *
161   * @param prefix search pattern
162   * @param limit maximum number of results to return
163   * @return of state provinces
164   */
165  List<String> suggestStateProvinces(@Min(1) String prefix, @Nullable Integer limit);
166
167
168  /**
169   * Searches DwC sampling protocols which start with the input prefix.
170   * If the limit is set to a number less than 0, then no maximum limit is enforced.
171   * If limit contains a null value, a default value is set by the service implementation.
172   *
173   * @param prefix search pattern
174   * @param limit maximum number of results to return
175   * @return of state provinces
176   */
177  List<String> suggestSamplingProtocol(@Min(1) String prefix, @Nullable Integer limit);
178
179  /**
180   * Searches DwC eventIds which start with the input prefix.
181   * If the limit is set to a number less than 0, then no maximum limit is enforced.
182   * If limit contains a null value, a default value is set by the service implementation.
183   *
184   * @param prefix search pattern
185   * @param limit maximum number of results to return
186   * @return of state provinces
187   */
188  List<String> suggestEventId(@Min(1) String prefix, @Nullable Integer limit);
189
190
191  /**
192   * Searches DwC parentEventIds which start with the input prefix.
193   * If the limit is set to a number less than 0, then no maximum limit is enforced.
194   * If limit contains a null value, a default value is set by the service implementation.
195   *
196   * @param prefix search pattern
197   * @param limit maximum number of results to return
198   * @return of state provinces
199   */
200  List<String> suggestParentEventId(@Min(1) String prefix, @Nullable Integer limit);
201
202  /**
203   * Searches other catalog numbers which start with the input prefix.
204   * If the limit is set to a number less than 0, then no maximum limit is enforced.
205   * If limit contains a null value, a default value is set by the service implementation.
206   *
207   * @param prefix search pattern
208   * @param limit maximum number of results to return
209   * @return of other catalog numbers
210   */
211  List<String> suggestOtherCatalogNumbers(@Min(1) String prefix, @Nullable Integer limit);
212
213  /**
214   * Searches dataset names which start with the input prefix.
215   * If the limit is set to a number less than 0, then no maximum limit is enforced.
216   * If limit contains a null value, a default value is set by the service implementation.
217   *
218   * @param prefix search pattern
219   * @param limit maximum number of results to return
220   * @return of dataset names
221   */
222  List<String> suggestDatasetName(@Min(1) String prefix, @Nullable Integer limit);
223}