EDIT

/**

* 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.beans.PropertyChangeEvent;

import java.beans.PropertyChangeListener;

import java.lang.reflect.Method;

import java.util.ArrayList;

import java.util.Collections;

import java.util.HashSet;

import java.util.List;

import java.util.Map;

import java.util.Set;

import javax.persistence.Column;

import javax.persistence.Entity;

import javax.persistence.FetchType;

import javax.persistence.Inheritance;

import javax.persistence.InheritanceType;

import javax.persistence.JoinColumn;

import javax.persistence.JoinTable;

import javax.persistence.ManyToMany;

import javax.persistence.ManyToOne;

import javax.persistence.OneToMany;

import javax.persistence.Transient;

import javax.validation.Valid;

import javax.validation.constraints.Min;

import javax.validation.constraints.NotNull;

import javax.validation.constraints.Pattern;

import javax.xml.bind.annotation.XmlAccessType;

import javax.xml.bind.annotation.XmlAccessorType;

import javax.xml.bind.annotation.XmlAttribute;

import javax.xml.bind.annotation.XmlElement;

import javax.xml.bind.annotation.XmlElementWrapper;

import javax.xml.bind.annotation.XmlIDREF;

import javax.xml.bind.annotation.XmlRootElement;

import javax.xml.bind.annotation.XmlSchemaType;

import javax.xml.bind.annotation.XmlType;

import org.apache.commons.lang.StringUtils;

import org.apache.log4j.Logger;

import org.hibernate.annotations.Cascade;

import org.hibernate.annotations.CascadeType;

import org.hibernate.annotations.Table;

import org.hibernate.annotations.Type;

import org.hibernate.envers.Audited;

import org.hibernate.search.annotations.Analyze;

import org.hibernate.search.annotations.Analyzer;

import org.hibernate.search.annotations.Field;

import org.hibernate.search.annotations.Fields;

import org.hibernate.search.annotations.Index;

import org.hibernate.search.annotations.Indexed;

import org.hibernate.search.annotations.IndexedEmbedded;

import org.hibernate.search.annotations.Store;

import org.hibernate.validator.constraints.NotEmpty;

import org.springframework.util.ReflectionUtils;

import eu.etaxonomy.cdm.common.CdmUtils;

import eu.etaxonomy.cdm.common.UTF8;

import eu.etaxonomy.cdm.model.agent.INomenclaturalAuthor;

import eu.etaxonomy.cdm.model.agent.TeamOrPersonBase;

import eu.etaxonomy.cdm.model.common.CdmBase;

import eu.etaxonomy.cdm.model.common.DefinedTermBase;

import eu.etaxonomy.cdm.model.common.IIntextReferenceTarget;

import eu.etaxonomy.cdm.model.common.IParsable;

import eu.etaxonomy.cdm.model.common.IRelated;

import eu.etaxonomy.cdm.model.common.IdentifiableEntity;

import eu.etaxonomy.cdm.model.common.RelationshipBase;

import eu.etaxonomy.cdm.model.common.RelationshipBase.Direction;

import eu.etaxonomy.cdm.model.common.TermType;

import eu.etaxonomy.cdm.model.common.TermVocabulary;

import eu.etaxonomy.cdm.model.description.IDescribable;

import eu.etaxonomy.cdm.model.description.TaxonNameDescription;

import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;

import eu.etaxonomy.cdm.model.reference.INomenclaturalReference;

import eu.etaxonomy.cdm.model.reference.Reference;

import eu.etaxonomy.cdm.model.taxon.Synonym;

import eu.etaxonomy.cdm.model.taxon.Taxon;

import eu.etaxonomy.cdm.model.taxon.TaxonBase;

import eu.etaxonomy.cdm.strategy.cache.TaggedText;

import eu.etaxonomy.cdm.strategy.cache.name.CacheUpdate;

import eu.etaxonomy.cdm.strategy.cache.name.INameCacheStrategy;

import eu.etaxonomy.cdm.strategy.cache.name.TaxonNameDefaultCacheStrategy;

import eu.etaxonomy.cdm.strategy.match.IMatchable;

import eu.etaxonomy.cdm.strategy.match.Match;

import eu.etaxonomy.cdm.strategy.match.Match.ReplaceMode;

import eu.etaxonomy.cdm.strategy.match.MatchMode;

import eu.etaxonomy.cdm.strategy.merge.Merge;

import eu.etaxonomy.cdm.strategy.merge.MergeMode;

import eu.etaxonomy.cdm.strategy.parser.ParserProblem;

import eu.etaxonomy.cdm.validation.Level2;

import eu.etaxonomy.cdm.validation.Level3;

import eu.etaxonomy.cdm.validation.annotation.CorrectEpithetsForRank;

import eu.etaxonomy.cdm.validation.annotation.NameMustFollowCode;

import eu.etaxonomy.cdm.validation.annotation.NameMustHaveAuthority;

import eu.etaxonomy.cdm.validation.annotation.NoDuplicateNames;

import eu.etaxonomy.cdm.validation.annotation.NullOrNotEmpty;

import eu.etaxonomy.cdm.validation.annotation.ValidTaxonomicYear;

/**

 * The upmost (abstract) class for scientific taxon names regardless of any

 * particular {@link NomenclaturalCode nomenclature code}. The scientific taxon name does not depend

 * on the use made of it in a publication or a treatment

 * ({@link eu.etaxonomy.cdm.model.taxon.TaxonBase taxon concept respectively potential taxon})

 * as an {@link eu.etaxonomy.cdm.model.taxon.Taxon "accepted" respectively "correct" (taxon) name}

 * or as a {@link eu.etaxonomy.cdm.model.taxon.Synonym synonym}.

 * <P>

 * This class corresponds partially to: <ul>

 * <li> TaxonName according to the TDWG ontology

 * <li> ScientificName and CanonicalName according to the TCS

 * <li> ScientificName according to the ABCD schema

 * </ul>

 *

 * @author m.doering

 * @created 08-Nov-2007 13:06:57

 */

