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:
    NameUsage

    • Method Detail

      • 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:
        Constants.NUB_DATASET_KEY

      • 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.