001/*
002 * Copyright 2014 Global Biodiversity Information Facility (GBIF)
003 * Licensed under the Apache License, Version 2.0 (the "License");
004 * you may not use this file except in compliance with the License.
005 * You may obtain a copy of the License at
006 * http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010 * See the License for the specific language governing permissions and
011 * limitations under the License.
012 */
013package org.gbif.api.service.occurrence;
014
015import org.gbif.api.model.occurrence.Occurrence;
016import org.gbif.api.model.occurrence.search.OccurrenceSearchParameter;
017import org.gbif.api.model.occurrence.search.OccurrenceSearchRequest;
018import org.gbif.api.service.common.SearchService;
019
020import java.util.List;
021
022import javax.annotation.Nullable;
023import javax.validation.constraints.Min;
024
025/**
026 * Interface that provides search operations over Occurrences.
027 * As the occurrence Solr index doesn't store values we use the full Occurrence class for search responses
028 * as we need to do lookups by key anyways.
029 */
030public interface OccurrenceSearchService
031  extends SearchService<Occurrence, OccurrenceSearchParameter, OccurrenceSearchRequest> {
032
033  /**
034   * Searches catalog numbers which start with the input prefix.
035   * If the limit is set to a number less than 0, then no maximum limit is enforced.
036   * If limit contains a null value, a default value is set by the service implementation.
037   *
038   * @param prefix search pattern
039   * @param limit maximum number of results to return
040   * @return of catalog numbers
041   */
042  List<String> suggestCatalogNumbers(@Min(1) String prefix, @Nullable Integer limit);
043
044  /**
045   * Searches collection codes which start with the input prefix.
046   * If the limit is set to a number less than 0, then no maximum limit is enforced.
047   * If limit contains a null value, a default value is set by the service implementation.
048   *
049   * @param prefix search pattern
050   * @param limit maximum number of results to return
051   * @return of collection names
052   */
053  List<String> suggestCollectionCodes(@Min(1) String prefix, @Nullable Integer limit);
054
055
056  /**
057   * Searches collector names (dwc:recordedBy) which start with the input prefix.
058   * If the limit is set to a number less than 0, then no maximum limit is enforced.
059   * If limit contains a null value, a default value is set by the service implementation.
060   *
061   * @param prefix search pattern
062   * @param limit maximum number of results to return
063   * @return of collector names
064   */
065  List<String> suggestRecordedBy(@Min(1) String prefix, @Nullable Integer limit);
066
067  /**
068   * Searches record numbers which start with the input prefix.
069   * If the limit is set to a number less than 0, then no maximum limit is enforced.
070   * If limit contains a null value, a default value is set by the service implementation.
071   *
072   * @param prefix search pattern
073   * @param limit maximum number of results to return
074   * @return of collector names
075   */
076  List<String> suggestRecordNumbers(@Min(1) String prefix, @Nullable Integer limit);
077
078
079  /**
080   * Searches institution codes 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 institution codes
087   */
088  List<String> suggestInstitutionCodes(@Min(1) String prefix, @Nullable Integer limit);
089
090  /**
091   * Searches DwC occurrenceIds 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 occurrenceIds
098   */
099  List<String> suggestOccurrenceIds(@Min(1) String prefix, @Nullable Integer limit);
100
101
102  /**
103   * Searches DwC organismsIds which start with the input prefix.
104   * If the limit is set to a number less than 0, then no maximum limit is enforced.
105   * If limit contains a null value, a default value is set by the service implementation.
106   *
107   * @param prefix search pattern
108   * @param limit maximum number of results to return
109   * @return of organismIds
110   */
111  List<String> suggestOrganismIds(@Min(1) String prefix, @Nullable Integer limit);
112
113
114  /**
115   * Searches DwC localities which start with the input prefix.
116   * If the limit is set to a number less than 0, then no maximum limit is enforced.
117   * If limit contains a null value, a default value is set by the service implementation.
118   *
119   * @param prefix search pattern
120   * @param limit maximum number of results to return
121   * @return of localities
122   */
123  List<String> suggestLocalities(@Min(1) String prefix, @Nullable Integer limit);
124
125  /**
126   * Searches DwC water bodies which start with the input prefix.
127   * If the limit is set to a number less than 0, then no maximum limit is enforced.
128   * If limit contains a null value, a default value is set by the service implementation.
129   *
130   * @param prefix search pattern
131   * @param limit maximum number of results to return
132   * @return of water bodies
133   */
134  List<String> suggestWaterBodies(@Min(1) String prefix, @Nullable Integer limit);
135
136  /**
137   * Searches DwC state/provinces which start with the input prefix.
138   * If the limit is set to a number less than 0, then no maximum limit is enforced.
139   * If limit contains a null value, a default value is set by the service implementation.
140   *
141   * @param prefix search pattern
142   * @param limit maximum number of results to return
143   * @return of state provinces
144   */
145  List<String> suggestStateProvinces(@Min(1) String prefix, @Nullable Integer limit);
146}