@XmlAccessorType(XmlAccessType.FIELD)

@XmlType(name = "TaxonName", propOrder = {

    "nameType",

    "appendedPhrase",

    "nomenclaturalMicroReference",

    "nomenclaturalReference",

    "rank",

    "fullTitleCache",

    "protectedFullTitleCache",

    "homotypicalGroup",

    "typeDesignations",

    "relationsFromThisName",

    "relationsToThisName",

    "status",

    "descriptions",

    "taxonBases",

    "registrations",

    "nameCache",

    "genusOrUninomial",

    "infraGenericEpithet",

    "specificEpithet",

    "infraSpecificEpithet",

    "combinationAuthorship",

    "exCombinationAuthorship",

    "basionymAuthorship",

    "exBasionymAuthorship",

    "authorshipCache",

    "protectedAuthorshipCache",

    "protectedNameCache",

    "hybridParentRelations",

    "hybridChildRelations",

    "hybridFormula",

    "monomHybrid",

    "binomHybrid",

    "trinomHybrid",

    "acronym",

    "subGenusAuthorship",

    "nameApprobation",

    "breed",

    "publicationYear",

    "originalPublicationYear",

    "anamorphic",

    "cultivarName"

})

@XmlRootElement(name = "TaxonName")

@Entity

@Audited

@Inheritance(strategy=InheritanceType.SINGLE_TABLE)

@Table(appliesTo="TaxonName", indexes = {

        @org.hibernate.annotations.Index(name = "taxonNameBaseTitleCacheIndex", columnNames = { "titleCache" }),

        @org.hibernate.annotations.Index(name = "taxonNameBaseNameCacheIndex", columnNames = { "nameCache" }) })

@NameMustFollowCode

@CorrectEpithetsForRank(groups = Level2.class)

@NameMustHaveAuthority(groups = Level2.class)

@NoDuplicateNames(groups = Level3.class)

@Indexed(index = "eu.etaxonomy.cdm.model.name.TaxonName")

