cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/INonViralName.java

   1 /**
   2 * Copyright (C) 2017 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9 package eu.etaxonomy.cdm.model.name;
  10
  11 import java.util.List;
  12 import java.util.Set;
  13
  14 import javax.persistence.Transient;
  15
  16 import eu.etaxonomy.cdm.model.agent.TeamOrPersonBase;
  17
  18 /**
  19  * @author a.mueller
  20  * @date 21.01.2017
  21  *
  22  */
  23 public interface INonViralName<T extends NonViralName> extends ITaxonNameBase<T>{
  24
  25     /**
  26      * Creates a new {@link HybridRelationship#HybridRelationship(TaxonNameBase, TaxonNameBase, HybridRelationshipType, String) hybrid relationship}
  27      * to <i>this</i> non viral name. A HybridRelationship may be of type
  28      * "is first/second parent" or "is male/female parent". By invoking this
  29      * method <i>this</i> non viral name becomes a parent of the hybrid child
  30      * non viral name.
  31      *
  32      * @param childName       the non viral name of the child for this new hybrid name relationship
  33      * @param type            the type of this new name relationship
  34      * @param ruleConsidered  the string which specifies the rule on which this name relationship is based
  35      * @return
  36      * @see                   #addHybridParent(TaxonNameBase, HybridRelationshipType,String )
  37      * @see                   #getRelationsToThisName()
  38      * @see                   #getNameRelations()
  39      * @see                   #addRelationshipFromName(TaxonNameBase, NameRelationshipType, String)
  40      * @see                   #addNameRelationship(NameRelationship)
  41      */
  42     public HybridRelationship addHybridChild(NonViralName childName, HybridRelationshipType type, String ruleConsidered);
  43
  44     /**
  45      * Creates a new {@link HybridRelationship#HybridRelationship(TaxonNameBase, TaxonNameBase, HybridRelationshipType, String) hybrid relationship}
  46      * to <i>this</i> non viral name. A HybridRelationship may be of type
  47      * "is first/second parent" or "is male/female parent". By invoking this
  48      * method <i>this</i> non viral name becomes a hybrid child of the parent
  49      * non viral name.
  50      *
  51      * @param parentName      the non viral name of the parent for this new hybrid name relationship
  52      * @param type            the type of this new name relationship
  53      * @param ruleConsidered  the string which specifies the rule on which this name relationship is based
  54      * @return
  55      * @see                   #addHybridChild(TaxonNameBase, HybridRelationshipType,String )
  56      * @see                   #getRelationsToThisName()
  57      * @see                   #getNameRelations()
  58      * @see                   #addRelationshipFromName(TaxonNameBase, NameRelationshipType, String)
  59      * @see                   #addNameRelationship(NameRelationship)
  60      */
  61     public HybridRelationship addHybridParent(NonViralName parentName, HybridRelationshipType type, String ruleConsidered);
  62
  63     /**
  64      * Shortcut. Returns the basionym authors title cache. Returns null if no basionym author exists.
  65      * @return
  66      */
  67     public String computeBasionymAuthorNomenclaturalTitle() ;
  68
  69     /**
  70      * Shortcut. Returns the combination authors title cache. Returns null if no combination author exists.
  71      * @return
  72      */
  73     public String computeCombinationAuthorNomenclaturalTitle();
  74
  75     /**
  76      * Shortcut. Returns the ex-basionym authors title cache. Returns null if no exbasionym author exists.
  77      * @return
  78      */
  79     public String computeExBasionymAuthorNomenclaturalTitle();
  80
  81     /**
  82      * Shortcut. Returns the ex-combination authors title cache. Returns null if no ex-combination author exists.
  83      * @return
  84      */
  85     public String computeExCombinationAuthorNomenclaturalTitle();
  86
  87     /**
  88      * Generates and returns a concatenated and formatted author teams string
  89      * including basionym and combination authors of <i>this</i> non viral taxon name
  90      * according to the strategy defined in
  91      * {@link eu.etaxonomy.cdm.strategy.cache.name.INonViralNameCacheStrategy#getAuthorshipCache(NonViralName) INonViralNameCacheStrategy}.
  92      *
  93      * @return  the string with the concatenated and formated author teams for <i>this</i> non viral taxon name
  94      * @see     eu.etaxonomy.cdm.strategy.cache.name.INonViralNameCacheStrategy#getAuthorshipCache(NonViralName)
  95      */
  96     public String generateAuthorship();
  97
  98
  99     /**
 100      * Returns the concatenated and formatted author teams string including
 101      * basionym and combination authors of <i>this</i> non viral taxon name.
 102      * If the protectedAuthorshipCache flag is set this method returns the
 103      * string stored in the the authorshipCache attribute, otherwise it
 104      * generates the complete authorship string, returns it and stores it in
 105      * the authorshipCache attribute.
 106      *
 107      * @return  the string with the concatenated and formated author teams for <i>this</i> non viral taxon name
 108      * @see     #generateAuthorship()
 109      */
 110     @Transient
 111     public String getAuthorshipCache();
 112
 113     /**
 114      * Returns the {@link eu.etaxonomy.cdm.model.agent.TeamOrPersonBase author (team)} that published the original combination
 115      * on which <i>this</i> non viral taxon name is nomenclaturally based. Such an
 116      * author (team) can only exist if <i>this</i> non viral taxon name is a new
 117      * combination due to a taxonomical revision.
 118      *
 119      * @return  the nomenclatural basionym author (team) of <i>this</i> non viral taxon name
 120      * @see     #getCombinationAuthorship()
 121      * @see     eu.etaxonomy.cdm.model.agent.INomenclaturalAuthor
 122      * @see     eu.etaxonomy.cdm.model.agent.TeamOrPersonBase#getNomenclaturalTitle()
 123      */
 124     public TeamOrPersonBase<?> getBasionymAuthorship();
 125
 126     /**
 127      * Returns the {@link eu.etaxonomy.cdm.model.agent.TeamOrPersonBase author (team)} that published <i>this</i> non viral
 128      * taxon name.
 129      *
 130      * @return  the nomenclatural author (team) of <i>this</i> non viral taxon name
 131      * @see     eu.etaxonomy.cdm.model.agent.INomenclaturalAuthor
 132      * @see     eu.etaxonomy.cdm.model.agent.TeamOrPersonBase#getNomenclaturalTitle()
 133      */
 134     public TeamOrPersonBase<?> getCombinationAuthorship();
 135
 136
 137     /**
 138      * Returns the {@link eu.etaxonomy.cdm.model.agent.TeamOrPersonBase author (team)} that contributed to
 139      * the publication of the original combination <i>this</i> non viral taxon name is
 140      * based on. This should have been generally stated by
 141      * the {@link #getBasionymAuthorship() basionym author (team)} itself.
 142      * The presence of a basionym author (team) of <i>this</i> non viral taxon name is a
 143      * condition for the existence of an ex basionym author (team)
 144      * for <i>this</i> same name.
 145      *
 146      * @return  the nomenclatural ex basionym author (team) of <i>this</i> non viral taxon name
 147      * @see     #getBasionymAuthorship()
 148      * @see     #getExCombinationAuthorship()
 149      * @see     #getCombinationAuthorship()
 150      * @see     eu.etaxonomy.cdm.model.agent.INomenclaturalAuthor
 151      * @see     eu.etaxonomy.cdm.model.agent.TeamOrPersonBase#getNomenclaturalTitle()
 152      */
 153     public TeamOrPersonBase<?> getExBasionymAuthorship();
 154
 155     /**
 156      * Returns the {@link eu.etaxonomy.cdm.model.agent.TeamOrPersonBase author (team)} that contributed to
 157      * the publication of <i>this</i> non viral taxon name as generally stated by
 158      * the {@link #getCombinationAuthorship() combination author (team)} itself.<BR>
 159      * An ex-author(-team) is an author(-team) to whom a taxon name was ascribed
 160      * although it is not the author(-team) of a valid publication (for instance
 161      * without the validating description or diagnosis in case of a name for a
 162      * new taxon). The name of this ascribed authorship, followed by "ex", may
 163      * be inserted before the name(s) of the publishing author(s) of the validly
 164      * published name:<BR>
 165      * <i>Lilium tianschanicum</i> was described by Grubov (1977) as a new species and
 166      * its name was ascribed to Ivanova; since there is no indication that
 167      * Ivanova provided the validating description, the name may be cited as
 168      * <i>Lilium tianschanicum</i> N. A. Ivanova ex Grubov or <i>Lilium tianschanicum</i> Grubov.
 169      * <P>
 170      * The presence of an author (team) of <i>this</i> non viral taxon name is a
 171      * condition for the existence of an ex author (team) for <i>this</i> same name.
 172      *
 173      * @return  the nomenclatural ex author (team) of <i>this</i> non viral taxon name
 174      * @see     #getCombinationAuthorship()
 175      * @see     eu.etaxonomy.cdm.model.agent.INomenclaturalAuthor
 176      * @see     eu.etaxonomy.cdm.model.agent.TeamOrPersonBase#getNomenclaturalTitle()
 177      */
 178     public TeamOrPersonBase<?> getExCombinationAuthorship();
 179
 180     /**
 181      * Returns either the scientific name string (without authorship) for <i>this</i>
 182      * non viral taxon name if its rank is genus or higher (monomial) or the string for
 183      * the genus part of it if its {@link Rank rank} is lower than genus (bi- or trinomial).
 184      * Genus or uninomial strings begin with an upper case letter.
 185      *
 186      * @return  the string containing the suprageneric name, the genus name or the genus part of <i>this</i> non viral taxon name
 187      * @see     #getNameCache()
 188      */
 189     public String getGenusOrUninomial();
 190
 191     /**
 192      * Returns the set of all {@link HybridRelationship hybrid relationships}
 193      * in which <i>this</i> taxon name is involved as a {@link common.RelationshipBase#getRelatedTo() child}.
 194      *
 195      * @see    #getHybridRelationships()
 196      * @see    #getParentRelationships()
 197      * @see    HybridRelationshipType
 198      */
 199     public Set<HybridRelationship> getHybridChildRelations();
 200
 201     /**
 202      * Returns the set of all {@link HybridRelationship hybrid relationships}
 203      * in which <i>this</i> taxon name is involved as a {@link common.RelationshipBase#getRelatedFrom() parent}.
 204      *
 205      * @see    #getHybridRelationships()
 206      * @see    #getChildRelationships()
 207      * @see    HybridRelationshipType
 208      */
 209     public Set<HybridRelationship> getHybridParentRelations();
 210
 211     /**
 212      * Returns the genus subdivision epithet string (infrageneric part) for
 213      * <i>this</i> non viral taxon name if its {@link Rank rank} is infrageneric (lower than genus and
 214      * higher than species aggregate: binomial). Genus subdivision epithet
 215      * strings begin with an upper case letter.
 216      *
 217      * @return  the string containing the infrageneric part of <i>this</i> non viral taxon name
 218      * @see     #getNameCache()
 219      */
 220     public String getInfraGenericEpithet();
 221
 222     /**
 223      * Returns the species epithet string for <i>this</i> non viral taxon name if its {@link Rank rank} is
 224      * species aggregate or lower (bi- or trinomial). Species epithet strings
 225      * begin with a lower case letter.
 226      *
 227      * @return  the string containing the species epithet of <i>this</i> non viral taxon name
 228      * @see     #getNameCache()
 229      */
 230     public String getSpecificEpithet();
 231
 232     /**
 233      * Returns the species subdivision epithet string (infraspecific part) for
 234      * <i>this</i> non viral taxon name if its {@link Rank rank} is infraspecific
 235      * (lower than species: trinomial). Species subdivision epithet strings
 236      * begin with a lower case letter.
 237      *
 238      * @return  the string containing the infraspecific part of <i>this</i> non viral taxon name
 239      * @see     #getNameCache()
 240      */
 241     public String getInfraSpecificEpithet();
 242
 243
 244     /**
 245      * Defines the last part of the name.
 246      * This is for infraspecific taxa, the infraspecific epithet,
 247      * for species the specific epithet, for infageneric taxa the infrageneric epithet
 248      * else the genusOrUninomial.
 249      * However, the result does not depend on the rank (which may be not correctly set
 250      * in case of dirty data) but returns the first name part which is not blank
 251      * considering the above order.
 252      * @return the first not blank name part in reverse order
 253      */
 254     public String getLastNamePart();
 255
 256     /**
 257      * Returns or generates the nameCache (scientific name
 258      * without author strings and year) string for <i>this</i> non viral taxon name. If the
 259      * {@link #isProtectedNameCache() protectedNameCache} flag is not set (False)
 260      * the string will be generated according to a defined strategy,
 261      * otherwise the value of the actual nameCache string will be returned.
 262      *
 263      * @return  the string which identifies <i>this</i> non viral taxon name (without authors or year)
 264      * @see     #generateNameCache()
 265      */
 266     @Transient
 267     public String getNameCache() ;
 268
 269     /**
 270      * Returns the hybrid child relationships ordered by relationship type, or if equal
 271      * by title cache of the related names.
 272      * @see #getHybridParentRelations()
 273      */
 274     @Transient
 275     public List<HybridRelationship> getOrderedChildRelationships();
 276
 277     /**
 278      * Tests if the given name has any authors.
 279      * @return false if no author ((ex)combination or (ex)basionym) exists, true otherwise
 280      */
 281     public boolean hasAuthors();
 282
 283     /**
 284      * Needs to be implemented by those classes that handle autonyms (e.g. botanical names).
 285      **/
 286    @Transient
 287    public boolean isAutonym();
 288
 289
 290    /**
 291     * Returns the boolean value of the flag indicating whether the name of <i>this</i>
 292     * botanical taxon name is a hybrid formula (true) or not (false). A hybrid
 293     * named by a hybrid formula (composed with its parent names by placing the
 294     * multiplication sign between them) does not have an own published name
 295     * and therefore has neither an {@link NonViralName#getAuthorshipCache() autorship}
 296     * nor other name components. If this flag is set no other hybrid flags may
 297     * be set.
 298     *
 299     * @return  the boolean value of the isHybridFormula flag
 300     * @see     #isMonomHybrid()
 301     * @see     #isBinomHybrid()
 302     * @see     #isTrinomHybrid()
 303     */
 304    public boolean isHybridFormula();
 305
 306    /**
 307     * Returns the boolean value of the flag indicating whether <i>this</i> botanical
 308     * taxon name is the name of an intergeneric hybrid (true) or not (false).
 309     * In this case the multiplication sign is placed before the scientific
 310     * name. If this flag is set no other hybrid flags may be set.
 311     *
 312     * @return  the boolean value of the isMonomHybrid flag
 313     * @see     #isHybridFormula()
 314     * @see     #isBinomHybrid()
 315     * @see     #isTrinomHybrid()
 316     */
 317    public boolean isMonomHybrid();
 318
 319    /**
 320     * Returns the boolean value of the flag indicating whether <i>this</i> botanical
 321     * taxon name is the name of an interspecific hybrid (true) or not (false).
 322     * In this case the multiplication sign is placed before the species
 323     * epithet. If this flag is set no other hybrid flags may be set.
 324     *
 325     * @return  the boolean value of the isBinomHybrid flag
 326     * @see     #isHybridFormula()
 327     * @see     #isMonomHybrid()
 328     * @see     #isTrinomHybrid()
 329     */
 330    public boolean isBinomHybrid();
 331
 332    /**
 333     * Returns the boolean value of the flag indicating whether <i>this</i> botanical
 334     * taxon name is the name of an infraspecific hybrid (true) or not (false).
 335     * In this case the term "notho-" (optionally abbreviated "n-") is used as
 336     * a prefix to the term denoting the infraspecific rank of <i>this</i> botanical
 337     * taxon name. If this flag is set no other hybrid flags may be set.
 338     *
 339     * @return  the boolean value of the isTrinomHybrid flag
 340     * @see     #isHybridFormula()
 341     * @see     #isMonomHybrid()
 342     * @see     #isBinomHybrid()
 343     */
 344    public boolean isTrinomHybrid();
 345
 346
 347    /**
 348     * Returns the boolean value of the flag intended to protect (true)
 349     * or not (false) the {@link #getAuthorshipCache() authorshipCache} (complete authorship string)
 350     * of <i>this</i> non viral taxon name.
 351     *
 352     * @return  the boolean value of the protectedAuthorshipCache flag
 353     * @see     #getAuthorshipCache()
 354     */
 355    public boolean isProtectedAuthorshipCache();
 356
 357
 358    /**
 359     * Returns the boolean value of the flag intended to protect (true)
 360     * or not (false) the {@link #getNameCache() nameCache} (scientific name without author strings and year)
 361     * string of <i>this</i> non viral taxon name.
 362     *
 363     * @return  the boolean value of the protectedNameCache flag
 364     * @see     #getNameCache()
 365     */
 366    public boolean isProtectedNameCache();
 367
 368    public void removeHybridChild(NonViralName child);
 369
 370    public void removeHybridParent(NonViralName parent);
 371
 372    /**
 373     * Removes one {@link HybridRelationship hybrid relationship} from the set of
 374     * {@link #getHybridRelationships() hybrid relationships} in which <i>this</i> botanical taxon name
 375     * is involved. The hybrid relationship will also be removed from the set
 376     * belonging to the second botanical taxon name involved.
 377     *
 378     * @param  relationship  the hybrid relationship which should be deleted from the corresponding sets
 379     * @see                  #getHybridRelationships()
 380     */
 381    public void removeHybridRelationship(HybridRelationship hybridRelation);
 382
 383    /**
 384     * Assigns an authorshipCache string to <i>this</i> non viral taxon name. Sets the isProtectedAuthorshipCache
 385     * flag to <code>true</code>.
 386     *
 387     * @param  authorshipCache  the string which identifies the complete authorship of <i>this</i> non viral taxon name
 388     * @see    #getAuthorshipCache()
 389     */
 390    public void setAuthorshipCache(String authorshipCache);
 391
 392
 393    /**
 394     * Assigns an authorshipCache string to <i>this</i> non viral taxon name.
 395     *
 396     * @param  authorshipCache  the string which identifies the complete authorship of <i>this</i> non viral taxon name
 397     * @param  protectedAuthorshipCache if true the isProtectedAuthorshipCache flag is set to <code>true</code>, otherwise
 398     * the flag is set to <code>false</code>.
 399     * @see    #getAuthorshipCache()
 400     */
 401    public void setAuthorshipCache(String authorshipCache, boolean protectedAuthorshipCache);
 402
 403    /**
 404     * @see  #getBasionymAuthorship()
 405     */
 406    public void setBasionymAuthorship(TeamOrPersonBase<?> basionymAuthorship);
 407
 408    /**
 409     * @see  #isBinomHybrid()
 410     * @see  #isMonomHybrid()
 411     * @see  #isTrinomHybrid()
 412     */
 413    public void setBinomHybrid(boolean binomHybrid);
 414
 415
 416    /**
 417     * @see  #getCombinationAuthorship()
 418     */
 419    public void setCombinationAuthorship(TeamOrPersonBase<?> combinationAuthorship);
 420
 421    /**
 422     * @see  #getExBasionymAuthorship()
 423     */
 424    public void setExBasionymAuthorship(TeamOrPersonBase<?> exBasionymAuthorship);
 425
 426
 427    /**
 428     * @see  #getExCombinationAuthorship()
 429     */
 430    public void setExCombinationAuthorship(TeamOrPersonBase<?> exCombinationAuthorship);
 431
 432    /**
 433     * @see  #getGenusOrUninomial()
 434     */
 435    public void setGenusOrUninomial(String genusOrUninomial);
 436
 437    /**
 438     * @see  #isHybridFormula()
 439     */
 440    public void setHybridFormula(boolean hybridFormula);
 441
 442    /**
 443     * @see  #getInfraGenericEpithet()
 444     */
 445    public void setInfraGenericEpithet(String infraGenericEpithet);
 446
 447    /**
 448     * @see  #getInfraSpecificEpithet()
 449     */
 450    public void setInfraSpecificEpithet(String infraSpecificEpithet);
 451
 452    /**
 453     * @see  #isMonomHybrid()
 454     * @see  #isBinomHybrid()
 455     * @see  #isTrinomHybrid()
 456     */
 457    public void setMonomHybrid(boolean monomHybrid);
 458
 459    /**
 460     * Assigns a nameCache string to <i>this</i> non viral taxon name and protects it from being overwritten.
 461     * Sets the protectedNameCache flag to <code>true</code>.
 462     *
 463     * @param  nameCache  the string which identifies <i>this</i> non viral taxon name (without authors or year)
 464     * @see    #getNameCache()
 465     */
 466    public void setNameCache(String nameCache);
 467
 468    /**
 469     * Assigns a nameCache string to <i>this</i> non viral taxon name and protects it from being overwritten.
 470     * Sets the protectedNameCache flag to <code>true</code>.
 471     *
 472     * @param  nameCache  the string which identifies <i>this</i> non viral taxon name (without authors or year)
 473     * @param  protectedNameCache if true teh protectedNameCache is set to <code>true</code> or otherwise set to
 474     * <code>false</code>
 475     * @see    #getNameCache()
 476     */
 477    public void setNameCache(String nameCache, boolean protectedNameCache);
 478
 479    /**
 480     * @see     #isProtectedAuthorshipCache()
 481     * @see     #getAuthorshipCache()
 482     */
 483    public void setProtectedAuthorshipCache(boolean protectedAuthorshipCache);
 484
 485    /**
 486     * @see     #isProtectedNameCache()
 487     */
 488    public void setProtectedNameCache(boolean protectedNameCache);
 489
 490    /**
 491     * @see  #getSpecificEpithet()
 492     */
 493    public void setSpecificEpithet(String specificEpithet);
 494
 495    /**
 496     * @see  #isTrinomHybrid()
 497     * @see  #isBinomHybrid()
 498     * @see  #isMonomHybrid()
 499     */
 500    public void setTrinomHybrid(boolean trinomHybrid);
 501
 502
 503 }