root/trunk/cdmlib/cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/name/NameRelationshipType.java

/**
* Copyright (C) 2007 EDIT
* European Distributed Institute of Taxonomy 
* http://www.e-taxonomy.eu
* 
* The contents of this file are subject to the Mozilla Public License Version 1.1
* See LICENSE.TXT at the top of this package for the full license terms.
*/

package eu.etaxonomy.cdm.model.name;


import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.UUID;

import javax.persistence.Entity;
import javax.persistence.Transient;
import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlType;

import org.apache.log4j.Logger;
import org.hibernate.envers.Audited;
import org.hibernate.search.annotations.Indexed;

import eu.etaxonomy.cdm.common.CdmUtils;
import eu.etaxonomy.cdm.model.common.DefinedTermBase;
import eu.etaxonomy.cdm.model.common.RelationshipTermBase;
import eu.etaxonomy.cdm.model.common.TermVocabulary;

/**
 * The class representing the categories of {@link NameRelationship taxon name relationships} between
 * two {@link TaxonNameBase taxon names}. These name relationship types are
 * based on the concrete {@link NomenclaturalCode nomenclatural code} governing
 * the taxon names involved in the name relationship or on decisions taken by
 * the competent authorities; they do not depend on the use made of these
 * taxon names in a particular reference or in a particular taxonomic treatment.
 * Most relationships are to be understood as 'is .... of': for instance 
 * <i>Linum radiola</i> L. is a replaced synonym of <i>Radiola linoides</i> Roth or
 * <i>Astragalus rhizanthus</i> Boiss. is a later homonym of
 * <i>Astragalus rhizanthus</i> Royle.  
 * <P>
 * A standard (ordered) list of name relationship type instances will be
 * automatically created as the project starts. But this class allows to extend
 * this standard list by creating new instances of additional name relationship
 * types if needed. 
 * <P>
 * This class corresponds partially to: <ul>
 * <li> TaxonRelationshipTerm and NomenclaturalNoteTypeTerm according to the TDWG ontology
 * <li> RelationshipType and NomenclaturalNoteType according to the TCS
 * </ul>
 * 
 * @author m.doering
 * @version 1.0
 * @created 08-Nov-2007 13:06:38
 */
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "NameRelationshipType")
@Entity
@Indexed(index = "eu.etaxonomy.cdm.model.common.DefinedTermBase")
@Audited
public class NameRelationshipType extends RelationshipTermBase<NameRelationshipType> {
        static Logger logger = Logger.getLogger(NameRelationshipType.class);

        private static final UUID uuidOrthographicVariant = UUID.fromString("eeaea868-c4c1-497f-b9fe-52c9fc4aca53");
        private static final UUID uuidMisspelling = UUID.fromString("c6f9afcb-8287-4a2b-a6f6-4da3a073d5de");
        private static final UUID uuidEmendation = UUID.fromString("6e23ad45-3f2a-462b-ad87-d2389cd6e26c");
        private static final UUID uuidLaterHomonym = UUID.fromString("80f06f65-58e0-4209-b811-cb40ad7220a6");
        private static final UUID uuidTreatedAsLaterHomonym = UUID.fromString("2990a884-3302-4c8b-90b2-dfd31aaa2778");
        private static final UUID uuidAlternativeName = UUID.fromString("049c6358-1094-4765-9fae-c9972a0e7780");
        private static final UUID uuidBasionym = UUID.fromString("25792738-98de-4762-bac1-8c156faded4a");
        private static final UUID uuidReplacedSynonym = UUID.fromString("71c67c38-d162-445b-b0c2-7aba56106696");
        private static final UUID uuidConservedAgainst = UUID.fromString("e6439f95-bcac-4ebb-a8b5-69fa5ce79e6a");
        private static final UUID uuidValidatedByName = UUID.fromString("a176c9ad-b4c2-4c57-addd-90373f8270eb");
        private static final UUID uuidLaterValidatedByName = UUID.fromString("a25ee4c1-863a-4dab-9499-290bf9b89639");
        private static final UUID uuidBlockingNameFor = UUID.fromString("1dab357f-2e12-4511-97a4-e5153589e6a6");
        
        protected static Map<UUID, NameRelationshipType> termMap = null;                
        