public class TaxonName

            extends IdentifiableEntity<INameCacheStrategy>

            implements ITaxonNameBase, INonViralName, IViralName, IBacterialName, IZoologicalName,

                IBotanicalName, ICultivarPlantName, IFungusName,

                IParsable, IRelated, IMatchable, IIntextReferenceTarget, Cloneable,

                IDescribable<TaxonNameDescription>{

    private static final long serialVersionUID = -791164269603409712L;

    private static final Logger logger = Logger.getLogger(TaxonName.class);

    /**

     * The {@link TermType type} of this term. Needs to be the same type in a {@link DefinedTermBase defined term}

     * and in it's {@link TermVocabulary vocabulary}.

     */

    @XmlAttribute(name ="NameType")

    @Column(name="nameType", length=15)

    @NotNull

    @Type(type = "eu.etaxonomy.cdm.hibernate.EnumUserType",

        parameters = {@org.hibernate.annotations.Parameter(name = "enumClass", value = "eu.etaxonomy.cdm.model.name.NomenclaturalCode")}

    )

    @Audited //needed ?

    private NomenclaturalCode nameType;

    @XmlElement(name = "FullTitleCache")

    @Column(length=800, name="fullTitleCache")  //see #1592

    @Match(value=MatchMode.CACHE, cacheReplaceMode=ReplaceMode.ALL)

    @CacheUpdate(noUpdate ="titleCache")

    @NotEmpty(groups = Level2.class)

    protected String fullTitleCache;

    //if true titleCache will not be automatically generated/updated

    @XmlElement(name = "ProtectedFullTitleCache")

    @CacheUpdate(value ="fullTitleCache", noUpdate ="titleCache")

    private boolean protectedFullTitleCache;

    @XmlElementWrapper(name = "Descriptions")

    @XmlElement(name = "Description")

    @OneToMany(mappedBy="taxonName", fetch= FetchType.LAZY, orphanRemoval=true)

    @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE, CascadeType.DELETE})

    @NotNull

    private Set<TaxonNameDescription> descriptions = new HashSet<>();

    @XmlElement(name = "AppendedPhrase")

    @Field

    @CacheUpdate(value ="nameCache")

    //TODO Val #3379

//    @NullOrNotEmpty

    @Column(length=255)

    private String appendedPhrase;

    @XmlElement(name = "NomenclaturalMicroReference")

    @Field

    @CacheUpdate(noUpdate ="titleCache")

    //TODO Val #3379

//    @NullOrNotEmpty

    @Column(length=255)

    private String nomenclaturalMicroReference;

    @XmlAttribute

    @CacheUpdate(noUpdate ={"titleCache","fullTitleCache"})

    private int parsingProblem = 0;

    @XmlAttribute

    @CacheUpdate(noUpdate ={"titleCache","fullTitleCache"})

    private int problemStarts = -1;

    @XmlAttribute

    @CacheUpdate(noUpdate ={"titleCache","fullTitleCache"})

    private int problemEnds = -1;

    @XmlElementWrapper(name = "TypeDesignations")

    @XmlElement(name = "TypeDesignation")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToMany(fetch = FetchType.LAZY)

    @JoinTable(

        name="TaxonName_TypeDesignationBase",

        joinColumns=@javax.persistence.JoinColumn(name="TaxonName_id"),

        inverseJoinColumns=@javax.persistence.JoinColumn(name="typedesignations_id")

    )

    @Cascade({CascadeType.SAVE_UPDATE,CascadeType.MERGE})

    @NotNull

    private Set<TypeDesignationBase> typeDesignations = new HashSet<>();

    @XmlElement(name = "HomotypicalGroup")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

    @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE})

    @Match(MatchMode.IGNORE)

    @CacheUpdate(noUpdate ="titleCache")

    //TODO Val #3379

//    @NotNull

    private HomotypicalGroup homotypicalGroup;

    @XmlElementWrapper(name = "RelationsFromThisName")

    @XmlElement(name = "RelationFromThisName")

    @OneToMany(mappedBy="relatedFrom", fetch= FetchType.LAZY, orphanRemoval=true)

    @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE, CascadeType.DELETE})

    @Merge(MergeMode.RELATION)

    @NotNull

    @Valid

    private Set<NameRelationship> relationsFromThisName = new HashSet<>();

    @XmlElementWrapper(name = "RelationsToThisName")

    @XmlElement(name = "RelationToThisName")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @OneToMany(mappedBy="relatedTo", fetch= FetchType.LAZY, orphanRemoval=true)

    @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE, CascadeType.DELETE})

    @Merge(MergeMode.RELATION)

    @NotNull

    @Valid

    private Set<NameRelationship> relationsToThisName = new HashSet<>();

    @XmlElementWrapper(name = "NomenclaturalStatuses")

    @XmlElement(name = "NomenclaturalStatus")

    @OneToMany(fetch= FetchType.LAZY, orphanRemoval=true)

    @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE,CascadeType.DELETE})

    @NotNull

    @IndexedEmbedded(depth=1)

    private Set<NomenclaturalStatus> status = new HashSet<>();

    @XmlElementWrapper(name = "TaxonBases")

    @XmlElement(name = "TaxonBase")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @OneToMany(mappedBy="name", fetch= FetchType.LAZY)

    @NotNull

    @IndexedEmbedded(depth=1)

    private Set<TaxonBase> taxonBases = new HashSet<>();

    @XmlElement(name = "Rank")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.EAGER)

    @CacheUpdate(value ="nameCache")

    //TODO Val #3379, handle maybe as groups = Level2.class ??

