Package org.gbif.api.service.checklistbank

Interface NameUsageService

public interface NameUsageService
This is the public interface providing methods for retrieving name usages in general, no matter if nub or checklist usage.
See Also:

  • Method Details

    • get

      @Nullable NameUsage get(int taxonKey, @Nullable Locale locale)
      Attempt to find a name usage matching the passed key. The given Locale determines the name used for the NameUsage.vernacularName property with null ignoring any vernacular name.
      Parameters:
      taxonKey - that identifies a name usage
      locale - the locale's language determines the vernacular name to use for a usage. Use null to not load any common name
      Returns:
      a matching name usage, or null if no name usage found

    • getParsedName

      @Nullable ParsedName getParsedName(int taxonKey)
      Gets the parsed name representation of a given name usage.
      Parameters:
      taxonKey - that identifies a name usage
      Returns:
      the parsed name of the name usage or null if none can be found

    • getMetrics

      @Nullable NameUsageMetrics getMetrics(int taxonKey)
      Gets the metrics for a given name usage.
      Parameters:
      taxonKey - that identifies a name usage
      Returns:
      the usage metrics of the name usage or null if none can be found

    • getVerbatim

      @Nullable VerbatimNameUsage getVerbatim(int taxonKey)
      Returns the verbatim data for the usage or null if its a generated usage having no verbatim data. This happens for all nub usages and some other usages which have a non SOURCE origin.
      Returns:
      verbatim data for the usage or null

    • list

      PagingResponse<NameUsage> list(Locale locale, @Nullable UUID datasetKey, @Nullable String sourceId, @Nullable Pageable page)
      Page through all usages across all or one checklists.
      Parameters:
      datasetKey - the optional checklist key to limit paging to.
      sourceId - the optional checklist key to limit paging to.
      locale - the locale's language determines the vernacular name to use for a usage Use null to not load any common name
      page - paging parameters or null for first page with default size
      Returns:
      Paged list of usages

    • listByCanonicalName

      PagingResponse<NameUsage> listByCanonicalName(Locale locale, String canonicalName, @Nullable Pageable page, @Nullable UUID... datasetKey)
      Page through all usages with a given canonical name across all or some checklists.
      Parameters:
      canonicalName - the canonical name of a name usage.
      locale - the locale's language determines the vernacular name to use for a usage Use null to not load any common name
      datasetKey - the optional list of checklist keys to limit paging to.
      page - paging parameters or null for first page with default size
      Returns:
      Paged list of usages matching the exact canonical name

    • listChildren

      PagingResponse<NameUsage> listChildren(int parentKey, Locale locale, @Nullable Pageable page)
      Lists all accepted child name usages for a given parent.
      Parameters:
      parentKey - that identifies the parent name usage
      locale - the locale's language determines the vernacular name to use for a usage Use null to not load any common name
      page - paging parameters or null for first page with default size
      Returns:
      Paged list of child usages.

    • listParents

      List<NameUsage> listParents(int taxonKey, Locale locale)
      Lists the complete parental hierarchy of a name usage regardless of their ranks.
      Parameters:
      taxonKey - that identifies the name usage to show parents of
      locale - the locale's language determines the vernacular name to use for a usage Use null to not load any common name
      Returns:
      List of parent usages with the last usage being the immediate parent

    • listRelated

      PagingResponse<NameUsage> listRelated(int taxonKey, Locale locale, @Nullable Pageable page, @Nullable UUID... datasetKey)
      Lists all related checklist usages for a given nub usage.
      Parameters:
      taxonKey - that identifies a nub usage
      locale - the locale's language determines the vernacular name to use for a usage Use null to not load any common name
      page - paging parameters or null for first page with default size
      datasetKey - Optional list of checklist keys to restrict related usages to
      Returns:
      Paged list of related name usages.

    • listRoot

      PagingResponse<NameUsage> listRoot(UUID datasetKey, Locale locale, @Nullable Pageable page)
      Lists all root usages for a given checklist, i.e. accepted usages without a parent. To list the 8 root kingdoms of the nub use the respective datasetKey,
      Parameters:
      datasetKey - the registered dataset key for the checklist in question
      locale - the locale's language determines the vernacular name to use for a usage Use null to not load any common name
      page - paging parameters or null for first page with default size
      Returns:
      Paged list of root name usages.
      See Also:

    • listSynonyms

      PagingResponse<NameUsage> listSynonyms(int taxonKey, Locale locale, @Nullable Pageable page)
      Lists all synonym name usages for a given accepted name usage.
      Parameters:
      taxonKey - that identifies any name usage
      locale - the locale's language determines the vernacular name to use for a usage Use null to not load any common name
      page - paging parameters or null for first page with default size
      Returns:
      Paged list of synonym name usages.

    • listCombinations

      List<NameUsage> listCombinations(int basionymKey, Locale locale)
      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). The basionym itself is not included in this list.
      Parameters:
      basionymKey - the name usage key of the basionym
      locale - the locale's language determines the vernacular name to use for a usage Use null to not load any common name
      Returns:
      List of name usages sharing the same basionym.