2 * Copyright (C) 2007 EDIT
3 * European Distributed Institute of Taxonomy
4 * http://www.e-taxonomy.eu
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.
10 package eu
.etaxonomy
.cdm
.model
.name
;
13 import java
.util
.HashMap
;
14 import java
.util
.List
;
16 import java
.util
.UUID
;
18 import javax
.persistence
.Entity
;
19 import javax
.persistence
.Transient
;
20 import javax
.xml
.bind
.annotation
.XmlAccessType
;
21 import javax
.xml
.bind
.annotation
.XmlAccessorType
;
22 import javax
.xml
.bind
.annotation
.XmlType
;
24 import org
.apache
.log4j
.Logger
;
25 import org
.hibernate
.envers
.Audited
;
26 import org
.hibernate
.search
.annotations
.Indexed
;
28 import eu
.etaxonomy
.cdm
.common
.CdmUtils
;
29 import eu
.etaxonomy
.cdm
.model
.common
.DefinedTermBase
;
30 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipTermBase
;
31 import eu
.etaxonomy
.cdm
.model
.common
.TermVocabulary
;
34 * The class representing the categories of {@link NameRelationship taxon name relationships} between
35 * two {@link TaxonNameBase taxon names}. These name relationship types are
36 * based on the concrete {@link NomenclaturalCode nomenclatural code} governing
37 * the taxon names involved in the name relationship or on decisions taken by
38 * the competent authorities; they do not depend on the use made of these
39 * taxon names in a particular reference or in a particular taxonomic treatment.
40 * Most relationships are to be understood as 'is .... of': for instance
41 * <i>Linum radiola</i> L. is a replaced synonym of <i>Radiola linoides</i> Roth or
42 * <i>Astragalus rhizanthus</i> Boiss. is a later homonym of
43 * <i>Astragalus rhizanthus</i> Royle.
45 * A standard (ordered) list of name relationship type instances will be
46 * automatically created as the project starts. But this class allows to extend
47 * this standard list by creating new instances of additional name relationship
50 * This class corresponds partially to: <ul>
51 * <li> TaxonRelationshipTerm and NomenclaturalNoteTypeTerm according to the TDWG ontology
52 * <li> RelationshipType and NomenclaturalNoteType according to the TCS
57 * @created 08-Nov-2007 13:06:38
59 @XmlAccessorType(XmlAccessType
.FIELD
)
60 @XmlType(name
= "NameRelationshipType")
62 @Indexed(index
= "eu.etaxonomy.cdm.model.common.DefinedTermBase")
64 public class NameRelationshipType
extends RelationshipTermBase
<NameRelationshipType
> {
65 static Logger logger
= Logger
.getLogger(NameRelationshipType
.class);
67 private static final UUID uuidOrthographicVariant
= UUID
.fromString("eeaea868-c4c1-497f-b9fe-52c9fc4aca53");
68 private static final UUID uuidMisspelling
= UUID
.fromString("c6f9afcb-8287-4a2b-a6f6-4da3a073d5de");
69 private static final UUID uuidEmendation
= UUID
.fromString("6e23ad45-3f2a-462b-ad87-d2389cd6e26c");
70 private static final UUID uuidLaterHomonym
= UUID
.fromString("80f06f65-58e0-4209-b811-cb40ad7220a6");
71 private static final UUID uuidTreatedAsLaterHomonym
= UUID
.fromString("2990a884-3302-4c8b-90b2-dfd31aaa2778");
72 private static final UUID uuidAlternativeName
= UUID
.fromString("049c6358-1094-4765-9fae-c9972a0e7780");
73 private static final UUID uuidBasionym
= UUID
.fromString("25792738-98de-4762-bac1-8c156faded4a");
74 private static final UUID uuidReplacedSynonym
= UUID
.fromString("71c67c38-d162-445b-b0c2-7aba56106696");
75 private static final UUID uuidConservedAgainst
= UUID
.fromString("e6439f95-bcac-4ebb-a8b5-69fa5ce79e6a");
76 private static final UUID uuidValidatedByName
= UUID
.fromString("a176c9ad-b4c2-4c57-addd-90373f8270eb");
77 private static final UUID uuidLaterValidatedByName
= UUID
.fromString("a25ee4c1-863a-4dab-9499-290bf9b89639");
78 private static final UUID uuidBlockingNameFor
= UUID
.fromString("1dab357f-2e12-4511-97a4-e5153589e6a6");
80 protected static Map
<UUID
, NameRelationshipType
> termMap
= null;
82 protected static NameRelationshipType
findTermByUuid(UUID uuid
){
86 return (NameRelationshipType
)termMap
.get(uuid
);
90 // ************* CONSTRUCTORS *************/
92 * Class constructor: creates a new empty name relationship type instance.
94 * @see #NameRelationshipType(String, String, String, boolean, boolean)
96 public NameRelationshipType() {
100 * Class constructor: creates an additional name relationship type
101 * instance with a description, a label, a label abbreviation and the flags
102 * indicating whether <i>this</i> new name relationship type is symmetric and/or
105 * @param term the string (in the default language) describing the
106 * new name relationship type to be created
107 * @param label the string identifying the new name relationship
109 * @param labelAbbrev the string identifying (in abbreviated form) the
110 * new name relationship type to be created
111 * @param symmetric the boolean indicating whether the new name
112 * relationship type to be created is symmetric
113 * @param transitive the boolean indicating whether the new name
114 * relationship type to be created is transitive
115 * @see #NameRelationshipType()
117 public NameRelationshipType(String term
, String label
, String labelAbbrev
, boolean symmetric
, boolean transitive
) {
118 super(term
, label
, labelAbbrev
, symmetric
, transitive
);
123 //************************** METHODS ********************************
126 * @see eu.etaxonomy.cdm.model.common.DefinedTermBase#resetTerms()
129 public void resetTerms(){
133 // TODO this method should be moved to consistency proof classes
135 * Returns the boolean value indicating whether the nomenclatural status
136 * type of the {@link eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom() first taxon name}
137 * involved in a name relationship with <i>this</i> name relationship type should
138 * be "invalid" (true) or not (false). Returns false if <i>this</i> name
139 * relationship status type is null.
141 * @see #isLegitimateType()
142 * @see #isIllegitimateType()
143 * @see NomenclaturalStatusType#isInvalidType()
144 * @see eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom()
147 public boolean isInvalidType(){
148 if (this.equals(VALIDATED_BY_NAME()) ||
149 this.equals(LATER_VALIDATED_BY_NAME())
157 // TODO this method should be moved to consistency proof classes
159 * Returns the boolean value indicating whether the nomenclatural status
160 * type of the {@link eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom() first taxon name}
161 * involved in a name relationship with <i>this</i> name relationship type should
162 * be "legitimate" (true) or not (false). Returns false if <i>this</i> name
163 * relationship status type is null.
165 * @see #isInvalidType()
166 * @see #isIllegitimateType()
167 * @see NomenclaturalStatusType#isLegitimateType()
168 * @see eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom()
171 public boolean isLegitimateType(){
172 if (this.equals(BASIONYM()) ||
173 this.equals(REPLACED_SYNONYM()) ||
174 this.equals(ALTERNATIVE_NAME()) ||
175 this.equals(CONSERVED_AGAINST())
183 // TODO this method should be moved to consistency proof classes
185 * Returns the boolean value indicating whether the nomenclatural status
186 * type of the {@link eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom() first taxon name}
187 * involved in a name relationship with <i>this</i> name relationship type should
188 * be "illegitimate" (true) or not (false). Returns false if <i>this</i> name
189 * relationship status type is null.
191 * @see #isInvalidType()
192 * @see #isLegitimateType()
193 * @see NomenclaturalStatusType#isIllegitimateType()
194 * @see eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom()
197 public boolean isIllegitimateType(){
198 //TODO: implement isX method. Maybe as persistent class attribute?
199 //TODO: RejectedInFavour,
200 if (this.equals(LATER_HOMONYM()) ||
201 this.equals(TREATED_AS_LATER_HOMONYM())
210 public boolean isBasionymRelation(){
211 if (BASIONYM() == null){
212 throw new IllegalStateException("NameRelationships have not been initialized yet. Please initialize DefinedTerms first");
214 return this.equals(BASIONYM());
218 public boolean isReplacedSynonymRelation(){
219 if (REPLACED_SYNONYM() == null){
220 throw new IllegalStateException("NameRelationships have not been initialized yet. Please initialize DefinedTerms first");
222 return this.equals(REPLACED_SYNONYM());
227 * Returns the "orthographic variant" name relationship type. The first
228 * {@link TaxonNameBase taxon name} involved in such a relationship is an
229 * orthographic variant of the second taxon name. The two {@link TaxonNameBase taxon names}
230 * involved in such a relationship must have the same {@link NonViralName#getAuthorshipCache() authorship}
231 * and {@link Rank rank}, belong to the same {@link HomotypicalGroup homotypical group} and their name parts
232 * must be almost identical (so one usually does not differentiate them).<BR>
233 * For instance <i>Angelica silvestris</i> L. is an orthographic variant of
234 * <i>Angelica sylvestris</i> L.<BR>
235 * This type is symmetric and transitive but usually orthographic variant relationships should be organized
236 * in a star schema with the correct variant in the middle and other variants pointing to it.
238 public static final NameRelationshipType
ORTHOGRAPHIC_VARIANT(){
239 return findTermByUuid(uuidOrthographicVariant
);
242 * Returns the "misspelling" name relationship type. The first
243 * {@link TaxonNameBase taxon name} involved in such a relationship is a
244 * misspelling of the second taxon name. The two {@link TaxonNameBase taxon names}
245 * involved in such a relationship must have the same {@link NonViralName#getAuthorshipCache() authorship}
246 * and {@link Rank rank}, belong to the same {@link HomotypicalGroup homotypical group} and their name parts
247 * must be almost identical (so one usually does not differentiate them).<BR>
248 * For instance <i>Anhelica silvestris</i> L. is a misspelling of
249 * <i>Angelica silvestris</i> L.<BR>
250 * A misspelling is always accicentally (not on purpose). Therefore misspellings are a
251 * subset of {@link #ORTHOGRAPHIC_VARIANT orthographic variants} and are complementary to
252 * emendations. A misspelling is always an {@link #ORTHOGRAPHIC_VARIANT orthographic variant}, too.
253 * This type is symmetric and transitive but usually the misspelling relationships should be organized
254 * in a star schema with the correct variant in the middle and the misspellings pointing to it.
256 public static final NameRelationshipType
MISSPELLING(){
257 return findTermByUuid(uuidMisspelling
);
260 * Returns the "emendation" name relationship type. The first
261 * {@link TaxonNameBase taxon name} involved in such a relationship is a
262 * misspelling of the second taxon name. The two {@link TaxonNameBase taxon names}
263 * involved in such a relationship must have the same {@link NonViralName#getAuthorshipCache() authorship}
264 * and {@link Rank rank}, belong to the same {@link HomotypicalGroup homotypical group} and their name parts
265 * must be almost identical (so one usually does not differentiate them).<BR>
266 * For instance <i>Angelica silvestris</i> L. is a emendation of
267 * <i>Angelica sylvestris</i> L.<BR>
268 * The name corrected by an emendation has originally been used on purpose (not accidentially)
269 * Therefore emendations are a subset of {@link #ORTHOGRAPHIC_VARIANT orthographic variants} and are
270 * complementary to {@link #MISSPELLING missepllings}. An emendation is always an
271 * {@link #ORTHOGRAPHIC_VARIANT orthographic variant}, too.<BR>
272 * This type is symmetric and transitive but usually the misspelling relationships should be organized
273 * in a star schema with the correct variant in the middle and the misspellings pointing to it.
275 public static final NameRelationshipType
EMENDATION(){
276 return findTermByUuid(uuidEmendation
);
279 * Returns the "later homonym" name relationship type. The first
280 * {@link TaxonNameBase taxon name} involved in such a relationship should
281 * have been published after the second taxon name. The two {@link TaxonNameBase taxon names}
282 * involved in such a relationship must belong to different
283 * {@link HomotypicalGroup homotypical groups}, have in general different
284 * {@link NonViralName#getAuthorshipCache() authorship} and their name parts (excluding infraspecific
285 * {@link Rank ranks}) must be (almost) identical, so one could be mistaken for
286 * the other one. The first taxon name is "illegitimate" and the second one
287 * is "legitimate" (this corresponds to "invalid" and "valid" in case of
288 * {@link ZoologicalName zoological names}).<BR>
289 * For instance <i>Astragalus rhizanthus</i> Boiss. is a later homonym of
290 * <i>Astragalus rhizanthus</i> Royle.<BR>
291 * This type is not symmetric but transitive.
293 * @see NomenclaturalStatusType#isIllegitimateType()
294 * @see NomenclaturalStatusType#isLegitimateType()
296 public static final NameRelationshipType
LATER_HOMONYM(){
297 return findTermByUuid(uuidLaterHomonym
);
300 * Returns the "treated as later homonym" name relationship type. The first
301 * {@link TaxonNameBase taxon name} involved in such a relationship is
302 * treated as an homonym although it has been published before the second
303 * taxon name. The two taxon names involved must belong to different
304 * {@link HomotypicalGroup homotypical groups} and their name parts (excluding
305 * {@link Rank#isInfraSpecific() infraspecific ranks} and {@link NonViralName#getAuthorshipCache() authorship}) must be
306 * almost identical (so one could be mistaken for the other). The first
307 * taxon name is "illegitimate" and the second one is "legitimate" (this
308 * corresponds to "invalid" and "valid" in case of {@link ZoologicalName zoological names}).<BR>
309 * This type is not symmetric but transitive.
311 * @see #LATER_HOMONYM()
312 * @see NomenclaturalStatusType#isIllegitimateType()
313 * @see NomenclaturalStatusType#isLegitimateType()
315 public static final NameRelationshipType
TREATED_AS_LATER_HOMONYM(){
316 return findTermByUuid(uuidTreatedAsLaterHomonym
);
319 * Returns the "alternative name" name relationship type. Both {@link TaxonNameBase taxon names}
320 * involved in such a relationship are family names. The first one is a
321 * classical name long in use, in some cases, even before 1753 and is considered as
322 * {@link NomenclaturalStatusType#VALID() valid} and also {@link NomenclaturalStatusType#isLegitimateType() legitimate}
323 * although it does not follow the rules for family names (see Article 18 of
324 * the ICBN). An alternative name is typified by the type of the name
325 * it is alternative to (so both must belong to the same
326 * {@link HomotypicalGroup homotypical group}).<BR>
327 * For instance <i>Cruciferae</i> Adans is an alternative name to
328 * <i>Brassicaceae</i> Lindl.<BR>
329 * This type is neither symmetric nor transitive.
331 public static final NameRelationshipType
ALTERNATIVE_NAME(){
332 return findTermByUuid(uuidAlternativeName
);
335 * Returns the "basionym" name relationship type. The first {@link TaxonNameBase taxon name}
336 * involved in such a relationship is the "basionym" of the second taxon
337 * name. Both taxon names belong to the same {@link HomotypicalGroup homotypical group}).
338 * The basionym is the epithet-bringing taxon name (first taxon name
339 * ever validly published given to the same {@link Rank#isInfraGeneric() infrageneric}
340 * taxon, the epithet of which is the same as in the second taxon name
341 * originated through a reclassification).<BR>
342 * According to the ICBN the author of the basionym must be mentioned in the
343 * later taxon name (by placing it in parentheses before the authority of
344 * the new combination). For instance <i>Pinus abies</i> L. is the basionym of
345 * <i>Picea abies</i> (L.) H. Karst.<BR>
346 * This type is neither symmetric nor transitive.
348 public static final NameRelationshipType
BASIONYM(){
349 return findTermByUuid(uuidBasionym
);
352 * Returns the "replaced synonym" name relationship type. The first
353 * {@link TaxonNameBase taxon name} involved in such a relationship is the
354 * "replaced synonym" of the second taxon name. Both taxon names belong to
355 * the same {@link HomotypicalGroup homotypical group}. The replaced synonym is the
356 * first taxon name ever validly published given to the same
357 * {@link Rank#isInfraGeneric() infrageneric} taxon that is either itself a
358 * "later homonym" or the epithet of which could not be used in the new
359 * taxon name originated through a reclassification. A new epithet must be
360 * proposed if the use of the original epithet leads to an already existing
361 * taxon name (for another taxon) or in botany to autonyms (since the ICBN
362 * does not allow such names where epithet and genus name are the same).<BR>
363 * For instance <i>Spartium biflorum</i> Desf. is the replaced synonym of
364 * of <i>Cytisus fontanesii</i> Spach ("novum" taxon name) because at the time
365 * of reclassification a taxon name <i>Cytisus biflorum</i> had been already
366 * published by L'H�r.<BR>
367 * This type is neither symmetric nor transitive.
370 * @see #LATER_HOMONYM()
371 * @see NomenclaturalStatusType#NOVUM()
373 public static final NameRelationshipType
REPLACED_SYNONYM(){
374 return findTermByUuid(uuidReplacedSynonym
);
377 * Returns the "conserved against" name relationship type. Both {@link TaxonNameBase taxon names}
378 * involved in such a relationship belong to the same {@link HomotypicalGroup homotypical group}.
379 * Competent authorities decided, regardless of the general
380 * nomenclatural rules, to handle the first one as the "legitimate"
381 * one and the second taxon name as "illegitimate" (this corresponds to
382 * "valid" and "invalid" in case of {@link ZoologicalName zoological names}).<BR>
383 * For instance <i>Cephaloziella</i> (Spruce) Schiffn. is conserved against
384 * <i>Dichiton</i> Mont.<BR>
385 * This type is neither symmetric nor transitive.
387 * @see NomenclaturalStatusType#CONSERVED()
388 * @see NomenclaturalStatusType#REJECTED()
389 * @see NomenclaturalStatusType#isLegitimateType()
390 * @see NomenclaturalStatusType#isIllegitimateType()
392 public static final NameRelationshipType
CONSERVED_AGAINST(){
393 return findTermByUuid(uuidConservedAgainst
);
396 * Returns the "validated by name" name relationship type. The two
397 * {@link TaxonNameBase taxon names} involved in such a relationship were published
398 * in order to define the same taxonomical group but the first
399 * (earlier) taxon name was invalidly published whereas the second (later)
400 * taxon name is the one which was validly published for the first time.<BR>
401 * This type is neither symmetric nor transitive.
403 * @see NomenclaturalStatusType#isInvalidType()
404 * @see NomenclaturalStatusType#VALID()
406 public static final NameRelationshipType
VALIDATED_BY_NAME(){
407 return findTermByUuid(uuidValidatedByName
);
410 * Returns the "later validated by name" name relationship type. The two
411 * {@link TaxonNameBase taxon names} involved in such a relationship were published
412 * in order to define the same taxonomical group but the first
413 * (earlier) taxon name was invalidly published whereas the second (later)
414 * taxon name is the one which was validly published for the first time.<BR>
415 * This type is neither symmetric nor transitive.
417 * @see NomenclaturalStatusType#isInvalidType()
418 * @see NomenclaturalStatusType#VALID()
420 public static final NameRelationshipType
LATER_VALIDATED_BY_NAME(){
421 return findTermByUuid(uuidLaterValidatedByName
);
424 * Returns the "blocking name" name relationship type. The first
425 * {@link TaxonNameBase taxon name} involved in such a relationship is the
426 * "blocking name" for the second taxon name. Both taxon names belong to
427 * different {@link HomotypicalGroup homotypical groups}). The blocking taxon name is the
428 * {@link Rank#isInfraGeneric() infrageneric} taxon name, already published at the time of
429 * reclassification, which makes illegitim (because of homonymy) the use of
430 * the epithet in the second taxon name originated through a reclassification.
431 * Therefore a "replaced synonym" name relationship arises.<BR>
432 * For instance <i>Cytisus biflorum</i> L'H�r. is the blocking name for
433 * <i>Cytisus fontanesii</i> Spach ("novum" taxon name) when reclassifying
434 * <i>Spartium biflorum</i> Desf. from <i>Spartium</i> to <i>Cytisus</i>.<BR>
435 * This type is neither symmetric nor transitive.
437 * @see #REPLACED_SYNONYM()
438 * @see #LATER_HOMONYM()
439 * @see NomenclaturalStatusType#NOVUM()
441 public static final NameRelationshipType
BLOCKING_NAME_FOR(){
442 return findTermByUuid(uuidBlockingNameFor
);
446 protected void setDefaultTerms(TermVocabulary
<NameRelationshipType
> termVocabulary
) {
447 termMap
= new HashMap
<UUID
, NameRelationshipType
>();
448 for (NameRelationshipType term
: termVocabulary
.getTerms()){
449 termMap
.put(term
.getUuid(), term
);
454 public NameRelationshipType
readCsvLine(Class
<NameRelationshipType
> termClass
, List
<String
> csvLine
, Map
<UUID
,DefinedTermBase
> terms
) {
455 NameRelationshipType result
= super.readCsvLine(termClass
, csvLine
, terms
);
456 String kindOfString
= csvLine
.get(10).trim();
457 if (CdmUtils
.isNotEmpty(kindOfString
)){
458 UUID uuidKindOf
= UUID
.fromString(kindOfString
);
459 DefinedTermBase kindOf
= terms
.get(uuidKindOf
);
460 result
.setKindOf((NameRelationshipType
)kindOf
);