//    @NotNull

    @IndexedEmbedded(depth=1)

    private Rank rank;

    @XmlElement(name = "NomenclaturalReference")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

    @Cascade({CascadeType.SAVE_UPDATE,CascadeType.MERGE})

    @CacheUpdate(noUpdate ="titleCache")

    @IndexedEmbedded

    private Reference nomenclaturalReference;

    @XmlElementWrapper(name = "Registrations")

    @XmlElement(name = "Registration")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @OneToMany(mappedBy="name", fetch= FetchType.LAZY)

    @Cascade({CascadeType.SAVE_UPDATE,CascadeType.MERGE})

    @NotNull

    @IndexedEmbedded(depth=1)

    private Set<Registration> registrations = new HashSet<>();

//****** Non-ViralName attributes ***************************************/

    @XmlElement(name = "NameCache")

    @Fields({

        @Field(name = "nameCache_tokenized"),

        @Field(store = Store.YES, index = Index.YES, analyze = Analyze.YES)

    })

    @Analyzer(impl = org.apache.lucene.analysis.core.KeywordAnalyzer.class)

    @Match(value=MatchMode.CACHE, cacheReplaceMode=ReplaceMode.DEFINED,

            cacheReplacedProperties={"genusOrUninomial", "infraGenericEpithet", "specificEpithet", "infraSpecificEpithet"} )

    @NotEmpty(groups = Level2.class) // implicitly NotNull

    @Column(length=255)

    private String nameCache;

    @XmlElement(name = "ProtectedNameCache")

    @CacheUpdate(value="nameCache")

    protected boolean protectedNameCache;

    @XmlElement(name = "GenusOrUninomial")

    @Field(analyze = Analyze.YES, indexNullAs=Field.DEFAULT_NULL_TOKEN)

    @Match(MatchMode.EQUAL_REQUIRED)

    @CacheUpdate("nameCache")

    @Column(length=255)

    @Pattern(regexp = "[A-Z][a-z\\u00E4\\u00EB\\u00EF\\u00F6\\u00FC\\-]+", groups=Level2.class, message="{eu.etaxonomy.cdm.model.name.NonViralName.allowedCharactersForUninomial.message}")

    @NullOrNotEmpty

    @NotNull(groups = Level2.class)

    private String genusOrUninomial;

    @XmlElement(name = "InfraGenericEpithet")

    @Field(analyze = Analyze.YES,indexNullAs=Field.DEFAULT_NULL_TOKEN)

    @CacheUpdate("nameCache")

    //TODO Val #3379

//    @NullOrNotEmpty

    @Column(length=255)

    @Pattern(regexp = "[a-z\\u00E4\\u00EB\\u00EF\\u00F6\\u00FC\\-]+", groups=Level2.class,message="{eu.etaxonomy.cdm.model.name.NonViralName.allowedCharactersForEpithet.message}")

    private String infraGenericEpithet;

    @XmlElement(name = "SpecificEpithet")

    @Field(analyze = Analyze.YES,indexNullAs=Field.DEFAULT_NULL_TOKEN)

    @CacheUpdate("nameCache")

    //TODO Val #3379

//    @NullOrNotEmpty

    @Column(length=255)

    @Pattern(regexp = "[a-z\\u00E4\\u00EB\\u00EF\\u00F6\\u00FC\\-]+", groups=Level2.class, message = "{eu.etaxonomy.cdm.model.name.NonViralName.allowedCharactersForEpithet.message}")

    private String specificEpithet;

    @XmlElement(name = "InfraSpecificEpithet")

    @Field(analyze = Analyze.YES,indexNullAs=Field.DEFAULT_NULL_TOKEN)

    @CacheUpdate("nameCache")

    //TODO Val #3379

//    @NullOrNotEmpty

    @Column(length=255)

    @Pattern(regexp = "[a-z\\u00E4\\u00EB\\u00EF\\u00F6\\u00FC\\-]+", groups=Level2.class, message = "{eu.etaxonomy.cdm.model.name.NonViralName.allowedCharactersForEpithet.message}")

    private String infraSpecificEpithet;

    @XmlElement(name = "CombinationAuthorship", type = TeamOrPersonBase.class)

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

//    @Target(TeamOrPersonBase.class)

    @Cascade({CascadeType.SAVE_UPDATE,CascadeType.MERGE})

    @JoinColumn(name="combinationAuthorship_id")

    @CacheUpdate("authorshipCache")

    @IndexedEmbedded

    private TeamOrPersonBase<?> combinationAuthorship;

    @XmlElement(name = "ExCombinationAuthorship", type = TeamOrPersonBase.class)

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

