Project

General

Profile

Download (21.7 KB) Statistics
| Branch: | Tag: | Revision:
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
 * @since 21.01.2017
21
 *
22
 */
23
public interface INonViralName extends ITaxonNameBase{
24

    
25
    /**
26
     * Creates a new {@link HybridRelationship#HybridRelationship(TaxonName, TaxonName, 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(TaxonName, HybridRelationshipType,String )
37
     * @see                   #getRelationsToThisName()
38
     * @see                   #getNameRelations()
39
     * @see                   #addRelationshipFromName(TaxonName, NameRelationshipType, String)
40
     * @see                   #addNameRelationship(NameRelationship)
41
     */
42
    public HybridRelationship addHybridChild(INonViralName childName, HybridRelationshipType type, String ruleConsidered);
43

    
44
    /**
45
     * Creates a new {@link HybridRelationship#HybridRelationship(TaxonName, TaxonName, 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(TaxonName, HybridRelationshipType,String )
56
     * @see                   #getRelationsToThisName()
57
     * @see                   #getNameRelations()
58
     * @see                   #addRelationshipFromName(TaxonName, NameRelationshipType, String)
59
     * @see                   #addNameRelationship(NameRelationship)
60
     */
61
    public HybridRelationship addHybridParent(INonViralName 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
    * @see     #isHybridName()
304
    * @see     #isHybrid()
305
   */
306
   public boolean isHybridFormula();
307

    
308
   /**
309
    * Returns the boolean value of the flag indicating whether <i>this</i> botanical
310
    * taxon name is the name of an intergeneric hybrid (true) or not (false).
311
    * In this case the multiplication sign is placed before the scientific
312
    * name. If this flag is set no other hybrid flags may be set.
313
    *
314
    * @return  the boolean value of the isMonomHybrid flag
315
    * @see     #isHybridFormula()
316
    * @see     #isBinomHybrid()
317
    * @see     #isTrinomHybrid()
318
    * @see     #isHybridName()
319
    * @see     #isHybrid()
320
    */
321
   public boolean isMonomHybrid();
322

    
323
   /**
324
    * Returns the boolean value of the flag indicating whether <i>this</i> botanical
325
    * taxon name is the name of an interspecific hybrid (true) or not (false).
326
    * In this case the multiplication sign is placed before the species
327
    * epithet. If this flag is set no other hybrid flags may be set.
328
    *
329
    * @return  the boolean value of the isBinomHybrid flag
330
    * @see     #isHybridFormula()
331
    * @see     #isMonomHybrid()
332
    * @see     #isTrinomHybrid()
333
    * @see     #isHybridName()
334
    * @see     #isHybrid()
335
    */
336
   public boolean isBinomHybrid();
337

    
338
   /**
339
    * Returns the boolean value of the flag indicating whether <i>this</i> botanical
340
    * taxon name is the name of an infraspecific hybrid (true) or not (false).
341
    * In this case the term "notho-" (optionally abbreviated "n-") is used as
342
    * a prefix to the term denoting the infraspecific rank of <i>this</i> botanical
343
    * taxon name. If this flag is set no other hybrid flags may be set.
344
    *
345
    * @return  the boolean value of the isTrinomHybrid flag
346
    * @see     #isHybridFormula()
347
    * @see     #isMonomHybrid()
348
    * @see     #isBinomHybrid()
349
    * @see     #isHybridName()
350
    * @see     #isHybrid()
351
    */
352
   public boolean isTrinomHybrid();
353

    
354
   /**
355
     * Computes if this name is a hybrid name. <code>true</code> if any of the monon, binom or trinom
356
     * hybrid flags is set. <code>false</code> if neither of these flags is set.
357
     * Note: usually <code>false</code> if the hybrid formula flag is set as a name is
358
     * either a hybrid name or a hybrid formula or none of them, but never both.
359
     *
360
     * @return the boolean value indicating if this is a hybrid name
361
     * @see     #isHybridFormula()
362
     * @see     #isMonomHybrid()
363
     * @see     #isBinomHybrid()
364
     * @see     #isTrinomHybrid()
365
     * @see     #isHybrid()
366
     */
367
   @Transient
368
   @java.beans.Transient
369
   public boolean isHybridName();
370

    
371
   /**
372
    * Computes if this name is a hybrid (hybrid name or hybrid formula). <code>true</code> if any of the monon, binom, trinom
373
    * hybrid flags or the hybrid formula flag is set. <code>false</code> otherwise.
374
    *
375
    * @return the boolean value indicating if this is a hybrid
376
    * @see     #isHybridFormula()
377
    * @see     #isMonomHybrid()
378
    * @see     #isBinomHybrid()
379
    * @see     #isTrinomHybrid()
380
    * @see     #isHybridName()
381
    */
382
  @Transient
383
  @java.beans.Transient
384
  public boolean isHybrid();
385

    
386

    
387
   /**
388
    * Returns the boolean value of the flag intended to protect (true)
389
    * or not (false) the {@link #getAuthorshipCache() authorshipCache} (complete authorship string)
390
    * of <i>this</i> non viral taxon name.
391
    *
392
    * @return  the boolean value of the protectedAuthorshipCache flag
393
    * @see     #getAuthorshipCache()
394
    */
395
   public boolean isProtectedAuthorshipCache();
396

    
397

    
398
   /**
399
    * Returns the boolean value of the flag intended to protect (true)
400
    * or not (false) the {@link #getNameCache() nameCache} (scientific name without author strings and year)
401
    * string of <i>this</i> non viral taxon name.
402
    *
403
    * @return  the boolean value of the protectedNameCache flag
404
    * @see     #getNameCache()
405
    */
406
   public boolean isProtectedNameCache();
407

    
408
   public void removeHybridChild(INonViralName child);
409

    
410
   public void removeHybridParent(INonViralName parent);
411

    
412
   /**
413
    * Removes one {@link HybridRelationship hybrid relationship} from the set of
414
    * {@link #getHybridRelationships() hybrid relationships} in which <i>this</i> botanical taxon name
415
    * is involved. The hybrid relationship will also be removed from the set
416
    * belonging to the second botanical taxon name involved.
417
    *
418
    * @param  relationship  the hybrid relationship which should be deleted from the corresponding sets
419
    * @see                  #getHybridRelationships()
420
    */
421
   public void removeHybridRelationship(HybridRelationship hybridRelation);
422

    
423
   /**
424
    * Assigns an authorshipCache string to <i>this</i> non viral taxon name. Sets the isProtectedAuthorshipCache
425
    * flag to <code>true</code>.
426
    *
427
    * @param  authorshipCache  the string which identifies the complete authorship of <i>this</i> non viral taxon name
428
    * @see    #getAuthorshipCache()
429
    */
430
   public void setAuthorshipCache(String authorshipCache);
431

    
432

    
433
   /**
434
    * Assigns an authorshipCache string to <i>this</i> non viral taxon name.
435
    *
436
    * @param  authorshipCache  the string which identifies the complete authorship of <i>this</i> non viral taxon name
437
    * @param  protectedAuthorshipCache if true the isProtectedAuthorshipCache flag is set to <code>true</code>, otherwise
438
    * the flag is set to <code>false</code>.
439
    * @see    #getAuthorshipCache()
440
    */
441
   public void setAuthorshipCache(String authorshipCache, boolean protectedAuthorshipCache);
442

    
443
   /**
444
    * @see  #getBasionymAuthorship()
445
    */
446
   public void setBasionymAuthorship(TeamOrPersonBase<?> basionymAuthorship);
447

    
448
   /**
449
    * @see  #isBinomHybrid()
450
    * @see  #isMonomHybrid()
451
    * @see  #isTrinomHybrid()
452
    */
453
   public void setBinomHybrid(boolean binomHybrid);
454

    
455

    
456
   /**
457
    * @see  #getCombinationAuthorship()
458
    */
459
   public void setCombinationAuthorship(TeamOrPersonBase<?> combinationAuthorship);
460

    
461
   /**
462
    * @see  #getExBasionymAuthorship()
463
    */
464
   public void setExBasionymAuthorship(TeamOrPersonBase<?> exBasionymAuthorship);
465

    
466

    
467
   /**
468
    * @see  #getExCombinationAuthorship()
469
    */
470
   public void setExCombinationAuthorship(TeamOrPersonBase<?> exCombinationAuthorship);
471

    
472
   /**
473
    * @see  #getGenusOrUninomial()
474
    */
475
   public void setGenusOrUninomial(String genusOrUninomial);
476

    
477
   /**
478
    * @see  #isHybridFormula()
479
    */
480
   public void setHybridFormula(boolean hybridFormula);
481

    
482
   /**
483
    * @see  #getInfraGenericEpithet()
484
    */
485
   public void setInfraGenericEpithet(String infraGenericEpithet);
486

    
487
   /**
488
    * @see  #getInfraSpecificEpithet()
489
    */
490
   public void setInfraSpecificEpithet(String infraSpecificEpithet);
491

    
492
   /**
493
    * @see  #isMonomHybrid()
494
    * @see  #isBinomHybrid()
495
    * @see  #isTrinomHybrid()
496
    */
497
   public void setMonomHybrid(boolean monomHybrid);
498

    
499
   /**
500
    * Assigns a nameCache string to <i>this</i> non viral taxon name and protects it from being overwritten.
501
    * Sets the protectedNameCache flag to <code>true</code>.
502
    *
503
    * @param  nameCache  the string which identifies <i>this</i> non viral taxon name (without authors or year)
504
    * @see    #getNameCache()
505
    */
506
   public void setNameCache(String nameCache);
507

    
508
   /**
509
    * Assigns a nameCache string to <i>this</i> non viral taxon name and protects it from being overwritten.
510
    * Sets the protectedNameCache flag to <code>true</code>.
511
    *
512
    * @param  nameCache  the string which identifies <i>this</i> non viral taxon name (without authors or year)
513
    * @param  protectedNameCache if true teh protectedNameCache is set to <code>true</code> or otherwise set to
514
    * <code>false</code>
515
    * @see    #getNameCache()
516
    */
517
   public void setNameCache(String nameCache, boolean protectedNameCache);
518

    
519
   /**
520
    * @see     #isProtectedAuthorshipCache()
521
    * @see     #getAuthorshipCache()
522
    */
523
   public void setProtectedAuthorshipCache(boolean protectedAuthorshipCache);
524

    
525
   /**
526
    * @see     #isProtectedNameCache()
527
    */
528
   public void setProtectedNameCache(boolean protectedNameCache);
529

    
530
   /**
531
    * @see  #getSpecificEpithet()
532
    */
533
   public void setSpecificEpithet(String specificEpithet);
534

    
535
   /**
536
    * @see  #isTrinomHybrid()
537
    * @see  #isBinomHybrid()
538
    * @see  #isMonomHybrid()
539
    */
540
   public void setTrinomHybrid(boolean trinomHybrid);
541
}
(10-10/36)