        protected static NameRelationshipType findTermByUuid(UUID uuid){
                if (termMap == null){
                        return null;
                }
                return (NameRelationshipType)termMap.get(uuid);
        }
        
        
        // ************* CONSTRUCTORS *************/    
        /** 
         * Class constructor: creates a new empty name relationship type instance.
         * 
         * @see         #NameRelationshipType(String, String, String, boolean, boolean)
         */
        public NameRelationshipType() {
        }
        
        /** 
         * Class constructor: creates an additional name relationship type
         * instance with a description, a label, a label abbreviation and the flags
         * indicating whether <i>this</i> new name relationship type is symmetric and/or
         * transitive.
         * 
         * @param       term             the string (in the default language) describing the
         *                                               new name relationship type to be created 
         * @param       label            the string identifying the new name relationship
         *                                               type to be created
         * @param       labelAbbrev  the string identifying (in abbreviated form) the
         *                                               new name relationship type to be created
         * @param       symmetric        the boolean indicating whether the new name
         *                                               relationship type to be created is symmetric
         * @param       transitive       the boolean indicating whether the new name
         *                                               relationship type to be created is transitive
         * @see                                  #NameRelationshipType()
         */
        public NameRelationshipType(String term, String label, String labelAbbrev, boolean symmetric, boolean transitive) {
                super(term, label, labelAbbrev, symmetric, transitive);
        }


        
//************************** METHODS ********************************
        
        /* (non-Javadoc)
         * @see eu.etaxonomy.cdm.model.common.DefinedTermBase#resetTerms()
         */
        @Override
        public void resetTerms(){
                termMap = null;
        }
        
        // TODO this method should be moved to consistency proof classes
        /**
         * Returns the boolean value indicating whether the nomenclatural status
         * type of the {@link eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom() first taxon name}
         * involved in a name relationship with <i>this</i> name relationship type should
         * be "invalid" (true) or not (false). Returns false if <i>this</i> name
         * relationship status type is null.
         *
         * @see  #isLegitimateType()
         * @see  #isIllegitimateType()
         * @see  NomenclaturalStatusType#isInvalidType()
         * @see  eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom()
         */
        @Transient
        public boolean isInvalidType(){
                if (this.equals(VALIDATED_BY_NAME()) || 
                                this.equals(LATER_VALIDATED_BY_NAME())
                        ){
                        return true;    
                }else{
                        return false;
                }
        }

        // TODO this method should be moved to consistency proof classes
        /**
         * Returns the boolean value indicating whether the nomenclatural status
         * type of the {@link eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom() first taxon name}
         * involved in a name relationship with <i>this</i> name relationship type should
         * be "legitimate" (true) or not (false). Returns false if <i>this</i> name
         * relationship status type is null.
         *
         * @see  #isInvalidType()
         * @see  #isIllegitimateType()
         * @see  NomenclaturalStatusType#isLegitimateType()
         * @see  eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom()
         */
        @Transient
        public boolean isLegitimateType(){
                if (this.equals(BASIONYM()) || 
                                this.equals(REPLACED_SYNONYM()) || 
                                this.equals(ALTERNATIVE_NAME()) ||
                                this.equals(CONSERVED_AGAINST())
                        ){
                        return true;    
                }else{
                        return false;
                }
        }

        // TODO this method should be moved to consistency proof classes
        /**
         * Returns the boolean value indicating whether the nomenclatural status
         * type of the {@link eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom() first taxon name}
         * involved in a name relationship with <i>this</i> name relationship type should
         * be "illegitimate" (true) or not (false). Returns false if <i>this</i> name
         * relationship status type is null.
         *
         * @see  #isInvalidType()
         * @see  #isLegitimateType()
         * @see  NomenclaturalStatusType#isIllegitimateType()
         * @see  eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom()
         */
        @Transient
        public boolean isIllegitimateType(){
                //TODO: implement isX method. Maybe as persistent class attribute?
                //TODO: RejectedInFavour,
                if (this.equals(LATER_HOMONYM()) || 
                                this.equals(TREATED_AS_LATER_HOMONYM())
                        ){
                        return true;    
                }else{
                        return false;
                }
        }
        
        @Transient
        public boolean isBasionymRelation(){
                if (BASIONYM() == null){
                        throw new IllegalStateException("NameRelationships have not been initialized yet. Please initialize DefinedTerms first");
                }
                return this.equals(BASIONYM());
        }
        