//    @Target(TeamOrPersonBase.class)

    @Cascade({CascadeType.SAVE_UPDATE,CascadeType.MERGE})

    @JoinColumn(name="exCombinationAuthorship_id")

    @CacheUpdate("authorshipCache")

    @IndexedEmbedded

    private TeamOrPersonBase<?> exCombinationAuthorship;

    @XmlElement(name = "BasionymAuthorship", type = TeamOrPersonBase.class)

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

//    @Target(TeamOrPersonBase.class)

    @Cascade({CascadeType.SAVE_UPDATE,CascadeType.MERGE})

    @JoinColumn(name="basionymAuthorship_id")

    @CacheUpdate("authorshipCache")

    @IndexedEmbedded

    private TeamOrPersonBase<?> basionymAuthorship;

    @XmlElement(name = "ExBasionymAuthorship", type = TeamOrPersonBase.class)

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

//    @Target(TeamOrPersonBase.class)

    @Cascade({CascadeType.SAVE_UPDATE,CascadeType.MERGE})

    @JoinColumn(name="exBasionymAuthorship_id")

    @CacheUpdate("authorshipCache")

    @IndexedEmbedded

    private TeamOrPersonBase<?> exBasionymAuthorship;

    @XmlElement(name = "AuthorshipCache")

    @Fields({

        @Field(name = "authorshipCache_tokenized"),

        @Field(analyze = Analyze.NO)

    })

    @Match(value=MatchMode.CACHE, cacheReplaceMode=ReplaceMode.DEFINED,

            cacheReplacedProperties={"combinationAuthorship", "basionymAuthorship", "exCombinationAuthorship", "exBasionymAuthorship"} )

    //TODO Val #3379

//    @NotNull

    @Column(length=255)

    @Pattern(regexp = "^[A-Za-z0-9 \\u00E4\\u00EB\\u00EF\\u00F6\\u00FC\\-\\&\\,\\(\\)\\.]+$", groups=Level2.class, message = "{eu.etaxonomy.cdm.model.name.NonViralName.allowedCharactersForAuthority.message}")

    private String authorshipCache;

    @XmlElement(name = "ProtectedAuthorshipCache")

    @CacheUpdate("authorshipCache")

    protected boolean protectedAuthorshipCache;

    @XmlElementWrapper(name = "HybridRelationsFromThisName")

    @XmlElement(name = "HybridRelationsFromThisName")

    @OneToMany(mappedBy="relatedFrom", fetch = FetchType.LAZY)

    @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE})

    @Merge(MergeMode.RELATION)

    @NotNull

    private Set<HybridRelationship> hybridParentRelations = new HashSet<>();

    @XmlElementWrapper(name = "HybridRelationsToThisName")

    @XmlElement(name = "HybridRelationsToThisName")

    @OneToMany(mappedBy="relatedTo", fetch = FetchType.LAZY, orphanRemoval=true) //a hybrid relation can be deleted automatically if the child is deleted.

    @Cascade({CascadeType.SAVE_UPDATE, CascadeType.MERGE, CascadeType.DELETE})

    @Merge(MergeMode.RELATION)

    @NotNull

    private Set<HybridRelationship> hybridChildRelations = new HashSet<>();

    //if set: this name is a hybrid formula (a hybrid that does not have an own name) and no

    //other hybrid flags may be set. A

    //hybrid name  may not have either an authorteam nor other name components.

    @XmlElement(name ="IsHybridFormula")

    @CacheUpdate("nameCache")

    private boolean hybridFormula = false;

    @XmlElement(name ="IsMonomHybrid")

    @CacheUpdate("nameCache")

    private boolean monomHybrid = false;

    @XmlElement(name ="IsBinomHybrid")

    @CacheUpdate("nameCache")

    private boolean binomHybrid = false;

    @XmlElement(name ="IsTrinomHybrid")

    @CacheUpdate("nameCache")

    private boolean trinomHybrid = false;

// ViralName attributes ************************* /

    @XmlElement(name = "Acronym")

    @Field

    //TODO Val #3379

//  @NullOrNotEmpty

    @Column(length=255)

    private String acronym;

