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 the NameUsageContainer class.

  • Constructor Details

  • Method Details

    • 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

    • setKey

      public void setKey(Integer key)
      Parameters:
      key - the key to set

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

    • 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

    • setNubKey

      public void setNubKey(Integer nubKey)
      Parameters:
      nubKey - the nubKey to set

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

    • setOrigin

      public void setOrigin(Origin origin)
      Parameters:
      origin - the origin to set

    • getParent

      public String getParent()
      The scientific name of the parent.
      Returns:
      the parent name

    • setParent

      public void setParent(String parent)
      Parameters:
      parent - the parent name to set

    • 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

    • setRank

      public void setRank(Rank rank)
      Parameters:
      rank - the rank to set

    • 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 interface LinneanClassification
      Returns:
      the kingdom

    • setKingdom

      public void setKingdom(String kingdom)
      Specified by:
      setKingdom in interface LinneanClassification
      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 interface LinneanClassification
      Returns:
      the phylum

    • setPhylum

      public void setPhylum(String phylum)
      Specified by:
      setPhylum in interface LinneanClassification
      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 interface LinneanClassification
      Returns:
      the class

    • setClazz

      public void setClazz(String clazz)
      Specified by:
      setClazz in interface LinneanClassification
      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 interface LinneanClassification
      Returns:
      the order

    • setOrder

      public void setOrder(String order)
      Specified by:
      setOrder in interface LinneanClassification
      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 interface LinneanClassification
      Returns:
      the family

    • setFamily

      public void setFamily(String family)
      Specified by:
      setFamily in interface LinneanClassification
      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 interface LinneanClassification
      Returns:
      the genus

    • setGenus

      public void setGenus(String genus)
      Specified by:
      setGenus in interface LinneanClassification
      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 interface LinneanClassification
      Returns:
      the subgenus name

    • setSubgenus

      public void setSubgenus(String subgenus)
      Specified by:
      setSubgenus in interface LinneanClassification
      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 interface LinneanClassification
      Returns:
      the species

    • setSpecies

      public void setSpecies(String species)
      Specified by:
      setSpecies in interface LinneanClassification
      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 interface LinneanClassificationKeys
      Returns:
      the kingdomKey

    • setKingdomKey

      public void setKingdomKey(Integer kingdomKey)
      Specified by:
      setKingdomKey in interface LinneanClassificationKeys
      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 interface LinneanClassificationKeys
      Returns:
      the phylumKey

    • setPhylumKey

      public void setPhylumKey(Integer phylumKey)
      Specified by:
      setPhylumKey in interface LinneanClassificationKeys
      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 interface LinneanClassificationKeys
      Returns:
      the classKey

    • setClassKey

      public void setClassKey(Integer classKey)
      Specified by:
      setClassKey in interface LinneanClassificationKeys
      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 interface LinneanClassificationKeys
      Returns:
      the orderKey

    • setOrderKey

      public void setOrderKey(Integer orderKey)
      Specified by:
      setOrderKey in interface LinneanClassificationKeys
      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 interface LinneanClassificationKeys
      Returns:
      the familyKey

    • setFamilyKey

      public void setFamilyKey(Integer familyKey)
      Specified by:
      setFamilyKey in interface LinneanClassificationKeys
      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 interface LinneanClassificationKeys
      Returns:
      the genusKey

    • setGenusKey

      public void setGenusKey(Integer genusKey)
      Specified by:
      setGenusKey in interface LinneanClassificationKeys
      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 interface LinneanClassificationKeys
      Returns:
      subgenusKey

    • setSubgenusKey

      public void setSubgenusKey(Integer subgenusKey)
      Specified by:
      setSubgenusKey in interface LinneanClassificationKeys
      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 interface LinneanClassificationKeys
      Returns:
      the speciesKey

    • setSpeciesKey

      public void setSpeciesKey(Integer speciesKey)
      Specified by:
      setSpeciesKey in interface LinneanClassificationKeys
      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 interface LinneanClassification
      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 interface LinneanClassificationKeys
      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)

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object