        @Transient
        public boolean isReplacedSynonymRelation(){
                if (REPLACED_SYNONYM() == null){
                        throw new IllegalStateException("NameRelationships have not been initialized yet. Please initialize DefinedTerms first");
                }
                return this.equals(REPLACED_SYNONYM());
        }

        
        /**
         * Returns the "orthographic variant" name relationship type. The first
         * {@link TaxonNameBase taxon name} involved in such a relationship is an 
         * orthographic variant of the second taxon name. The two {@link TaxonNameBase taxon names}
         * involved in such a relationship must have the same {@link NonViralName#getAuthorshipCache() authorship}
         * and {@link Rank rank}, belong to the same {@link HomotypicalGroup homotypical group} and their name parts
         * must be almost identical (so one usually does not differentiate them).<BR>
         * For instance <i>Angelica silvestris</i> L. is an orthographic variant of
         * <i>Angelica sylvestris</i> L.<BR>
         * This type is symmetric and transitive but usually orthographic variant relationships should be organized
         * in a star schema with the correct variant in the middle and other variants pointing to it.
         */
        public static final NameRelationshipType ORTHOGRAPHIC_VARIANT(){
                  return findTermByUuid(uuidOrthographicVariant);
        }
        /**
         * Returns the "misspelling" name relationship type. The first
         * {@link TaxonNameBase taxon name} involved in such a relationship is a 
         * misspelling of the second taxon name. The two {@link TaxonNameBase taxon names}
         * involved in such a relationship must have the same {@link NonViralName#getAuthorshipCache() authorship}
         * and {@link Rank rank}, belong to the same {@link HomotypicalGroup homotypical group} and their name parts
         * must be almost identical (so one usually does not differentiate them).<BR>
         * For instance <i>Anhelica silvestris</i> L. is a misspelling of
         * <i>Angelica silvestris</i> L.<BR>
         * A misspelling is always accicentally (not on purpose). Therefore misspellings are a 
         * subset of {@link #ORTHOGRAPHIC_VARIANT orthographic variants} and are complementary to 
         * emendations. A misspelling is always an {@link #ORTHOGRAPHIC_VARIANT orthographic variant}, too.
         * This type is symmetric and transitive but usually the misspelling relationships should be organized
         * in a star schema with the correct variant in the middle and the misspellings pointing to it.
         */
        public static final NameRelationshipType MISSPELLING(){
                  return findTermByUuid(uuidMisspelling);
        }
        /**
         * Returns the "emendation" name relationship type. The first
         * {@link TaxonNameBase taxon name} involved in such a relationship is a 
         * misspelling of the second taxon name. The two {@link TaxonNameBase taxon names}
         * involved in such a relationship must have the same {@link NonViralName#getAuthorshipCache() authorship}
         * and {@link Rank rank}, belong to the same {@link HomotypicalGroup homotypical group} and their name parts
         * must be almost identical (so one usually does not differentiate them).<BR>
         * For instance <i>Angelica silvestris</i> L. is a emendation of
         * <i>Angelica sylvestris</i> L.<BR>
         * The name corrected by an emendation has originally been used on purpose (not accidentially) 
         * Therefore emendations are a subset of {@link #ORTHOGRAPHIC_VARIANT orthographic variants} and are 
         * complementary to {@link #MISSPELLING missepllings}. An emendation is always an 
         * {@link #ORTHOGRAPHIC_VARIANT orthographic variant}, too.<BR>
         * This type is symmetric and transitive but usually the misspelling relationships should be organized
         * in a star schema with the correct variant in the middle and the misspellings pointing to it.
         */
        public static final NameRelationshipType EMENDATION(){
                  return findTermByUuid(uuidEmendation);
        }
        /**
         * Returns the "later homonym" name relationship type. The first
         * {@link TaxonNameBase taxon name} involved in such a relationship should
         * have been published after the second taxon name. The two {@link TaxonNameBase taxon names}
         * involved in such a relationship must belong to different
         * {@link HomotypicalGroup homotypical groups}, have in general different
         * {@link NonViralName#getAuthorshipCache() authorship} and their name parts (excluding infraspecific
         * {@link Rank ranks}) must be (almost) identical, so one could be mistaken for
         * the other one. The first taxon name is "illegitimate" and the second one
         * is "legitimate" (this corresponds to "invalid" and "valid" in case of
         * {@link ZoologicalName zoological names}).<BR>
         * For instance <i>Astragalus rhizanthus</i> Boiss. is a later homonym of
         * <i>Astragalus rhizanthus</i> Royle.<BR>
         * This type is not symmetric but transitive.
         * 
         * @see NomenclaturalStatusType#isIllegitimateType()
         * @see NomenclaturalStatusType#isLegitimateType()
         */
        public static final NameRelationshipType LATER_HOMONYM(){
          return findTermByUuid(uuidLaterHomonym);
        }
        /**
         * Returns the "treated as later homonym" name relationship type. The first
         * {@link TaxonNameBase taxon name} involved in such a relationship is
         * treated as an homonym although it has been published before the second
         * taxon name. The two taxon names involved must belong to different
         * {@link HomotypicalGroup homotypical groups} and their name parts (excluding
         * {@link Rank#isInfraSpecific() infraspecific ranks} and {@link NonViralName#getAuthorshipCache() authorship}) must be
         * almost identical (so one could be mistaken for the other). The first
         * taxon name is "illegitimate" and the second one is "legitimate" (this
         * corresponds to "invalid" and "valid" in case of {@link ZoologicalName zoological names}).<BR>
         * This type is not symmetric but transitive.
         * 
         * @see #LATER_HOMONYM()
         * @see NomenclaturalStatusType#isIllegitimateType()
         * @see NomenclaturalStatusType#isLegitimateType()
         */
        public static final NameRelationshipType TREATED_AS_LATER_HOMONYM(){
          return findTermByUuid(uuidTreatedAsLaterHomonym);
        }
        /**
         * Returns the "alternative name" name relationship type. Both {@link TaxonNameBase taxon names}
         * involved in such a relationship are family names. The first one is a
         * classical name long in use, in some cases, even before 1753 and is considered as
         * {@link NomenclaturalStatusType#VALID() valid} and also {@link NomenclaturalStatusType#isLegitimateType() legitimate}
         * although it does not follow the rules for family names (see Article 18 of
         * the ICBN). An alternative name is typified by the type of the name
         * it is alternative to (so both must belong to the same
         * {@link HomotypicalGroup homotypical group}).<BR>
         * For instance <i>Cruciferae</i> Adans is an alternative name to
         * <i>Brassicaceae</i> Lindl.<BR>
         * This type is neither symmetric nor transitive.
         */
        public static final NameRelationshipType ALTERNATIVE_NAME(){
          return findTermByUuid(uuidAlternativeName);
        }
        /**
         * Returns the "basionym" name relationship type. The first {@link TaxonNameBase taxon name} 
         * involved in such a relationship is the "basionym" of the second taxon
         * name. Both taxon names belong to the same {@link HomotypicalGroup homotypical group}).
         * The basionym is the epithet-bringing taxon name (first taxon name 
         * ever validly published given to the same {@link Rank#isInfraGeneric() infrageneric}
         * taxon, the epithet of which is the same as in the second taxon name 
         * originated through a reclassification).<BR>
         * According to the ICBN the author of the basionym must be mentioned in the
         * later taxon name (by placing it in parentheses before the authority of
         * the new combination). For instance <i>Pinus abies</i> L. is the basionym of
         * <i>Picea abies</i> (L.) H. Karst.<BR>
         * This type is neither symmetric nor transitive.
         */
        public static final NameRelationshipType BASIONYM(){
          return findTermByUuid(uuidBasionym);
        }
        /**
         * Returns the "replaced synonym" name relationship type. The first 
         * {@link TaxonNameBase taxon name} involved in such a relationship is the
         * "replaced synonym" of the second taxon name. Both taxon names belong to
         * the same {@link HomotypicalGroup homotypical group}. The replaced synonym is the
         * first taxon name ever validly published given to the same
         * {@link Rank#isInfraGeneric() infrageneric} taxon that is either itself a
         * "later homonym" or the epithet of which could not be used in the new
         * taxon name originated through a reclassification. A new epithet must be
         * proposed if the use of the original epithet leads to an already existing
         * taxon name (for another taxon) or in botany to autonyms (since the ICBN
         * does not allow such names where epithet and genus name are the same).<BR>
         * For instance <i>Spartium biflorum</i> Desf. is the replaced synonym of
         * of <i>Cytisus fontanesii</i> Spach ("novum" taxon name) because at the time
         * of reclassification a taxon name <i>Cytisus biflorum</i> had been already
         * published by L'H�r.<BR>
         * This type is neither symmetric nor transitive.
         * 
         * @see #BASIONYM()
         * @see #LATER_HOMONYM()
         * @see NomenclaturalStatusType#NOVUM()
         */
        public static final NameRelationshipType REPLACED_SYNONYM(){
          return findTermByUuid(uuidReplacedSynonym);
        }
        /**
         * Returns the "conserved against" name relationship type. Both {@link TaxonNameBase taxon names}
         * involved in such a relationship belong to the same {@link HomotypicalGroup homotypical group}.
         * Competent authorities decided, regardless of the general
         * nomenclatural rules, to handle the first one as the "legitimate"
         * one and the second taxon name as "illegitimate" (this corresponds to
         * "valid" and "invalid" in case of {@link ZoologicalName zoological names}).<BR>
         * For instance <i>Cephaloziella</i> (Spruce) Schiffn. is conserved against
         * <i>Dichiton</i> Mont.<BR>
         * This type is neither symmetric nor transitive.
         * 
         * @see NomenclaturalStatusType#CONSERVED()
         * @see NomenclaturalStatusType#REJECTED()
         * @see NomenclaturalStatusType#isLegitimateType()
         * @see NomenclaturalStatusType#isIllegitimateType()
         */
        public static final NameRelationshipType CONSERVED_AGAINST(){
          return findTermByUuid(uuidConservedAgainst);
        }
        /**
         * Returns the "validated by name" name relationship type. The two
         * {@link TaxonNameBase taxon names} involved in such a relationship were published
         * in order to define the same taxonomical group but the first
         * (earlier) taxon name was invalidly published whereas the second (later)
         * taxon name is the one which was validly published for the first time.<BR>
         * This type is neither symmetric nor transitive.
         * 
         * @see         NomenclaturalStatusType#isInvalidType()
         * @see         NomenclaturalStatusType#VALID()
         */
        public static final NameRelationshipType VALIDATED_BY_NAME(){
          return findTermByUuid(uuidValidatedByName);
        }
        /**
         * Returns the "later validated by name" name relationship type. The two
         * {@link TaxonNameBase taxon names} involved in such a relationship were published
         * in order to define the same taxonomical group but the first
         * (earlier) taxon name was invalidly published whereas the second (later)
         * taxon name is the one which was validly published for the first time.<BR>
         * This type is neither symmetric nor transitive.
         * 
         * @see         NomenclaturalStatusType#isInvalidType()
         * @see         NomenclaturalStatusType#VALID()
         */
        public static final NameRelationshipType LATER_VALIDATED_BY_NAME(){
          return findTermByUuid(uuidLaterValidatedByName); 
        }
        /**
         * Returns the "blocking name" name relationship type. The first 
         * {@link TaxonNameBase taxon name} involved in such a relationship is the
         * "blocking name" for the second taxon name. Both taxon names belong to
         * different {@link HomotypicalGroup homotypical groups}). The blocking taxon name is the
         * {@link Rank#isInfraGeneric() infrageneric} taxon name, already published at the time of
         * reclassification, which makes illegitim (because of homonymy) the use of
         * the epithet in the second taxon name originated through a reclassification.
         * Therefore a "replaced synonym" name relationship arises.<BR>
         * For instance  <i>Cytisus biflorum</i> L'H�r. is the blocking name for
         * <i>Cytisus fontanesii</i> Spach ("novum" taxon name) when reclassifying
         * <i>Spartium biflorum</i> Desf. from <i>Spartium</i> to <i>Cytisus</i>.<BR>
         * This type is neither symmetric nor transitive.
         * 
         * @see #REPLACED_SYNONYM()
         * @see #LATER_HOMONYM()
         * @see NomenclaturalStatusType#NOVUM()
         */
        public static final NameRelationshipType BLOCKING_NAME_FOR(){
          return  findTermByUuid(uuidBlockingNameFor);
        }

        @Override
        protected void setDefaultTerms(TermVocabulary<NameRelationshipType> termVocabulary) {
                termMap = new HashMap<UUID, NameRelationshipType>();
                for (NameRelationshipType term : termVocabulary.getTerms()){
                        termMap.put(term.getUuid(), term);
                }
        }

        @Override
        public NameRelationshipType readCsvLine(Class<NameRelationshipType> termClass, List<String> csvLine, Map<UUID,DefinedTermBase> terms) {
                NameRelationshipType result = super.readCsvLine(termClass, csvLine, terms);
                String kindOfString = csvLine.get(10).trim();
                if (CdmUtils.isNotEmpty(kindOfString)){
                        UUID uuidKindOf = UUID.fromString(kindOfString);
                        DefinedTermBase kindOf = terms.get(uuidKindOf);
                        result.setKindOf((NameRelationshipType)kindOf);
                }
                return result;
        }
}