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