// BacterialName attributes ***********************/

    //Author team and year of the subgenus name

    @XmlElement(name = "SubGenusAuthorship")

    @Field

    private String subGenusAuthorship;

    //Approbation of name according to approved list, validation list, or validly published, paper in IJSB after 1980

    @XmlElement(name = "NameApprobation")

    @Field

    private String nameApprobation;

    //ZOOLOGICAL NAME

    //Name of the breed of an animal

    @XmlElement(name = "Breed")

    @Field

    @NullOrNotEmpty

    @Column(length=255)

    private String breed;

    @XmlElement(name = "PublicationYear")

    @Field(analyze = Analyze.NO)

    @CacheUpdate(value ="authorshipCache")

    @Min(0)

    private Integer publicationYear;

    @XmlElement(name = "OriginalPublicationYear")

    @Field(analyze = Analyze.NO)

    @CacheUpdate(value ="authorshipCache")

    @Min(0)

    private Integer originalPublicationYear;

    //Cultivar attribute(s)

    //the characteristical name of the cultivar

    @XmlElement(name = "CultivarName")

    //TODO Val #3379

    //@NullOrNotEmpty

    @Column(length=255)

    private String cultivarName;

    // ************** FUNGUS name attributes

    //to indicate that the type of the name is asexual or not

    @XmlElement(name ="IsAnamorphic")

    private boolean anamorphic = false;

// *************** FACTORY METHODS ********************************/

    //see TaxonNameFactory

    /**

     * @param code

     * @param rank

     * @param homotypicalGroup

     * @return

     */

    protected static TaxonName NewInstance(NomenclaturalCode code, Rank rank,

            HomotypicalGroup homotypicalGroup) {

        TaxonName result = new TaxonName(code, rank, homotypicalGroup);

        return result;

    }

    /**

     * @param icnafp

     * @param rank2

     * @param genusOrUninomial2

     * @param infraGenericEpithet2

     * @param specificEpithet2

     * @param infraSpecificEpithet2

     * @param combinationAuthorship2

     * @param nomenclaturalReference2

     * @param nomenclMicroRef

     * @param homotypicalGroup2

     * @return

     */

    public static TaxonName NewInstance(NomenclaturalCode code, Rank rank, String genusOrUninomial,

            String infraGenericEpithet, String specificEpithet, String infraSpecificEpithet,

            TeamOrPersonBase combinationAuthorship, Reference nomenclaturalReference,

            String nomenclMicroRef, HomotypicalGroup homotypicalGroup) {

        TaxonName result = new TaxonName(code, rank, genusOrUninomial, infraGenericEpithet, specificEpithet, infraSpecificEpithet, combinationAuthorship, nomenclaturalReference, nomenclMicroRef, homotypicalGroup);

        return result;

    }

