001/*
002 * Copyright 2014 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.checklistbank;
017
018import org.gbif.api.model.checklistbank.NameUsage;
019import org.gbif.api.model.checklistbank.NameUsageMetrics;
020import org.gbif.api.model.checklistbank.ParsedName;
021import org.gbif.api.model.checklistbank.VerbatimNameUsage;
022import org.gbif.api.model.common.paging.Pageable;
023import org.gbif.api.model.common.paging.PagingResponse;
024
025import java.util.List;
026import java.util.Locale;
027import java.util.UUID;
028import javax.annotation.Nullable;
029
030/**
031 * This is the public interface providing methods for retrieving name usages in general, no matter if nub or
032 * checklist usage.
033 *
034 * @see NameUsage
035 */
036public interface NameUsageService {
037
038  /**
039   * Attempt to find a name usage matching the passed key.
040   * The given Locale determines the name used for the NameUsage.vernacularName property
041   * with null ignoring any vernacular name.
042   *
043   * @param taxonKey that identifies a name usage
044   * @param locale   the locale's language determines the vernacular name to use for a usage.
045   *                 Use null to not load any common name
046   *
047   * @return a matching name usage, or null if no name usage found
048   */
049  @Nullable
050  NameUsage get(int taxonKey, @Nullable Locale locale);
051
052  /**
053   * Gets the parsed name representation of a given name usage.
054   *
055   * @param taxonKey that identifies a name usage
056   *
057   * @return the parsed name of the name usage or null if none can be found
058   */
059  @Nullable
060  ParsedName getParsedName(int taxonKey);
061
062  /**
063   * Gets the metrics for a given name usage.
064   *
065   * @param taxonKey that identifies a name usage
066   *
067   * @return the usage metrics of the name usage or null if none can be found
068   */
069  @Nullable
070  NameUsageMetrics getMetrics(int taxonKey);
071
072  /**
073   * Returns the verbatim data for the usage or null if its a generated usage having no verbatim data.
074   * This happens for all nub usages and some other usages which have a non SOURCE origin.
075   *
076   * @return verbatim data for the usage or null
077   */
078  @Nullable
079  VerbatimNameUsage getVerbatim(int taxonKey);
080
081  /**
082   * Page through all usages across all or one checklists.
083   *
084   * @param datasetKey the optional checklist key to limit paging to.
085   * @param sourceId   the optional checklist key to limit paging to.
086   * @param locale     the locale's language determines the vernacular name to use for a usage
087   *                   Use null to not load any common name
088   * @param page       paging parameters or null for first page with default size
089   *
090   * @return Paged list of usages
091   */
092  PagingResponse<NameUsage> list(Locale locale, @Nullable UUID datasetKey, @Nullable String sourceId,
093                                 @Nullable Pageable page);
094
095  /**
096   * Page through all usages with a given canonical name across all or some checklists.
097   *
098   * @param canonicalName the canonical name of a name usage.
099   * @param locale        the locale's language determines the vernacular name to use for a usage
100   *                      Use null to not load any common name
101   * @param datasetKey   the optional list of checklist keys to limit paging to.
102   * @param page          paging parameters or null for first page with default size
103   *
104   * @return Paged list of usages matching the exact canonical name
105   */
106  PagingResponse<NameUsage> listByCanonicalName(Locale locale, String canonicalName, @Nullable Pageable page,
107    @Nullable UUID ... datasetKey);
108
109  /**
110   * Lists all accepted child name usages for a given parent.
111   *
112   * @param parentKey that identifies the parent name usage
113   * @param locale    the locale's language determines the vernacular name to use for a usage
114   *                  Use null to not load any common name
115   * @param page      paging parameters or null for first page with default size
116   *
117   * @return Paged list of child usages.
118   */
119  PagingResponse<NameUsage> listChildren(int parentKey, Locale locale, @Nullable Pageable page);
120
121  /**
122   * Lists the complete parental hierarchy of a name usage regardless of their ranks.
123   *
124   * @param taxonKey that identifies the name usage to show parents of
125   * @param locale   the locale's language determines the vernacular name to use for a usage
126   *                 Use null to not load any common name
127   *
128   * @return List of parent usages with the last usage being the immediate parent
129   */
130  List<NameUsage> listParents(int taxonKey, Locale locale);
131
132  /**
133   * Lists all related checklist usages for a given nub usage.
134   *
135   * @param taxonKey   that identifies a nub usage
136   * @param locale     the locale's language determines the vernacular name to use for a usage
137   *                   Use null to not load any common name
138   * @param page       paging parameters or null for first page with default size
139   * @param datasetKey Optional list of checklist keys to restrict related usages to
140   *
141   * @return Paged list of related name usages.
142   */
143  PagingResponse<NameUsage> listRelated(int taxonKey, Locale locale, @Nullable Pageable page, @Nullable UUID... datasetKey);
144
145  /**
146   * Lists all root usages for a given checklist, i.e. accepted usages without a parent.
147   * To list the 8 root kingdoms of the nub use the respective datasetKey,
148   * @see org.gbif.api.model.Constants#NUB_DATASET_KEY
149   *
150   * @param datasetKey the registered dataset key for the checklist in question
151   * @param locale     the locale's language determines the vernacular name to use for a usage
152   *                   Use null to not load any common name
153   * @param page       paging parameters or null for first page with default size
154   *
155   * @return Paged list of root name usages.
156   *
157   */
158  PagingResponse<NameUsage> listRoot(UUID datasetKey, Locale locale, @Nullable Pageable page);
159
160  /**
161   * Lists all synonym name usages for a given accepted name usage.
162   *
163   * @param taxonKey that identifies any name usage
164   * @param locale   the locale's language determines the vernacular name to use for a usage
165   *                 Use null to not load any common name
166   * @param page     paging parameters or null for first page with default size
167   *
168   * @return Paged list of synonym name usages.
169   */
170  PagingResponse<NameUsage> listSynonyms(int taxonKey, Locale locale, @Nullable Pageable page);
171
172  /**
173   * Lists all combinations or names at different rank that are based on this basionym, i.e. a list of all name usages sharing the same basionym (homotypical group).
174   * The basionym itself is not included in this list.
175   *
176   * @param basionymKey the name usage key of the basionym
177   * @param locale   the locale's language determines the vernacular name to use for a usage
178   *                 Use null to not load any common name
179   *
180   * @return List of name usages sharing the same basionym.
181   */
182  List<NameUsage> listCombinations(int basionymKey, Locale locale);
183
184}