Package org.gbif.api.model.checklistbank
Class NameUsage
- java.lang.Object
-
- org.gbif.api.model.checklistbank.NameUsage
-
- All Implemented Interfaces:
LinneanClassification
,LinneanClassificationKeys
- Direct Known Subclasses:
NameUsageContainer
public class NameUsage extends Object implements LinneanClassification, LinneanClassificationKeys
A usage of a scientific name according to one particular Checklist including the GBIF Taxonomic Backbone, the NUB. It is shown as species in the portal and API.
Backbone (NUB) usages have key==nubKey. Backbone usages can also be detected by either the NameUsage.isNub() method or by manually comparing the datasetKey with the fixed backbone datasetKey, see Constants.NUB_DATASET_KEY.
Name usages from other checklists with names that also exist in the backbone will have a nubKey that points to the related usage in the NUB.
To store not eagerly loaded subresources such as vernacular names or synonyms with a usage please use theNameUsageContainer
class.
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addIssue(NameUsageIssue issue)
boolean
equals(Object o)
String
getAccepted()
Integer
getAcceptedKey()
String
getAccordingTo()
The taxon concept reference is usually a reference to some publication or author and year.String
getAuthorship()
Returns the authorship information for the scientific name.String
getBasionym()
Integer
getBasionymKey()
Returns the earlier name (basionym) for this scientific name.String
getCanonicalName()
String
getCanonicalOrScientificName()
Integer
getClassKey()
Return the class key for this usage.String
getClazz()
Return the class for this usage.UUID
getConstituentKey()
Return the optional sub dataset key for this usage.@NotNull UUID
getDatasetKey()
Returns the key of the checklist that "hosts" this name usage.Date
getDeleted()
The date this record was deleted.String
getFamily()
Return the family for this usage.Integer
getFamilyKey()
Return the family key for this usage.String
getGenus()
Return the genus for this usage.Integer
getGenusKey()
Return the genus key for this usage.@NotNull LinkedHashMap<Integer,String>
getHigherClassificationMap()
An ordered map with entries for all higher Linnean ranks down to the actual direct parent of this usage.String
getHigherRank(Rank rank)
Gets a higher taxon property by passing the rank of it.Integer
getHigherRankKey(Rank rank)
Gets a higher taxon key by passing the rank of it.@NotNull Set<NameUsageIssue>
getIssues()
@NotNull Integer
getKey()
Return the key that uniquely identifies this name usage.String
getKingdom()
Return the kingdom for this usage.Integer
getKingdomKey()
Return the kingdom key for this usage.Date
getLastCrawled()
The date this record was last crawled during clb indexing.Date
getLastInterpreted()
The date this record was last interpreted during indexing.Date
getModified()
The interpreted dc:modified from the verbatim source data.Integer
getNameKey()
NameType
getNameType()
Set<NomenclaturalStatus>
getNomenclaturalStatus()
The status related to the conformance to the relevant rules of nomenclature.Integer
getNubKey()
int
getNumDescendants()
The number of all accepted taxonomic elements under this usage.String
getOrder()
Return the order for this usage.Integer
getOrderKey()
Return the order key for this usage.@NotNull Origin
getOrigin()
The origin of this name usage record, i.e.String
getParent()
The scientific name of the parent.Integer
getParentKey()
Returns the immediate parent.String
getPhylum()
Return the phylum for this usage.Integer
getPhylumKey()
Return the phylum key for this usage.Integer
getProParteKey()
Pro parte synonyms, i.e.String
getPublishedIn()
Original publication for this name usage.Rank
getRank()
Returns the rank for this usage.URI
getReferences()
A URI link or reference to the source of this record, the record's "homepage".String
getRemarks()
@NotNull String
getScientificName()
The scientific name (with date and authorship information if applicable).Integer
getSourceTaxonKey()
For backbone taxa the source taxon key refers to the original name usage that was used during backbone building and is the primary reason that this taxon exists in the backbone.String
getSpecies()
Return the species for this usage.Integer
getSpeciesKey()
Return the species key for this usage.String
getSubgenus()
Return the canonical subgenus name for this usage.Integer
getSubgenusKey()
Return the subgenus key for this usage.String
getTaxonID()
The original taxonID of the name usage as found in the source.TaxonomicStatus
getTaxonomicStatus()
The taxonomic status of the name usage.String
getVernacularName()
A common or vernacular name for this usage.int
hashCode()
boolean
isNub()
boolean
isProParte()
True for pro parte synonyms with multiple accepted usages.boolean
isSynonym()
Convenience method using the taxonomicStatus field.void
setAccepted(String accepted)
Sets the scientific name of the basionym, i.e.void
setAcceptedKey(Integer acceptedKey)
Sets the usage key for the accepted name.void
setAccordingTo(String accordingTo)
void
setAuthorship(String authorship)
void
setBasionym(String basionym)
sets the basionym name.void
setBasionymKey(Integer basionymKey)
void
setCanonicalName(String canonicalName)
void
setClassKey(Integer classKey)
void
setClazz(String clazz)
void
setConstituentKey(UUID constituentKey)
void
setDatasetKey(UUID datasetKey)
void
setDeleted(Date deleted)
void
setFamily(String family)
void
setFamilyKey(Integer familyKey)
void
setGenus(String genus)
void
setGenusKey(Integer genusKey)
void
setIssues(Set<NameUsageIssue> issues)
void
setKey(Integer key)
void
setKingdom(String kingdom)
void
setKingdomKey(Integer kingdomKey)
void
setLastCrawled(Date lastCrawled)
void
setLastInterpreted(Date lastInterpreted)
void
setModified(Date modified)
void
setNameKey(Integer nameKey)
void
setNameType(NameType nameType)
void
setNomenclaturalStatus(Set<NomenclaturalStatus> nomenclaturalStatus)
void
setNubKey(Integer nubKey)
void
setNumDescendants(int numDescendants)
void
setOrder(String order)
void
setOrderKey(Integer orderKey)
void
setOrigin(Origin origin)
void
setParent(String parent)
void
setParentKey(Integer parentKey)
void
setPhylum(String phylum)
void
setPhylumKey(Integer phylumKey)
void
setProParteKey(Integer proParteKey)
Sets the pro parte usage key.void
setPublishedIn(String publishedIn)
void
setRank(Rank rank)
void
setReferences(URI references)
void
setRemarks(String remarks)
void
setScientificName(String scientificName)
void
setSourceTaxonKey(Integer sourceTaxonKey)
void
setSpecies(String species)
void
setSpeciesKey(Integer speciesKey)
void
setSubgenus(String subgenus)
void
setSubgenusKey(Integer subgenusKey)
void
setTaxonID(String taxonID)
void
setTaxonomicStatus(TaxonomicStatus taxonomicStatus)
void
setVernacularName(String vernacularName)
String
toString()
-
-
-
Method Detail
-
getNameKey
public Integer getNameKey()
- Returns:
- the name key for retrieving a parsed name object
-
setNameKey
public void setNameKey(Integer nameKey)
-
getSourceTaxonKey
@Nullable public Integer getSourceTaxonKey()
For backbone taxa the source taxon key refers to the original name usage that was used during backbone building and is the primary reason that this taxon exists in the backbone.
All backbone name usages are built from several underlying checklist usages, but these are sorted by priority and the usage key for the highest priority one becomes the sourceTaxonKey for a backbone usage.
Some backbone usages do not have any source record altogether. For example if there is a subspecies found, but no matching parent species, the missing species will be created nevertheless and has no primary source.- Returns:
- The key of the name usage this backbone taxon is derived from.
-
setSourceTaxonKey
public void setSourceTaxonKey(Integer sourceTaxonKey)
-
getAccepted
public String getAccepted()
- Returns:
- the scientific name of the accepted name
-
setAccepted
public void setAccepted(String accepted)
Sets the scientific name of the basionym, i.e. original name usage.
-
getAcceptedKey
public Integer getAcceptedKey()
- Returns:
- the name usage key of the accepted name
-
setAcceptedKey
public void setAcceptedKey(Integer acceptedKey)
Sets the usage key for the accepted name.
-
getAccordingTo
@Nullable public String getAccordingTo()
The taxon concept reference is usually a reference to some publication or author and year.
The dwc:taxonAccordingTo reference is usually appended to the scientific name to further qualify the concept with "sensu" or "sec." being used for concatenation. E.g. "Acer nigrum sec. Gleason Cronquist 1991".
In the case of backbone taxa this refers to the primary checklist the name was found in.- Returns:
- the taxon concept reference
-
setAccordingTo
public void setAccordingTo(String accordingTo)
- Parameters:
accordingTo
- the accordingTo to set
-
getAuthorship
@Nullable public String getAuthorship()
Returns the authorship information for the scientific name.- Returns:
- the authorship
-
setAuthorship
public void setAuthorship(String authorship)
- Parameters:
authorship
- the authorship to set
-
getBasionym
public String getBasionym()
- Returns:
- the scientific name of the basionym
-
setBasionym
public void setBasionym(String basionym)
sets the basionym name.
-
getBasionymKey
@Nullable public Integer getBasionymKey()
Returns the earlier name (basionym) for this scientific name. Return null if the basionym does not exist.- Returns:
- the basionymKey
-
setBasionymKey
public void setBasionymKey(Integer basionymKey)
- Parameters:
basionymKey
- the basionymKey to set
-
getCanonicalName
@Nullable public String getCanonicalName()
- Returns:
- the canonicalName
-
setCanonicalName
public void setCanonicalName(String canonicalName)
- Parameters:
canonicalName
- the canonicalName to set
-
getDatasetKey
@NotNull public @NotNull UUID getDatasetKey()
Returns the key of the checklist that "hosts" this name usage.- Returns:
- the datasetKey
-
setDatasetKey
public void setDatasetKey(UUID datasetKey)
- Parameters:
datasetKey
- the datasetKey to set
-
getKey
@NotNull public @NotNull Integer getKey()
Return the key that uniquely identifies this name usage.- Returns:
- the key
-
getNameType
public NameType getNameType()
- Returns:
- the type of name string classified by CLB.
-
setNameType
public void setNameType(NameType nameType)
- Parameters:
nameType
- the type of name string
-
getNomenclaturalStatus
public Set<NomenclaturalStatus> getNomenclaturalStatus()
The status related to the conformance to the relevant rules of nomenclature.Example: "invalid", "misapplied", "homotypic synonym", "accepted"
- Returns:
- the set of known nomenclaturalStatus values
- See Also:
- Nomenclatural Status GBIF Vocabulary
-
setNomenclaturalStatus
public void setNomenclaturalStatus(Set<NomenclaturalStatus> nomenclaturalStatus)
- Parameters:
nomenclaturalStatus
- the nomenclaturalStatus to set
-
getNubKey
@Nullable public Integer getNubKey()
- Returns:
- the taxon key of the matching backbone name usage
-
getNumDescendants
public int getNumDescendants()
The number of all accepted taxonomic elements under this usage.- Returns:
- the number of descendants
-
setNumDescendants
public void setNumDescendants(int numDescendants)
- Parameters:
numDescendants
- the n umber of descendants to set
-
getOrigin
@NotNull public @NotNull Origin getOrigin()
The origin of this name usage record, i.e. the reason why it exists. In most cases this is because the record existed explicitly in the checklist sources, but some usages are created de novo because they exist implicitly in the data.- Returns:
- the name usage origin
- See Also:
Origin
-
getParentKey
@Nullable public Integer getParentKey()
Returns the immediate parent. If this usage if for the highest taxonomic level, return null.- Returns:
- the parentKey
-
setParentKey
public void setParentKey(Integer parentKey)
- Parameters:
parentKey
- the parentKey to set
-
getProParteKey
public Integer getProParteKey()
Pro parte synonyms, i.e. a synonym with multiple accepted names, are grouped by a single, primary name usage key.- Returns:
- the primary name usage key for a pro parte synonym or null
-
setProParteKey
public void setProParteKey(Integer proParteKey)
Sets the pro parte usage key.
-
getPublishedIn
@Nullable public String getPublishedIn()
Original publication for this name usage.- Returns:
- the publishedIn
-
setPublishedIn
public void setPublishedIn(String publishedIn)
- Parameters:
publishedIn
- the publishedIn to set
-
getRank
@Nullable public Rank getRank()
Returns the rank for this usage.Example: "Kingdom", "Genus"
- Returns:
- the rank
-
getScientificName
@NotNull public @NotNull String getScientificName()
The scientific name (with date and authorship information if applicable).Example: "Coleoptera" (order), "Vespertilionidae" (family), "Manis" (genus), "Ctenomys sociabilis" (genus + specific name), "Ambystoma tigrinum diaboli" (genus + specific name + infraspecific name), "Quercus agrifolia var. oxyadenia (Torr.)"
- Returns:
- the scientificName
-
setScientificName
public void setScientificName(String scientificName)
- Parameters:
scientificName
- the scientificName to set
-
getConstituentKey
@Nullable public UUID getConstituentKey()
Return the optional sub dataset key for this usage.- Returns:
- the subDatasetKey or null
-
setConstituentKey
public void setConstituentKey(UUID constituentKey)
- Parameters:
constituentKey
- to set
-
getVernacularName
@Nullable public String getVernacularName()
A common or vernacular name for this usage.Example: Andean Condor", "Condor Andino", "American Eagle", "Gänsegeier".
- Returns:
- the vernacularName
-
setVernacularName
public void setVernacularName(String vernacularName)
- Parameters:
vernacularName
- the vernacularName to set
-
getKingdom
public String getKingdom()
Description copied from interface:LinneanClassification
Return the kingdom for this usage. If the usage is for something above the "kingdom" taxonomic level, return null.- Specified by:
getKingdom
in interfaceLinneanClassification
- Returns:
- the kingdom
-
setKingdom
public void setKingdom(String kingdom)
- Specified by:
setKingdom
in interfaceLinneanClassification
- Parameters:
kingdom
- the kingdom to set
-
getPhylum
public String getPhylum()
Description copied from interface:LinneanClassification
Return the phylum for this usage. If the usage is for something above the "phylum" taxonomic level, return null.- Specified by:
getPhylum
in interfaceLinneanClassification
- Returns:
- the phylum
-
setPhylum
public void setPhylum(String phylum)
- Specified by:
setPhylum
in interfaceLinneanClassification
- Parameters:
phylum
- the phylum to set
-
getClazz
public String getClazz()
Description copied from interface:LinneanClassification
Return the class for this usage. If the usage is for something above the "class" taxonomic level, return null.- Specified by:
getClazz
in interfaceLinneanClassification
- Returns:
- the class
-
setClazz
public void setClazz(String clazz)
- Specified by:
setClazz
in interfaceLinneanClassification
- Parameters:
clazz
- the clazz to set
-
getOrder
public String getOrder()
Description copied from interface:LinneanClassification
Return the order for this usage. If the usage is for something above the "order" taxonomic level, return null.- Specified by:
getOrder
in interfaceLinneanClassification
- Returns:
- the order
-
setOrder
public void setOrder(String order)
- Specified by:
setOrder
in interfaceLinneanClassification
- Parameters:
order
- the order to set
-
getFamily
public String getFamily()
Description copied from interface:LinneanClassification
Return the family for this usage. If the usage is for something above the "family" taxonomic level, return null.- Specified by:
getFamily
in interfaceLinneanClassification
- Returns:
- the family
-
setFamily
public void setFamily(String family)
- Specified by:
setFamily
in interfaceLinneanClassification
- Parameters:
family
- the family to set
-
getGenus
public String getGenus()
Description copied from interface:LinneanClassification
Return the genus for this usage. If the usage is for something above the "genus" taxonomic level, return null.- Specified by:
getGenus
in interfaceLinneanClassification
- Returns:
- the genus
-
setGenus
public void setGenus(String genus)
- Specified by:
setGenus
in interfaceLinneanClassification
- Parameters:
genus
- the genus to set
-
getSubgenus
public String getSubgenus()
Description copied from interface:LinneanClassification
Return the canonical subgenus name for this usage. If the usage is for something above the "subgenus" taxonomic level, return null.- Specified by:
getSubgenus
in interfaceLinneanClassification
- Returns:
- the subgenus name
-
setSubgenus
public void setSubgenus(String subgenus)
- Specified by:
setSubgenus
in interfaceLinneanClassification
- Parameters:
subgenus
- the subgenus canonical name
-
getSpecies
public String getSpecies()
Description copied from interface:LinneanClassification
Return the species for this usage. If the usage is for something above the "species" taxonomic level, return null.- Specified by:
getSpecies
in interfaceLinneanClassification
- Returns:
- the species
-
setSpecies
public void setSpecies(String species)
- Specified by:
setSpecies
in interfaceLinneanClassification
- Parameters:
species
- the species to set
-
getKingdomKey
public Integer getKingdomKey()
Description copied from interface:LinneanClassificationKeys
Return the kingdom key for this usage. If the usage is for something above the "kingdom" taxonomic level, return null.- Specified by:
getKingdomKey
in interfaceLinneanClassificationKeys
- Returns:
- the kingdomKey
-
setKingdomKey
public void setKingdomKey(Integer kingdomKey)
- Specified by:
setKingdomKey
in interfaceLinneanClassificationKeys
- Parameters:
kingdomKey
- the kingdomKey to set
-
getPhylumKey
public Integer getPhylumKey()
Description copied from interface:LinneanClassificationKeys
Return the phylum key for this usage. If the usage is for something above the "phylum" taxonomic level, return null.- Specified by:
getPhylumKey
in interfaceLinneanClassificationKeys
- Returns:
- the phylumKey
-
setPhylumKey
public void setPhylumKey(Integer phylumKey)
- Specified by:
setPhylumKey
in interfaceLinneanClassificationKeys
- Parameters:
phylumKey
- the phylumKey to set
-
getClassKey
public Integer getClassKey()
Description copied from interface:LinneanClassificationKeys
Return the class key for this usage. If the usage is for something above the "class" taxonomic level, return null.- Specified by:
getClassKey
in interfaceLinneanClassificationKeys
- Returns:
- the classKey
-
setClassKey
public void setClassKey(Integer classKey)
- Specified by:
setClassKey
in interfaceLinneanClassificationKeys
- Parameters:
classKey
- the classKey to set
-
getOrderKey
public Integer getOrderKey()
Description copied from interface:LinneanClassificationKeys
Return the order key for this usage. If the usage is for something above the "order" taxonomic level, return null.- Specified by:
getOrderKey
in interfaceLinneanClassificationKeys
- Returns:
- the orderKey
-
setOrderKey
public void setOrderKey(Integer orderKey)
- Specified by:
setOrderKey
in interfaceLinneanClassificationKeys
- Parameters:
orderKey
- the orderKey to set
-
getFamilyKey
public Integer getFamilyKey()
Description copied from interface:LinneanClassificationKeys
Return the family key for this usage. If the usage is for something above the "family" taxonomic level, return null.- Specified by:
getFamilyKey
in interfaceLinneanClassificationKeys
- Returns:
- the familyKey
-
setFamilyKey
public void setFamilyKey(Integer familyKey)
- Specified by:
setFamilyKey
in interfaceLinneanClassificationKeys
- Parameters:
familyKey
- the familyKey to set
-
getGenusKey
public Integer getGenusKey()
Description copied from interface:LinneanClassificationKeys
Return the genus key for this usage. If the usage is for something above the "genus" taxonomic level, return null.- Specified by:
getGenusKey
in interfaceLinneanClassificationKeys
- Returns:
- the genusKey
-
setGenusKey
public void setGenusKey(Integer genusKey)
- Specified by:
setGenusKey
in interfaceLinneanClassificationKeys
- Parameters:
genusKey
- the genusKey to set
-
getSubgenusKey
public Integer getSubgenusKey()
Description copied from interface:LinneanClassificationKeys
Return the subgenus key for this usage. If the usage is for something above the "subgenus" taxonomic level, return null.- Specified by:
getSubgenusKey
in interfaceLinneanClassificationKeys
- Returns:
- subgenusKey
-
setSubgenusKey
public void setSubgenusKey(Integer subgenusKey)
- Specified by:
setSubgenusKey
in interfaceLinneanClassificationKeys
- Parameters:
subgenusKey
- the subgenus usage key
-
getSpeciesKey
public Integer getSpeciesKey()
Description copied from interface:LinneanClassificationKeys
Return the species key for this usage. If the usage is for something above the "species" taxonomic level, return null.- Specified by:
getSpeciesKey
in interfaceLinneanClassificationKeys
- Returns:
- the speciesKey
-
setSpeciesKey
public void setSpeciesKey(Integer speciesKey)
- Specified by:
setSpeciesKey
in interfaceLinneanClassificationKeys
- Parameters:
speciesKey
- the speciesKey to set
-
getRemarks
public String getRemarks()
-
setRemarks
public void setRemarks(String remarks)
-
getCanonicalOrScientificName
@Nullable public String getCanonicalOrScientificName()
- Returns:
- the canonicalName or scientific name in case its null
-
getReferences
@Nullable public URI getReferences()
A URI link or reference to the source of this record, the record's "homepage".Example: https://www.catalogueoflife.org/data/taxon/4R5YN
- Returns:
- the link
-
setReferences
public void setReferences(URI references)
-
getHigherRank
public String getHigherRank(Rank rank)
Description copied from interface:LinneanClassification
Gets a higher taxon property by passing the rank of it. Only Linnean ranks are supported.- Specified by:
getHigherRank
in interfaceLinneanClassification
- Parameters:
rank
- the higher linnean rank to retrieve- Returns:
- the name of the higher taxon or null if rank doesnt exist
-
getHigherRankKey
public Integer getHigherRankKey(Rank rank)
Description copied from interface:LinneanClassificationKeys
Gets a higher taxon key by passing the rank of it. Only Linnean ranks are supported.- Specified by:
getHigherRankKey
in interfaceLinneanClassificationKeys
- Parameters:
rank
- the higher linnean rank to retrieve- Returns:
- the key of the higher taxon or null if rank doesnt exist
-
getHigherClassificationMap
@NotNull public @NotNull LinkedHashMap<Integer,String> getHigherClassificationMap()
An ordered map with entries for all higher Linnean ranks down to the actual direct parent of this usage. The map starts with the highest rank, e.g. the kingdom and maps the name usage key to its canonical name. The name usage itself is never included, even though a higher rank might point to the usage itself.- Returns:
- map of higher ranks
-
getTaxonID
@Nullable public String getTaxonID()
The original taxonID of the name usage as found in the source. For backbone taxa and name usages with an origin different to SOURCE this is null.
-
getTaxonomicStatus
@Nullable public TaxonomicStatus getTaxonomicStatus()
The taxonomic status of the name usage. Can be null, but for all synonyms with an accepted name usage it is guaranteed to exist.- Returns:
- the taxonomicStatus, can be null
-
setTaxonomicStatus
public void setTaxonomicStatus(TaxonomicStatus taxonomicStatus)
- Parameters:
taxonomicStatus
- the taxonomicStatus to set
-
getModified
@Nullable public Date getModified()
The interpreted dc:modified from the verbatim source data. Ideally indicating when a record was last modified in the source.
-
setModified
public void setModified(Date modified)
-
getDeleted
@Nullable public Date getDeleted()
The date this record was deleted. Logical deletions only occur for backbone usages!
-
setDeleted
public void setDeleted(Date deleted)
-
getLastCrawled
@Nullable public Date getLastCrawled()
The date this record was last crawled during clb indexing.
-
setLastCrawled
public void setLastCrawled(Date lastCrawled)
-
getLastInterpreted
@Nullable public Date getLastInterpreted()
The date this record was last interpreted during indexing. This includes matching to the backbone.
-
setLastInterpreted
public void setLastInterpreted(Date lastInterpreted)
-
getIssues
@NotNull public @NotNull Set<NameUsageIssue> getIssues()
-
setIssues
public void setIssues(Set<NameUsageIssue> issues)
-
addIssue
public void addIssue(NameUsageIssue issue)
-
isNub
public boolean isNub()
-
isProParte
public boolean isProParte()
True for pro parte synonyms with multiple accepted usages.- Returns:
- true if proParte, false otherwise
-
isSynonym
public boolean isSynonym()
Convenience method using the taxonomicStatus field.- Returns:
- true if it's a synonym
-
setTaxonID
public void setTaxonID(String taxonID)
-
-