// ************* CONSTRUCTORS *************/

    /**

     * Class constructor: creates a new empty taxon name.

     * @param code

     *

     * @see #TaxonName(Rank)

     * @see #TaxonName(HomotypicalGroup)

     * @see #TaxonName(Rank, HomotypicalGroup)

     */

    protected TaxonName() {

        super();

        rectifyNameCacheStrategy();

    }

    /**

     * Class constructor: creates a new taxon name instance

     * only containing its {@link Rank rank} and

     * its {@link HomotypicalGroup homotypical group} and

     * the {@link eu.etaxonomy.cdm.strategy.cache.name.TaxonNameDefaultCacheStrategy default cache strategy}.

     * The new taxon name will be also added to the set of taxon names

     * belonging to this homotypical group.

     *

     * @param  rank  			 the rank to be assigned to <i>this</i> taxon name

     * @param  homotypicalGroup  the homotypical group to which <i>this</i> taxon name belongs

     * @see    					 #TaxonName()

     * @see    					 #TaxonName(Rank)

     * @see    					 #TaxonName(HomotypicalGroup)

     */

    protected TaxonName(NomenclaturalCode type, Rank rank, HomotypicalGroup homotypicalGroup) {

        this();

        setNameType(type);

        this.setRank(rank);

        if (homotypicalGroup == null){

            homotypicalGroup = HomotypicalGroup.NewInstance();

        }

        homotypicalGroup.addTypifiedName(this);

        this.homotypicalGroup = homotypicalGroup;

    }

    /**

     * Class constructor: creates a new non viral taxon name instance

     * containing its {@link Rank rank},

     * its {@link HomotypicalGroup homotypical group},

     * its scientific name components, its {@link eu.etaxonomy.cdm.model.agent.TeamOrPersonBase author(team)},

     * its {@link eu.etaxonomy.cdm.model.reference.Reference nomenclatural reference} and

     * the {@link eu.etaxonomy.cdm.strategy.cache.name.TaxonNameDefaultCacheStrategy default cache strategy}.

     * The new non viral taxon name instance will be also added to the set of

     * non viral taxon names belonging to this homotypical group.

     *

     * @param   rank  the rank to be assigned to <i>this</i> non viral taxon name

     * @param   genusOrUninomial the string for <i>this</i> non viral taxon name

     *          if its rank is genus or higher or for the genus part

     *          if its rank is lower than genus

     * @param   infraGenericEpithet  the string for the first epithet of

     *          <i>this</i> non viral taxon name if its rank is lower than genus

     *          and higher than species aggregate

     * @param   specificEpithet  the string for the first epithet of

     *          <i>this</i> non viral taxon name if its rank is species aggregate or lower

     * @param   infraSpecificEpithet  the string for the second epithet of

     *          <i>this</i> non viral taxon name if its rank is lower than species

     * @param   combinationAuthorship  the author or the team who published <i>this</i> non viral taxon name

     * @param   nomenclaturalReference  the nomenclatural reference where <i>this</i> non viral taxon name was published

     * @param   nomenclMicroRef  the string with the details for precise location within the nomenclatural reference

     * @param   homotypicalGroup  the homotypical group to which <i>this</i> non viral taxon name belongs

     * @see     #NewInstance(NomenclaturalCode, Rank, HomotypicalGroup)

     * @see     #NewInstance(NomenclaturalCode, Rank, String, String, String, String, TeamOrPersonBase, Reference, String, HomotypicalGroup)

     * @see     eu.etaxonomy.cdm.strategy.cache.name.INonViralNameCacheStrategy

     * @see     eu.etaxonomy.cdm.strategy.cache.name.INameCacheStrategy

     * @see     eu.etaxonomy.cdm.strategy.cache.common.IIdentifiableEntityCacheStrategy

     */

    protected TaxonName(NomenclaturalCode type, Rank rank, String genusOrUninomial, String infraGenericEpithet, String specificEpithet, String infraSpecificEpithet, TeamOrPersonBase combinationAuthorship, INomenclaturalReference nomenclaturalReference, String nomenclMicroRef, HomotypicalGroup homotypicalGroup) {

        this(type, rank, homotypicalGroup);

        setGenusOrUninomial(genusOrUninomial);

        setInfraGenericEpithet (infraGenericEpithet);

        setSpecificEpithet(specificEpithet);

        setInfraSpecificEpithet(infraSpecificEpithet);

        setCombinationAuthorship(combinationAuthorship);

        setNomenclaturalReference(nomenclaturalReference);

        this.setNomenclaturalMicroReference(nomenclMicroRef);

    }

    /**

     * This method was originally needed to distinguish cache strategies

     * depending on the name type. Now we have a unified cache strategy

     * which does not require this anymore. Maybe we could even further remove this method.

     */

    private void rectifyNameCacheStrategy(){

        if (this.cacheStrategy == null){

            this.cacheStrategy = TaxonNameDefaultCacheStrategy.NewInstance();

        }

    }

    @Override

    public void initListener(){

        PropertyChangeListener listener = new PropertyChangeListener() {

            @Override

            public void propertyChange(PropertyChangeEvent e) {

                boolean protectedByLowerCache = false;

                //authorship cache

                if (fieldHasCacheUpdateProperty(e.getPropertyName(), "authorshipCache")){

                    if (protectedAuthorshipCache){

                        protectedByLowerCache = true;

                    }else{

                        authorshipCache = null;

                    }

                }

                //nameCache

                if (fieldHasCacheUpdateProperty(e.getPropertyName(), "nameCache")){

                    if (protectedNameCache){

                        protectedByLowerCache = true;

                    }else{

                        nameCache = null;

                    }

                }

                //title cache

                if (! fieldHasNoUpdateProperty(e.getPropertyName(), "titleCache")){

                    if (isProtectedTitleCache()|| protectedByLowerCache == true ){

                        protectedByLowerCache = true;

                    }else{

                        titleCache = null;

                    }

                }

                //full title cache

                if (! fieldHasNoUpdateProperty(e.getPropertyName(), "fullTitleCache")){

                    if (isProtectedFullTitleCache()|| protectedByLowerCache == true ){

                        protectedByLowerCache = true;

                    }else{

                        fullTitleCache = null;

                    }

                }

            }

        };

        addPropertyChangeListener(listener);  //didn't use this.addXXX to make lsid.AssemblerTest run in cdmlib-remote

    }

    private static Map<String, java.lang.reflect.Field> allFields = null;

    protected Map<String, java.lang.reflect.Field> getAllFields(){

        if (allFields == null){

            allFields = CdmUtils.getAllFields(this.getClass(), CdmBase.class, false, false, false, true);

        }

        return allFields;

    }

    /**

     * @param propertyName

     * @param string

     * @return

     */

    private boolean fieldHasCacheUpdateProperty(String propertyName, String cacheName) {

        java.lang.reflect.Field field;

        try {

            field = getAllFields().get(propertyName);

            if (field != null){

                CacheUpdate updateAnnotation = field.getAnnotation(CacheUpdate.class);

                if (updateAnnotation != null){

                    for (String value : updateAnnotation.value()){

                        if (cacheName.equals(value)){

                            return true;

                        }

                    }

                }

            }

            return false;

        } catch (SecurityException e1) {

            throw e1;

        }

    }

    private boolean fieldHasNoUpdateProperty(String propertyName, String cacheName) {

        java.lang.reflect.Field field;

        //do not update fields with the same name

        if (cacheName.equals(propertyName)){

            return true;

        }

        //evaluate annotation

        try {

            field = getAllFields().get(propertyName);

            if (field != null){

                CacheUpdate updateAnnotation = field.getAnnotation(CacheUpdate.class);

                if (updateAnnotation != null){

                    for (String value : updateAnnotation.noUpdate()){

                        if (cacheName.equals(value)){

                            return true;

                        }

                    }

                }

            }

            return false;

        } catch (SecurityException e1) {

            throw e1;

        }

    }

