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 Summary

Modifier and Type	Method and Description
NameUsage	get(int taxonKey, Locale locale) Attempt to find a name usage matching the passed key.
NameUsageMetrics	getMetrics(int taxonKey) Gets the metrics for a given name usage.
ParsedName	getParsedName(int taxonKey) Gets the parsed name representation of a given name usage.
VerbatimNameUsage	getVerbatim(int taxonKey) Returns the verbatim data for the usage or null if its a generated usage having no verbatim data.
PagingResponse<NameUsage>	list(Locale locale, UUID datasetKey, String sourceId, Pageable page) Page through all usages across all or one checklists.
PagingResponse<NameUsage>	listByCanonicalName(Locale locale, String canonicalName, Pageable page, UUID... datasetKey) Page through all usages with a given canonical name across all or some checklists.
PagingResponse<NameUsage>	listChildren(int parentKey, Locale locale, Pageable page) Lists all accepted child name usages for a given parent.
List<NameUsage>	listCombinations(int basionymKey, Locale locale) Lists all combinations or names at different rank that are based on this basionym, i.e.
List<NameUsage>	listParents(int taxonKey, Locale locale) Lists the complete parental hierarchy of a name usage regardless of their ranks.
PagingResponse<NameUsage>	listRelated(int taxonKey, Locale locale, Pageable page, UUID... datasetKey) Lists all related checklist usages for a given nub usage.
PagingResponse<NameUsage>	listRoot(UUID datasetKey, Locale locale, Pageable page) Lists all root usages for a given checklist, i.e.
PagingResponse<NameUsage>	listSynonyms(int taxonKey, Locale locale, Pageable page) Lists all synonym name usages for a given accepted name usage.

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.