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.common.IIdentifiableEntity;
|
17
|
import eu.etaxonomy.cdm.model.common.IParsable;
|
18
|
import eu.etaxonomy.cdm.model.common.IRelated;
|
19
|
import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
|
20
|
import eu.etaxonomy.cdm.model.description.DescriptionElementSource;
|
21
|
import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
|
22
|
import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;
|
23
|
import eu.etaxonomy.cdm.model.reference.INomenclaturalReference;
|
24
|
import eu.etaxonomy.cdm.model.reference.Reference;
|
25
|
import eu.etaxonomy.cdm.model.taxon.Synonym;
|
26
|
import eu.etaxonomy.cdm.model.taxon.Taxon;
|
27
|
import eu.etaxonomy.cdm.model.taxon.TaxonBase;
|
28
|
import eu.etaxonomy.cdm.model.taxon.TaxonComparator;
|
29
|
import eu.etaxonomy.cdm.strategy.cache.TaggedText;
|
30
|
import eu.etaxonomy.cdm.strategy.match.IMatchable;
|
31
|
|
32
|
/**
|
33
|
*
|
34
|
* The upmost interface for taxon names.
|
35
|
* <P>
|
36
|
* This class corresponds partially to: <ul>
|
37
|
* <li> TaxonName according to the TDWG ontology
|
38
|
* <li> ScientificName and CanonicalName according to the TCS
|
39
|
* <li> ScientificName according to the ABCD schema
|
40
|
* </ul>
|
41
|
*
|
42
|
* ITaxonNameBase and it's extensions should only be used for type safety
|
43
|
* of {@link TaxonName} instances. It should not be used to interface
|
44
|
* instances of any other class
|
45
|
*
|
46
|
* @author a.mueller
|
47
|
* @since 21.01.2017
|
48
|
*
|
49
|
*/
|
50
|
public interface ITaxonNameBase
|
51
|
extends IIdentifiableEntity, IParsable, IRelated, IMatchable, Cloneable{
|
52
|
|
53
|
|
54
|
public NomenclaturalCode getNameType();
|
55
|
public void setNameType(NomenclaturalCode nameType);
|
56
|
|
57
|
public Object clone();
|
58
|
|
59
|
public String generateFullTitle();
|
60
|
|
61
|
@Transient
|
62
|
public String getFullTitleCache();
|
63
|
|
64
|
@Transient
|
65
|
public NomenclaturalCode getNomenclaturalCode();
|
66
|
|
67
|
public List<TaggedText> getTaggedName();
|
68
|
|
69
|
public void setFullTitleCache(String fullTitleCache);
|
70
|
|
71
|
public void setFullTitleCache(String fullTitleCache, boolean protectCache);
|
72
|
|
73
|
public boolean isProtectedFullTitleCache();
|
74
|
|
75
|
void setProtectedFullTitleCache(boolean protectedFullTitleCache);
|
76
|
|
77
|
/**
|
78
|
* Returns the set of all {@link NameRelationship name relationships}
|
79
|
* in which <i>this</i> taxon name is involved. A taxon name can be both source
|
80
|
* in some name relationships or target in some others.
|
81
|
*
|
82
|
* @see #getRelationsToThisName()
|
83
|
* @see #getRelationsFromThisName()
|
84
|
* @see #addNameRelationship(NameRelationship)
|
85
|
* @see #addRelationshipToName(TaxonName, NameRelationshipType, String)
|
86
|
* @see #addRelationshipFromName(TaxonName, NameRelationshipType, String)
|
87
|
*/
|
88
|
public Set<NameRelationship> getNameRelations();
|
89
|
|
90
|
/**
|
91
|
* Creates a new {@link NameRelationship#NameRelationship(TaxonName, TaxonName, NameRelationshipType, String) name relationship} from <i>this</i> taxon name to another taxon name
|
92
|
* and adds it both to the set of {@link #getRelationsFromThisName() relations from <i>this</i> taxon name} and
|
93
|
* to the set of {@link #getRelationsToThisName() relations to the other taxon name}.
|
94
|
*
|
95
|
* @param toName the taxon name of the target for this new name relationship
|
96
|
* @param type the type of this new name relationship
|
97
|
* @param ruleConsidered the string which specifies the rule on which this name relationship is based
|
98
|
* @return
|
99
|
* @see #getRelationsToThisName()
|
100
|
* @see #getNameRelations()
|
101
|
* @see #addRelationshipFromName(TaxonName, NameRelationshipType, String)
|
102
|
* @see #addNameRelationship(NameRelationship)
|
103
|
*/
|
104
|
public NameRelationship addRelationshipToName(TaxonName toName, NameRelationshipType type, String ruleConsidered);
|
105
|
|
106
|
/**
|
107
|
* Creates a new {@link NameRelationship#NameRelationship(TaxonName, TaxonName, NameRelationshipType, String) name relationship} from <i>this</i> taxon name to another taxon name
|
108
|
* and adds it both to the set of {@link #getRelationsFromThisName() relations from <i>this</i> taxon name} and
|
109
|
* to the set of {@link #getRelationsToThisName() relations to the other taxon name}.
|
110
|
*
|
111
|
* @param toName the taxon name of the target for this new name relationship
|
112
|
* @param type the type of this new name relationship
|
113
|
* @param ruleConsidered the string which specifies the rule on which this name relationship is based
|
114
|
* @return
|
115
|
* @see #getRelationsToThisName()
|
116
|
* @see #getNameRelations()
|
117
|
* @see #addRelationshipFromName(TaxonName, NameRelationshipType, String)
|
118
|
* @see #addNameRelationship(NameRelationship)
|
119
|
*/
|
120
|
public NameRelationship addRelationshipToName(TaxonName toName, NameRelationshipType type, Reference citation,
|
121
|
String microCitation, String ruleConsidered);
|
122
|
|
123
|
/**
|
124
|
* Creates a new {@link NameRelationship#NameRelationship(TaxonName, TaxonName, NameRelationshipType, String) name relationship} from another taxon name to <i>this</i> taxon name
|
125
|
* and adds it both to the set of {@link #getRelationsToThisName() relations to <i>this</i> taxon name} and
|
126
|
* to the set of {@link #getRelationsFromThisName() relations from the other taxon name}.
|
127
|
*
|
128
|
* @param fromName the taxon name of the source for this new name relationship
|
129
|
* @param type the type of this new name relationship
|
130
|
* @param ruleConsidered the string which specifies the rule on which this name relationship is based
|
131
|
* @param citation the reference in which this relation was described
|
132
|
* @param microCitation the reference detail for this relation (e.g. page)
|
133
|
* @see #getRelationsFromThisName()
|
134
|
* @see #getNameRelations()
|
135
|
* @see #addRelationshipToName(TaxonName, NameRelationshipType, String)
|
136
|
* @see #addNameRelationship(NameRelationship)
|
137
|
*/
|
138
|
public NameRelationship addRelationshipFromName(TaxonName fromName, NameRelationshipType type, String ruleConsidered);
|
139
|
|
140
|
/**
|
141
|
* Creates a new {@link NameRelationship#NameRelationship(TaxonName, TaxonName, NameRelationshipType, String) name relationship} from another taxon name to <i>this</i> taxon name
|
142
|
* and adds it both to the set of {@link #getRelationsToThisName() relations to <i>this</i> taxon name} and
|
143
|
* to the set of {@link #getRelationsFromThisName() relations from the other taxon name}.
|
144
|
*
|
145
|
* @param fromName the taxon name of the source for this new name relationship
|
146
|
* @param type the type of this new name relationship
|
147
|
* @param ruleConsidered the string which specifies the rule on which this name relationship is based
|
148
|
* @param citation the reference in which this relation was described
|
149
|
* @param microCitation the reference detail for this relation (e.g. page)
|
150
|
* @see #getRelationsFromThisName()
|
151
|
* @see #getNameRelations()
|
152
|
* @see #addRelationshipToName(TaxonName, NameRelationshipType, String)
|
153
|
* @see #addNameRelationship(NameRelationship)
|
154
|
*/
|
155
|
public NameRelationship addRelationshipFromName(TaxonName fromName, NameRelationshipType type, Reference citation,
|
156
|
String microCitation, String ruleConsidered);
|
157
|
|
158
|
/**
|
159
|
* Removes one {@link NameRelationship name relationship} from one of both sets of
|
160
|
* {@link #getNameRelations() name relationships} in which <i>this</i> taxon name is involved.
|
161
|
* The name relationship will also be removed from one of both sets belonging
|
162
|
* to the second taxon name involved. Furthermore the fromName and toName
|
163
|
* attributes of the name relationship object will be nullified.
|
164
|
*
|
165
|
* @param nameRelation the name relationship which should be deleted from one of both sets
|
166
|
* @see #getNameRelations()
|
167
|
*/
|
168
|
public void removeNameRelationship(NameRelationship nameRelation);
|
169
|
|
170
|
public void removeRelationToTaxonName(TaxonName toTaxonName);
|
171
|
|
172
|
/**
|
173
|
* Returns the set of all {@link NameRelationship name relationships}
|
174
|
* in which <i>this</i> taxon name is involved as a source ("from"-side).
|
175
|
*
|
176
|
* @see #getNameRelations()
|
177
|
* @see #getRelationsToThisName()
|
178
|
* @see #addRelationshipFromName(TaxonName, NameRelationshipType, String)
|
179
|
*/
|
180
|
public Set<NameRelationship> getRelationsFromThisName();
|
181
|
|
182
|
/**
|
183
|
* Returns the set of all {@link NameRelationship name relationships}
|
184
|
* in which <i>this</i> taxon name is involved as a target ("to"-side).
|
185
|
*
|
186
|
* @see #getNameRelations()
|
187
|
* @see #getRelationsFromThisName()
|
188
|
* @see #addRelationshipToName(TaxonName, NameRelationshipType, String)
|
189
|
*/
|
190
|
public Set<NameRelationship> getRelationsToThisName();
|
191
|
|
192
|
/**
|
193
|
* Returns the set of {@link NomenclaturalStatus nomenclatural status} assigned
|
194
|
* to <i>this</i> taxon name according to its corresponding nomenclature code.
|
195
|
* This includes the {@link NomenclaturalStatusType type} of the nomenclatural status
|
196
|
* and the nomenclatural code rule considered.
|
197
|
*
|
198
|
* @see NomenclaturalStatus
|
199
|
* @see NomenclaturalStatusType
|
200
|
*/
|
201
|
public Set<NomenclaturalStatus> getStatus();
|
202
|
|
203
|
/**
|
204
|
* Adds a new {@link NomenclaturalStatus nomenclatural status}
|
205
|
* to <i>this</i> taxon name's set of nomenclatural status.
|
206
|
*
|
207
|
* @param nomStatus the nomenclatural status to be added
|
208
|
* @see #getStatus()
|
209
|
*/
|
210
|
public void addStatus(NomenclaturalStatus nomStatus);
|
211
|
|
212
|
public NomenclaturalStatus addStatus(NomenclaturalStatusType statusType, Reference citation, String microCitation);
|
213
|
|
214
|
/**
|
215
|
* Removes one element from the set of nomenclatural status of <i>this</i> taxon name.
|
216
|
* Type and ruleConsidered attributes of the nomenclatural status object
|
217
|
* will be nullified.
|
218
|
*
|
219
|
* @param nomStatus the nomenclatural status of <i>this</i> taxon name which should be deleted
|
220
|
* @see #getStatus()
|
221
|
*/
|
222
|
public void removeStatus(NomenclaturalStatus nomStatus);
|
223
|
|
224
|
/**
|
225
|
* Indicates whether <i>this</i> taxon name is a {@link NameRelationshipType#BASIONYM() basionym}
|
226
|
* or a {@link NameRelationshipType#REPLACED_SYNONYM() replaced synonym}
|
227
|
* of any other taxon name. Returns "true", if a basionym or a replaced
|
228
|
* synonym {@link NameRelationship relationship} from <i>this</i> taxon name to another taxon name exists,
|
229
|
* false otherwise (also in case <i>this</i> taxon name is the only one in the
|
230
|
* homotypical group).
|
231
|
*/
|
232
|
public boolean isOriginalCombination();
|
233
|
|
234
|
/**
|
235
|
* Indicates <i>this</i> taxon name is a {@link NameRelationshipType#REPLACED_SYNONYM() replaced synonym}
|
236
|
* of any other taxon name. Returns "true", if a replaced
|
237
|
* synonym {@link NameRelationship relationship} from <i>this</i> taxon name to another taxon name exists,
|
238
|
* false otherwise (also in case <i>this</i> taxon name is the only one in the
|
239
|
* homotypical group).
|
240
|
*/
|
241
|
public boolean isReplacedSynonym();
|
242
|
|
243
|
/**
|
244
|
* Returns the taxon name which is the {@link NameRelationshipType#BASIONYM() basionym} of <i>this</i> taxon name.
|
245
|
* The basionym of a taxon name is its epithet-bringing synonym.
|
246
|
* For instance <i>Pinus abies</i> L. was published by Linnaeus and the botanist
|
247
|
* Karsten transferred later <i>this</i> taxon to the genus Picea. Therefore,
|
248
|
* <i>Pinus abies</i> L. is the basionym of the new combination <i>Picea abies</i> (L.) H. Karst.
|
249
|
*
|
250
|
* If more than one basionym exists one is choosen at radom.
|
251
|
*
|
252
|
* If no basionym exists null is returned.
|
253
|
*/
|
254
|
public TaxonName getBasionym();
|
255
|
|
256
|
/**
|
257
|
* Returns the set of taxon names which are the {@link NameRelationshipType#BASIONYM() basionyms} of <i>this</i> taxon name.
|
258
|
* The basionym of a taxon name is its epithet-bringing synonym.
|
259
|
* For instance <i>Pinus abies</i> L. was published by Linnaeus and the botanist
|
260
|
* Karsten transferred later <i>this</i> taxon to the genus Picea. Therefore,
|
261
|
* <i>Pinus abies</i> L. is the basionym of the new combination <i>Picea abies</i> (L.) H. Karst.
|
262
|
*/
|
263
|
public Set<TaxonName> getBasionyms();
|
264
|
|
265
|
/**
|
266
|
* Assigns a taxon name as {@link NameRelationshipType#BASIONYM() basionym} of <i>this</i> taxon name.
|
267
|
* The basionym {@link NameRelationship relationship} will be added to <i>this</i> taxon name
|
268
|
* and to the basionym. The basionym cannot have itself a basionym.
|
269
|
* The {@link HomotypicalGroup homotypical groups} of <i>this</i> taxon name and of the basionym
|
270
|
* will be {@link HomotypicalGroup#merge(HomotypicalGroup) merged}.
|
271
|
*
|
272
|
* @param basionym the taxon name to be set as the basionym of <i>this</i> taxon name
|
273
|
* @see #getBasionym()
|
274
|
* @see #addBasionym(TaxonName, String)
|
275
|
*/
|
276
|
public void addBasionym(TaxonName basionym);
|
277
|
|
278
|
/**
|
279
|
* Assigns a taxon name as {@link NameRelationshipType#BASIONYM() basionym} of <i>this</i> taxon name
|
280
|
* and keeps the nomenclatural rule considered for it. The basionym
|
281
|
* {@link NameRelationship relationship} will be added to <i>this</i> taxon name and to the basionym.
|
282
|
* The basionym cannot have itself a basionym.
|
283
|
* The {@link HomotypicalGroup homotypical groups} of <i>this</i> taxon name and of the basionym
|
284
|
* will be {@link HomotypicalGroup#merge(HomotypicalGroup) merged}.
|
285
|
*
|
286
|
* @param basionym the taxon name to be set as the basionym of <i>this</i> taxon name
|
287
|
* @param ruleConsidered the string identifying the nomenclatural rule
|
288
|
* @return
|
289
|
* @see #getBasionym()
|
290
|
* @see #addBasionym(TaxonName)
|
291
|
*/
|
292
|
public NameRelationship addBasionym(TaxonName basionym, Reference citation, String microcitation, String ruleConsidered);
|
293
|
|
294
|
/**
|
295
|
* Returns the set of taxon names which are the {@link NameRelationshipType#REPLACED_SYNONYM() replaced synonyms} of <i>this</i> taxon name.
|
296
|
*
|
297
|
*/
|
298
|
public Set<TaxonName> getReplacedSynonyms();
|
299
|
|
300
|
/**
|
301
|
* Assigns a taxon name as {@link NameRelationshipType#REPLACED_SYNONYM() replaced synonym} of <i>this</i> taxon name
|
302
|
* and keeps the nomenclatural rule considered for it. The replaced synonym
|
303
|
* {@link NameRelationship relationship} will be added to <i>this</i> taxon name and to the replaced synonym.
|
304
|
* The {@link HomotypicalGroup homotypical groups} of <i>this</i> taxon name and of the replaced synonym
|
305
|
* will be {@link HomotypicalGroup#merge(HomotypicalGroup) merged}.
|
306
|
*
|
307
|
* @param basionym the taxon name to be set as the basionym of <i>this</i> taxon name
|
308
|
* @param ruleConsidered the string identifying the nomenclatural rule
|
309
|
* @see #getBasionym()
|
310
|
* @see #addBasionym(TaxonName)
|
311
|
*/
|
312
|
//TODO: Check if true: The replaced synonym cannot have itself a replaced synonym (?).
|
313
|
public void addReplacedSynonym(TaxonName replacedSynonym, Reference citation, String microcitation, String ruleConsidered);
|
314
|
|
315
|
/**
|
316
|
* Removes the {@link NameRelationshipType#BASIONYM() basionym} {@link NameRelationship relationship} from the set of
|
317
|
* {@link #getRelationsToThisName() name relationships to} <i>this</i> taxon name. The same relationhip will be
|
318
|
* removed from the set of {@link #getRelationsFromThisName() name relationships from} the taxon name
|
319
|
* previously used as basionym.
|
320
|
*
|
321
|
* @see #getBasionym()
|
322
|
* @see #addBasionym(TaxonName)
|
323
|
*/
|
324
|
public void removeBasionyms();
|
325
|
|
326
|
/**
|
327
|
* Returns the taxonomic {@link Rank rank} of <i>this</i> taxon name.
|
328
|
*
|
329
|
* @see Rank
|
330
|
*/
|
331
|
public Rank getRank();
|
332
|
|
333
|
/**
|
334
|
* @see #getRank()
|
335
|
*/
|
336
|
public void setRank(Rank rank);
|
337
|
|
338
|
/**
|
339
|
* Returns the {@link eu.etaxonomy.cdm.model.reference.Reference nomenclatural reference} of <i>this</i> taxon name.
|
340
|
* The nomenclatural reference is here meant to be the one publication
|
341
|
* <i>this</i> taxon name was originally published in while fulfilling the formal
|
342
|
* requirements as specified by the corresponding {@link NomenclaturalCode nomenclatural code}.
|
343
|
*
|
344
|
* @see eu.etaxonomy.cdm.model.reference.Reference
|
345
|
* @see #getNomenclaturalSource()
|
346
|
*/
|
347
|
public Reference getNomenclaturalReference();
|
348
|
|
349
|
/**
|
350
|
* Assigns a {@link eu.etaxonomy.cdm.model.reference.INomenclaturalReference nomenclatural reference} to <i>this</i> taxon name.
|
351
|
* The corresponding {@link eu.etaxonomy.cdm.model.reference.Reference.isNomenclaturallyRelevant nomenclaturally relevant flag} will be set to true
|
352
|
* as it is obviously used for nomenclatural purposes.
|
353
|
*
|
354
|
* @see #getNomenclaturalReference()
|
355
|
*/
|
356
|
public void setNomenclaturalReference(Reference nomenclaturalReference);
|
357
|
|
358
|
/**
|
359
|
* Same as setNomenclaturalReferences, to also allow interfaces to be used.
|
360
|
* @see #setNomenclaturalReference(Reference)
|
361
|
* @param nomenclaturalReference
|
362
|
*/
|
363
|
public void setNomenclaturalReference(INomenclaturalReference nomenclaturalReference);
|
364
|
|
365
|
/**
|
366
|
* Returns the details string of the {@link #getNomenclaturalReference() nomenclatural reference} assigned
|
367
|
* to <i>this</i> taxon name. The details describe the exact localisation within
|
368
|
* the publication used as nomenclature reference. These are mostly
|
369
|
* (implicitly) pages but can also be figures or tables or any other
|
370
|
* element of a publication. A nomenclatural micro reference (details)
|
371
|
* requires the existence of a nomenclatural reference.
|
372
|
*
|
373
|
* @see #getNomenclaturalReference()
|
374
|
* @see #getNomenclaturalSource()
|
375
|
*/
|
376
|
public String getNomenclaturalMicroReference();
|
377
|
|
378
|
/**
|
379
|
* @see #getNomenclaturalMicroReference()
|
380
|
*/
|
381
|
public void setNomenclaturalMicroReference(String nomenclaturalMicroReference);
|
382
|
|
383
|
/**
|
384
|
* Sets the nomenclatural source which is a combination of the nomenclatural reference
|
385
|
* and the detail information (exact page, table, figure, ...) where to find this name
|
386
|
* for the first time.
|
387
|
*
|
388
|
* @see #getNomenclaturalReference()
|
389
|
* @see #getNomenclaturalMicroReference()
|
390
|
*/
|
391
|
public DescriptionElementSource getNomenclaturalSource();
|
392
|
|
393
|
/**
|
394
|
* Sets the nomenclatural source
|
395
|
* @param nomenclaturalSource
|
396
|
*/
|
397
|
public void setNomenclaturalSource(DescriptionElementSource nomenclaturalSource);
|
398
|
|
399
|
|
400
|
/**
|
401
|
* Returns the appended phrase string assigned to <i>this</i> taxon name.
|
402
|
* The appended phrase is a non-atomised addition to a name. It is
|
403
|
* not ruled by a nomenclatural code.
|
404
|
*/
|
405
|
public String getAppendedPhrase();
|
406
|
|
407
|
/**
|
408
|
* @see #getAppendedPhrase()
|
409
|
*/
|
410
|
public void setAppendedPhrase(String appendedPhrase);
|
411
|
|
412
|
|
413
|
/**
|
414
|
* @param warnings
|
415
|
*/
|
416
|
public void addParsingProblems(int problems);
|
417
|
|
418
|
/**
|
419
|
* Returns the set of {@link TypeDesignationBase type designations} assigned
|
420
|
* to <i>this</i> taxon name.
|
421
|
* @see NameTypeDesignation
|
422
|
* @see SpecimenTypeDesignation
|
423
|
*/
|
424
|
public Set<TypeDesignationBase> getTypeDesignations();
|
425
|
|
426
|
/**
|
427
|
* Removes one element from the set of {@link TypeDesignationBase type designations} assigned to
|
428
|
* <i>this</i> taxon name. The type designation itself will be nullified.
|
429
|
*
|
430
|
* @param typeDesignation the type designation which should be deleted
|
431
|
*/
|
432
|
public void removeTypeDesignation(TypeDesignationBase typeDesignation);
|
433
|
|
434
|
/**
|
435
|
* Returns the set of {@link SpecimenTypeDesignation specimen type designations} assigned
|
436
|
* to <i>this</i> taxon name. The {@link Rank rank} of <i>this</i> taxon name is generally
|
437
|
* "species" or below. The specimen type designations include all the
|
438
|
* specimens on which the typification of this name is based (which are
|
439
|
* exclusively used to typify taxon names belonging to the same
|
440
|
* {@link HomotypicalGroup homotypical group} to which <i>this</i> taxon name
|
441
|
* belongs) and eventually the status of these designations.
|
442
|
*
|
443
|
* @see SpecimenTypeDesignation
|
444
|
* @see NameTypeDesignation
|
445
|
* @see HomotypicalGroup
|
446
|
*/
|
447
|
public Set<SpecimenTypeDesignation> getSpecimenTypeDesignationsOfHomotypicalGroup();
|
448
|
|
449
|
/**
|
450
|
* Returns the set of {@link NameTypeDesignation name type designations} assigned
|
451
|
* to <i>this</i> taxon name the rank of which must be above "species".
|
452
|
* The name type designations include all the taxon names used to typify
|
453
|
* <i>this</i> taxon name and eventually the rejected or conserved status
|
454
|
* of these designations.
|
455
|
*
|
456
|
* @see NameTypeDesignation
|
457
|
* @see SpecimenTypeDesignation
|
458
|
*/
|
459
|
public Set<NameTypeDesignation> getNameTypeDesignations();
|
460
|
|
461
|
/**
|
462
|
* Creates and adds a new {@link NameTypeDesignation name type designation}
|
463
|
* to <i>this</i> taxon name's set of type designations.
|
464
|
*
|
465
|
* @param typeSpecies the taxon name to be used as type of <i>this</i> taxon name
|
466
|
* @param citation the reference for this new designation
|
467
|
* @param citationMicroReference the string with the details (generally pages) within the reference
|
468
|
* @param originalNameString the taxon name string used in the reference to assert this designation
|
469
|
* @param isRejectedType the boolean status for a rejected name type designation
|
470
|
* @param isConservedType the boolean status for a conserved name type designation
|
471
|
* @param isLectoType the boolean status for a lectotype name type designation
|
472
|
* @param isNotDesignated the boolean status for a name type designation without name type
|
473
|
* @param addToAllHomotypicNames the boolean indicating whether the name type designation should be
|
474
|
* added to all taxon names of the homotypical group this taxon name belongs to
|
475
|
* @return
|
476
|
* @see #getNameTypeDesignations()
|
477
|
* @see NameTypeDesignation
|
478
|
* @see TypeDesignationBase#isNotDesignated()
|
479
|
*/
|
480
|
public NameTypeDesignation addNameTypeDesignation(TaxonName typeSpecies, Reference citation,
|
481
|
String citationMicroReference, String originalNameString, NameTypeDesignationStatus status,
|
482
|
boolean isRejectedType, boolean isConservedType,
|
483
|
/*boolean isLectoType, */
|
484
|
boolean isNotDesignated, boolean addToAllHomotypicNames);
|
485
|
|
486
|
/**
|
487
|
* Creates and adds a new {@link NameTypeDesignation name type designation}
|
488
|
* to <i>this</i> taxon name's set of type designations.
|
489
|
*
|
490
|
* @param typeSpecies the taxon name to be used as type of <i>this</i> taxon name
|
491
|
* @param citation the reference for this new designation
|
492
|
* @param citationMicroReference the string with the details (generally pages) within the reference
|
493
|
* @param originalNameString the taxon name string used in the reference to assert this designation
|
494
|
* @param status the name type designation status
|
495
|
* @param addToAllHomotypicNames the boolean indicating whether the name type designation should be
|
496
|
* added to all taxon names of the homotypical group this taxon name belongs to
|
497
|
* @return
|
498
|
* @see #getNameTypeDesignations()
|
499
|
* @see NameTypeDesignation
|
500
|
* @see TypeDesignationBase#isNotDesignated()
|
501
|
*/
|
502
|
public NameTypeDesignation addNameTypeDesignation(TaxonName typeSpecies, Reference citation,
|
503
|
String citationMicroReference, String originalNameString, NameTypeDesignationStatus status,
|
504
|
boolean addToAllHomotypicNames);
|
505
|
|
506
|
/**
|
507
|
* Returns the set of {@link SpecimenTypeDesignation specimen type designations}
|
508
|
* that typify <i>this</i> taxon name.
|
509
|
*/
|
510
|
public Set<SpecimenTypeDesignation> getSpecimenTypeDesignations();
|
511
|
|
512
|
/**
|
513
|
* Creates and adds a new {@link SpecimenTypeDesignation specimen type designation}
|
514
|
* to <i>this</i> taxon name's set of type designations.
|
515
|
*
|
516
|
* @param typeSpecimen the specimen to be used as a type for <i>this</i> taxon name
|
517
|
* @param status the specimen type designation status
|
518
|
* @param citation the reference for this new specimen type designation
|
519
|
* @param citationMicroReference the string with the details (generally pages) within the reference
|
520
|
* @param originalNameString the taxon name used in the reference to assert this designation
|
521
|
* @param isNotDesignated the boolean status for a specimen type designation without specimen type
|
522
|
* @param addToAllHomotypicNames the boolean indicating whether the specimen type designation should be
|
523
|
* added to all taxon names of the homotypical group the typified
|
524
|
* taxon name belongs to
|
525
|
* @return
|
526
|
* @see #getSpecimenTypeDesignations()
|
527
|
* @see SpecimenTypeDesignationStatus
|
528
|
* @see SpecimenTypeDesignation
|
529
|
* @see TypeDesignationBase#isNotDesignated()
|
530
|
*/
|
531
|
public SpecimenTypeDesignation addSpecimenTypeDesignation(DerivedUnit typeSpecimen, SpecimenTypeDesignationStatus status,
|
532
|
Reference citation, String citationMicroReference, String originalNameString, boolean isNotDesignated,
|
533
|
boolean addToAllHomotypicNames);
|
534
|
|
535
|
/**
|
536
|
* Adds a {@link TypeDesignationBase type designation} to <code>this</code> taxon name's set of type designations
|
537
|
*
|
538
|
* @param typeDesignation the typeDesignation to be added to <code>this</code> taxon name
|
539
|
* @param addToAllNames the boolean indicating whether the type designation should be
|
540
|
* added to all taxon names of the homotypical group the typified
|
541
|
* taxon name belongs to
|
542
|
* @return true if the operation was succesful
|
543
|
*
|
544
|
* @throws IllegalArgumentException if the type designation already has typified names, an {@link IllegalArgumentException exception}
|
545
|
* is thrown. We do this to prevent a type designation to be used for multiple taxon names.
|
546
|
*
|
547
|
*/
|
548
|
public boolean addTypeDesignation(TypeDesignationBase typeDesignation, boolean addToAllNames);
|
549
|
|
550
|
/**
|
551
|
* Returns the {@link HomotypicalGroup homotypical group} to which
|
552
|
* <i>this</i> taxon name belongs. A homotypical group represents all taxon names
|
553
|
* that share the same types.
|
554
|
*
|
555
|
* @see HomotypicalGroup
|
556
|
*/
|
557
|
|
558
|
public HomotypicalGroup getHomotypicalGroup();
|
559
|
|
560
|
/**
|
561
|
* @see #getHomotypicalGroup()
|
562
|
*/
|
563
|
public void setHomotypicalGroup(HomotypicalGroup homotypicalGroup);
|
564
|
|
565
|
/**
|
566
|
* Returns the complete string containing the
|
567
|
* {@link eu.etaxonomy.cdm.model.reference.INomenclaturalReference#getNomenclaturalCitation() nomenclatural reference citation}
|
568
|
* and the {@link #getNomenclaturalMicroReference() details} assigned to <i>this</i> taxon name.
|
569
|
*
|
570
|
* @return the string containing the nomenclatural reference of <i>this</i> taxon name
|
571
|
* @see eu.etaxonomy.cdm.model.reference.INomenclaturalReference#getNomenclaturalCitation()
|
572
|
* @see #getNomenclaturalReference()
|
573
|
* @see #getNomenclaturalMicroReference()
|
574
|
*/
|
575
|
public String getCitationString();
|
576
|
|
577
|
/**
|
578
|
* Returns the string containing the publication date (generally only year)
|
579
|
* of the {@link #getNomenclaturalReference() nomenclatural reference} for <i>this</i> taxon name, null if there is
|
580
|
* no nomenclatural reference.
|
581
|
*
|
582
|
* @return the string containing the publication date of <i>this</i> taxon name
|
583
|
* @see eu.etaxonomy.cdm.model.reference.INomenclaturalReference#getYear()
|
584
|
*/
|
585
|
public String getReferenceYear();
|
586
|
|
587
|
/**
|
588
|
* Returns the set of {@link eu.etaxonomy.cdm.model.taxon.TaxonBase taxon bases} that refer to <i>this</i> taxon name.
|
589
|
* In this context a taxon base means the use of a taxon name by a reference
|
590
|
* either as a {@link eu.etaxonomy.cdm.model.taxon.Taxon taxon} ("accepted/correct" name) or
|
591
|
* as a (junior) {@link eu.etaxonomy.cdm.model.taxon.Synonym synonym}.
|
592
|
* A taxon name can be used by several distinct {@link eu.etaxonomy.cdm.model.reference.Reference references} but only once
|
593
|
* within a taxonomic treatment (identified by one reference).
|
594
|
*
|
595
|
* @see #getTaxa()
|
596
|
* @see #getSynonyms()
|
597
|
*/
|
598
|
public Set<TaxonBase> getTaxonBases();
|
599
|
|
600
|
/**
|
601
|
* Adds a new {@link eu.etaxonomy.cdm.model.taxon.TaxonBase taxon base}
|
602
|
* to the set of taxon bases using <i>this</i> taxon name.
|
603
|
*
|
604
|
* @param taxonBase the taxon base to be added
|
605
|
* @see #getTaxonBases()
|
606
|
* @see #removeTaxonBase(TaxonBase)
|
607
|
*/
|
608
|
//TODO protected
|
609
|
public void addTaxonBase(TaxonBase taxonBase);
|
610
|
|
611
|
/**
|
612
|
* Removes one element from the set of {@link eu.etaxonomy.cdm.model.taxon.TaxonBase taxon bases} that refer to <i>this</i> taxon name.
|
613
|
*
|
614
|
* @param taxonBase the taxon base which should be removed from the corresponding set
|
615
|
* @see #getTaxonBases()
|
616
|
* @see #addTaxonBase(TaxonBase)
|
617
|
*/
|
618
|
public void removeTaxonBase(TaxonBase taxonBase);
|
619
|
|
620
|
/**
|
621
|
* Returns the set of {@link eu.etaxonomy.cdm.model.taxon.Taxon taxa} ("accepted/correct" names according to any
|
622
|
* reference) that are based on <i>this</i> taxon name. This set is a subset of
|
623
|
* the set returned by getTaxonBases().
|
624
|
*
|
625
|
* @see eu.etaxonomy.cdm.model.taxon.Taxon
|
626
|
* @see #getTaxonBases()
|
627
|
* @see #getSynonyms()
|
628
|
*/
|
629
|
public Set<Taxon> getTaxa();
|
630
|
|
631
|
/**
|
632
|
* Returns the set of {@link eu.etaxonomy.cdm.model.taxon.Synonym (junior) synonyms} (according to any
|
633
|
* reference) that are based on <i>this</i> taxon name. This set is a subset of
|
634
|
* the set returned by getTaxonBases().
|
635
|
*
|
636
|
* @see eu.etaxonomy.cdm.model.taxon.Synonym
|
637
|
* @see #getTaxonBases()
|
638
|
* @see #getTaxa()
|
639
|
*/
|
640
|
public Set<Synonym> getSynonyms();
|
641
|
|
642
|
/**
|
643
|
* Returns the set of {@link eu.etaxonomy.cdm.model.description.TaxonNameDescription taxon name descriptions} assigned
|
644
|
* to <i>this</i> taxon name. A taxon name description is a piece of information
|
645
|
* concerning the taxon name like for instance the content of its first
|
646
|
* publication (protolog) or a picture of this publication.
|
647
|
*
|
648
|
* @see #addDescription(TaxonNameDescription)
|
649
|
* @see #removeDescription(TaxonNameDescription)
|
650
|
* @see eu.etaxonomy.cdm.model.description.TaxonNameDescription
|
651
|
*/
|
652
|
public Set<TaxonNameDescription> getDescriptions();
|
653
|
|
654
|
/**
|
655
|
* Adds a new {@link eu.etaxonomy.cdm.model.description.TaxonNameDescription taxon name description}
|
656
|
* to the set of taxon name descriptions assigned to <i>this</i> taxon name. The
|
657
|
* content of the {@link eu.etaxonomy.cdm.model.description.TaxonNameDescription#getTaxonName() taxonName attribute} of the
|
658
|
* taxon name description itself will be replaced with <i>this</i> taxon name.
|
659
|
*
|
660
|
* @param description the taxon name description to be added
|
661
|
* @see #getDescriptions()
|
662
|
* @see #removeDescription(TaxonNameDescription)
|
663
|
*/
|
664
|
public void addDescription(TaxonNameDescription description);
|
665
|
|
666
|
/**
|
667
|
* Removes one element from the set of {@link eu.etaxonomy.cdm.model.description.TaxonNameDescription taxon name descriptions} assigned
|
668
|
* to <i>this</i> taxon name. The content of the {@link eu.etaxonomy.cdm.model.description.TaxonNameDescription#getTaxonName() taxonName attribute}
|
669
|
* of the description itself will be set to "null".
|
670
|
*
|
671
|
* @param description the taxon name description which should be removed
|
672
|
* @see #getDescriptions()
|
673
|
* @see #addDescription(TaxonNameDescription)
|
674
|
* @see eu.etaxonomy.cdm.model.description.TaxonNameDescription#getTaxonName()
|
675
|
*/
|
676
|
public void removeDescription(TaxonNameDescription description);
|
677
|
|
678
|
public void mergeHomotypicGroups(TaxonName name);
|
679
|
|
680
|
/**
|
681
|
* Returns the boolean value indicating whether a given taxon name belongs
|
682
|
* to the same {@link HomotypicalGroup homotypical group} as <i>this</i> taxon name (true)
|
683
|
* or not (false). Returns "true" only if the homotypical groups of both
|
684
|
* taxon names exist and if they are identical.
|
685
|
*
|
686
|
* @param homoTypicName the taxon name the homotypical group of which is to be checked
|
687
|
* @return the boolean value of the check
|
688
|
* @see HomotypicalGroup
|
689
|
*/
|
690
|
public boolean isHomotypic(TaxonName homoTypicName);
|
691
|
|
692
|
/**
|
693
|
* Checks whether name is a basionym for ALL names
|
694
|
* in its homotypical group.
|
695
|
* Returns <code>false</code> if there are no other names in the group
|
696
|
* @param name
|
697
|
* @return
|
698
|
*/
|
699
|
public boolean isGroupsBasionym();
|
700
|
|
701
|
/**
|
702
|
* Checks whether a basionym relationship exists between fromName and toName.
|
703
|
*
|
704
|
* @param fromName
|
705
|
* @param toName
|
706
|
* @return
|
707
|
*/
|
708
|
public boolean isBasionymFor(TaxonName newCombinationName);
|
709
|
|
710
|
/**
|
711
|
* Creates a basionym relationship to all other names in this names homotypical
|
712
|
* group.
|
713
|
*
|
714
|
* @see HomotypicalGroup.setGroupBasionym(TaxonName basionymName)
|
715
|
*/
|
716
|
public void makeGroupsBasionym();
|
717
|
|
718
|
//********* Rank comparison shortcuts ********************//
|
719
|
/**
|
720
|
* Returns the boolean value indicating whether the taxonomic {@link Rank rank} of <i>this</i>
|
721
|
* taxon name is higher than the genus rank (true) or not (false).
|
722
|
* Suprageneric non viral names are monomials.
|
723
|
* Returns false if rank is null.
|
724
|
*
|
725
|
* @see #isGenus()
|
726
|
* @see #isInfraGeneric()
|
727
|
* @see #isSpecies()
|
728
|
* @see #isInfraSpecific()
|
729
|
* @see #isGenusOrSupraGeneric()
|
730
|
*/
|
731
|
public boolean isSupraGeneric();
|
732
|
|
733
|
/**
|
734
|
* Returns the boolean value indicating whether the taxonomic {@link Rank rank} of <i>this</i>
|
735
|
* taxon name is the genus rank (true) or not (false). Non viral names with
|
736
|
* genus rank are monomials. Returns false if rank is null.
|
737
|
*
|
738
|
* @see #isSupraGeneric()
|
739
|
* @see #isInfraGeneric()
|
740
|
* @see #isSpecies()
|
741
|
* @see #isInfraSpecific()
|
742
|
* @see #isGenusOrSupraGeneric()
|
743
|
*/
|
744
|
public boolean isGenus();
|
745
|
|
746
|
|
747
|
/**
|
748
|
* Returns the boolean value indicating whether the taxonomic {@link Rank rank} of <i>this</i>
|
749
|
* taxon name is the genus rank or higher (<code>true</code>) or not (<code>false</code>).
|
750
|
* Non viral names with
|
751
|
* genus rank or higher are monomials. Returns false if rank is null.<BR>
|
752
|
* This is a shortcut for {@link #isGenus()} || {@link #isSupraGeneric()}
|
753
|
*
|
754
|
* @see #isGenus()
|
755
|
* @see #isSupraGeneric()
|
756
|
* @see #isInfraGeneric()
|
757
|
* @see #isSpecies()
|
758
|
* @see #isInfraSpecific()
|
759
|
*/
|
760
|
boolean isGenusOrSupraGeneric();
|
761
|
|
762
|
/**
|
763
|
* Returns the boolean value indicating whether the taxonomic {@link Rank rank} of <i>this</i>
|
764
|
* taxon name is higher than the species rank and lower than the
|
765
|
* genus rank (true) or not (false). Infrageneric non viral names are
|
766
|
* binomials. Returns false if rank is null.
|
767
|
*
|
768
|
* @see #isSupraGeneric()
|
769
|
* @see #isGenus()
|
770
|
* @see #isSpecies()
|
771
|
* @see #isInfraSpecific()
|
772
|
*/
|
773
|
public boolean isInfraGeneric();
|
774
|
|
775
|
/**
|
776
|
* Returns the boolean value indicating whether the taxonomic {@link Rank rank} of <i>this</i>
|
777
|
* taxon name is higher than the species rank (true) or not (false).
|
778
|
* Returns false if rank is null.
|
779
|
*
|
780
|
* @see #isGenus()
|
781
|
* @see #isInfraGeneric()
|
782
|
* @see #isSpecies()
|
783
|
* @see #isInfraSpecific()
|
784
|
*/
|
785
|
public boolean isSupraSpecific();
|
786
|
|
787
|
/**
|
788
|
* Returns the boolean value indicating whether the taxonomic {@link Rank rank} of <i>this</i>
|
789
|
* taxon name is the species rank (true) or not (false). Non viral names
|
790
|
* with species rank are binomials.
|
791
|
* Returns false if rank is null.
|
792
|
*
|
793
|
* @see #isSupraGeneric()
|
794
|
* @see #isGenus()
|
795
|
* @see #isInfraGeneric()
|
796
|
* @see #isInfraSpecific()
|
797
|
*/
|
798
|
public boolean isSpecies();
|
799
|
|
800
|
/**
|
801
|
* Returns the boolean value indicating whether the taxonomic {@link Rank rank} of <i>this</i>
|
802
|
* taxon name is lower than the species rank (true) or not (false).
|
803
|
* Infraspecific non viral names are trinomials.
|
804
|
* Returns false if rank is null.
|
805
|
*
|
806
|
* @see #isSupraGeneric()
|
807
|
* @see #isGenus()
|
808
|
* @see #isInfraGeneric()
|
809
|
* @see #isSpecies()
|
810
|
*/
|
811
|
public boolean isInfraSpecific();
|
812
|
|
813
|
/**
|
814
|
* Returns true if this name's rank indicates a rank that aggregates species like species
|
815
|
* aggregates or species groups, false otherwise. This methods currently returns false
|
816
|
* for all user defined ranks.
|
817
|
*
|
818
|
*@see Rank#isSpeciesAggregate()
|
819
|
*
|
820
|
* @return
|
821
|
*/
|
822
|
public boolean isSpeciesAggregate();
|
823
|
|
824
|
/**
|
825
|
* Creates a basionym relationship between this name and
|
826
|
* each name in its homotypic group.
|
827
|
*
|
828
|
* @param basionymName
|
829
|
*/
|
830
|
public void setAsGroupsBasionym();
|
831
|
|
832
|
/**
|
833
|
* Removes basionym relationship between this name and
|
834
|
* each name in its homotypic group.
|
835
|
*
|
836
|
* @param basionymName
|
837
|
*/
|
838
|
public void removeAsGroupsBasionym();
|
839
|
|
840
|
/**
|
841
|
* This method compares 2 taxon names on it's name titles and caches.
|
842
|
* Maybe in future more parts will be added.
|
843
|
* It is not fully clear/defined how this method relates to
|
844
|
* explicit comparators like {@link TaxonNameComparator}.
|
845
|
* Historically it was a compareTo method in {@link IdentifiableEntity}
|
846
|
* but did not fulfill the {@link Comparable} contract.
|
847
|
* <BR><BR>
|
848
|
* {@link https://dev.e-taxonomy.eu/redmine/issues/922}<BR>
|
849
|
* {@link https://dev.e-taxonomy.eu/redmine/issues/6311}
|
850
|
*
|
851
|
* @see TaxonName#compareToName(TaxonName)
|
852
|
* @see TaxonNameComparator
|
853
|
* @see TaxonComparator
|
854
|
* @param otherTaxon
|
855
|
* @return the compareTo result similar to {@link Comparable#compareTo(Object)}
|
856
|
* @throws NullPointerException if otherTaxon is <code>null</code>
|
857
|
*/
|
858
|
public int compareToName(TaxonName otherName);
|
859
|
|
860
|
/**
|
861
|
* This method returns als {@link Registration registrations} for the given name.
|
862
|
* @return
|
863
|
*/
|
864
|
public Set<Registration> getRegistrations();
|
865
|
|
866
|
|
867
|
/**
|
868
|
* Returns <code>true</code> if this name is of type {@link NomenclaturalCode#ICZN} or
|
869
|
* any sub type and is supposed to be handled via {@link IZoologicalName}
|
870
|
*/
|
871
|
public boolean isZoological();
|
872
|
|
873
|
/**
|
874
|
* Returns <code>true</code> if this name is of type {@link NomenclaturalCode#NonViral} or
|
875
|
* any sub type and is supposed to be handled via {@link INonViralName}
|
876
|
*/
|
877
|
public boolean isNonViral();
|
878
|
|
879
|
/**
|
880
|
* Returns <code>true</code> if this name is of type {@link NomenclaturalCode#ICNAFP} or
|
881
|
* any sub type and is supposed to be handled via {@link IBotanicalName}
|
882
|
*/
|
883
|
public boolean isBotanical();
|
884
|
|
885
|
/**
|
886
|
* Returns <code>true</code> if this name is of type {@link NomenclaturalCode#ICNCP} or
|
887
|
* any sub type and is supposed to be handled via {@link ICultivarPlantName}
|
888
|
*/
|
889
|
boolean isCultivar();
|
890
|
|
891
|
/**
|
892
|
* Returns <code>true</code> if this name is of type {@link NomenclaturalCode#ICNB} or
|
893
|
* any sub type and is supposed to be handled via {@link IBacterialName}
|
894
|
*/
|
895
|
boolean isBacterial();
|
896
|
|
897
|
/**
|
898
|
* Returns <code>true</code> if this name is of type {@link NomenclaturalCode#ICVCN} or
|
899
|
* any sub type and is supposed to be handled via {@link IViralName}
|
900
|
*/
|
901
|
boolean isViral();
|
902
|
|
903
|
}
|