// ****************** GETTER / SETTER ****************************/

    @Override

    public NomenclaturalCode getNameType() {

        return nameType;

    }

    @Override

    public void setNameType(NomenclaturalCode nameType) {

        this.nameType = nameType;

    }

    /**

     * Returns the boolean value of the flag intended to protect (true)

     * or not (false) the {@link #getNameCache() nameCache} (scientific name without author strings and year)

     * string of <i>this</i> non viral taxon name.

     *

     * @return  the boolean value of the protectedNameCache flag

     * @see     #getNameCache()

     */

    @Override

    public boolean isProtectedNameCache() {

        return protectedNameCache;

    }

    /**

     * @see     #isProtectedNameCache()

     */

    @Override

    public void setProtectedNameCache(boolean protectedNameCache) {

        this.protectedNameCache = protectedNameCache;

    }

    /**

     * Returns either the scientific name string (without authorship) for <i>this</i>

     * non viral taxon name if its rank is genus or higher (monomial) or the string for

     * the genus part of it if its {@link Rank rank} is lower than genus (bi- or trinomial).

     * Genus or uninomial strings begin with an upper case letter.

     *

     * @return  the string containing the suprageneric name, the genus name or the genus part of <i>this</i> non viral taxon name

     * @see     #getNameCache()

     */

    @Override

    public String getGenusOrUninomial() {

        return genusOrUninomial;

    }

    /**

     * @see  #getGenusOrUninomial()

     */

    @Override

    public void setGenusOrUninomial(String genusOrUninomial) {

        this.genusOrUninomial = StringUtils.isBlank(genusOrUninomial) ? null : genusOrUninomial;

    }

    /**

     * Returns the genus subdivision epithet string (infrageneric part) for

     * <i>this</i> non viral taxon name if its {@link Rank rank} is infrageneric (lower than genus and

     * higher than species aggregate: binomial). Genus subdivision epithet

     * strings begin with an upper case letter.

     *

     * @return  the string containing the infrageneric part of <i>this</i> non viral taxon name

     * @see     #getNameCache()

     */

    @Override

    public String getInfraGenericEpithet(){

        return this.infraGenericEpithet;

    }

    /**

     * @see  #getInfraGenericEpithet()

     */

    @Override

    public void setInfraGenericEpithet(String infraGenericEpithet){

        this.infraGenericEpithet = StringUtils.isBlank(infraGenericEpithet)? null : infraGenericEpithet;

    }

    /**

     * Returns the species epithet string for <i>this</i> non viral taxon name if its {@link Rank rank} is

     * species aggregate or lower (bi- or trinomial). Species epithet strings

     * begin with a lower case letter.

     *

     * @return  the string containing the species epithet of <i>this</i> non viral taxon name

     * @see     #getNameCache()

     */

    @Override

    public String getSpecificEpithet(){

        return this.specificEpithet;

    }

    /**

     * @see  #getSpecificEpithet()

     */

    @Override

    public void setSpecificEpithet(String specificEpithet){

        this.specificEpithet = StringUtils.isBlank(specificEpithet) ? null : specificEpithet;