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.lang.reflect.Method;

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.ManyToMany;

import javax.persistence.ManyToOne;

import javax.persistence.OneToMany;

import javax.persistence.Transient;

import javax.validation.constraints.NotNull;

import javax.validation.constraints.Size;

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.log4j.Logger;

import org.hibernate.annotations.Cascade;

import org.hibernate.annotations.CascadeType;

import org.hibernate.annotations.Index;

import org.hibernate.annotations.Table;

import org.hibernate.envers.Audited;

import org.hibernate.search.annotations.Field;

import org.hibernate.validator.constraints.NotEmpty;

import org.springframework.util.ReflectionUtils;

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

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

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.description.TaxonNameDescription;

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

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

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

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.name.CacheUpdate;

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

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

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

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

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

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.annotation.NullOrNotEmpty;

/**

 * 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

 * @version 1.0

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

 */

@XmlAccessorType(XmlAccessType.FIELD)

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

    "appendedPhrase",

    "nomenclaturalMicroReference",

    "nomenclaturalReference",

    "rank",

    "fullTitleCache",

    "protectedFullTitleCache",

    "homotypicalGroup",

    "typeDesignations",

    "relationsFromThisName",

    "relationsToThisName",

    "status",

    "descriptions",

    "taxonBases"

})

@XmlRootElement(name = "TaxonNameBase")

@Entity

@Audited

@Inheritance(strategy=InheritanceType.SINGLE_TABLE)

@Table(appliesTo="TaxonNameBase", indexes = { @Index(name = "taxonNameBaseTitleCacheIndex", columnNames = { "titleCache" }) })

public abstract class TaxonNameBase<T extends TaxonNameBase<?,?>, S extends INameCacheStrategy> extends IdentifiableEntity<S> implements IReferencedEntity, IParsable, IRelated, IMatchable {

	private static final long serialVersionUID = -4530368639601532116L;

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

	@XmlElement(name = "FullTitleCache")

	@Column(length=330, name="fullTitleCache")

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

	@CacheUpdate(noUpdate ="titleCache")

	@NotEmpty(groups = Level2.class)

	@Size(max = 330)

	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) 

	@Cascade({CascadeType.SAVE_UPDATE})

	@NotNull

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

    @XmlElement(name = "AppendedPhrase")

    @Field(index= org.hibernate.search.annotations.Index.TOKENIZED)

    @CacheUpdate(value ="nameCache")

    @NullOrNotEmpty

    @Size(max = 255)

	private String appendedPhrase;

    @XmlElement(name = "NomenclaturalMicroReference")

    @Field(index= org.hibernate.search.annotations.Index.TOKENIZED)

    @CacheUpdate(noUpdate ="titleCache")

    @NullOrNotEmpty

    @Size(max = 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)

	//TODO @Cascade({CascadeType.DELETE_ORPHAN})

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

	@NotNull

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

    @XmlElement(name = "HomotypicalGroup")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

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

	@Match(MatchMode.IGNORE)

	@CacheUpdate(noUpdate ="titleCache")

	@NotNull

	private HomotypicalGroup homotypicalGroup;

    @XmlElementWrapper(name = "RelationsFromThisName")

    @XmlElement(name = "RelationFromThisName")

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

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

	@Merge(MergeMode.RELATION)

	@NotNull

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

    @XmlElementWrapper(name = "RelationsToThisName")

    @XmlElement(name = "RelationToThisName")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

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

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

	@Merge(MergeMode.RELATION)

	@NotNull

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

    @XmlElementWrapper(name = "NomenclaturalStatuses")

    @XmlElement(name = "NomenclaturalStatus")

    @OneToMany(fetch= FetchType.LAZY)

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

	@NotNull

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

    @XmlElementWrapper(name = "TaxonBases")

    @XmlElement(name = "TaxonBase")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

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

    @NotNull

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

    @XmlElement(name = "Rank")

	@XmlIDREF

	@XmlSchemaType(name = "IDREF")

	@ManyToOne(fetch = FetchType.EAGER)

	@CacheUpdate(value ="nameCache")

	@NotNull

	private Rank rank;

	@XmlElement(name = "NomenclaturalReference")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

	@Cascade({CascadeType.SAVE_UPDATE})

	@CacheUpdate(noUpdate ="titleCache")

	private ReferenceBase nomenclaturalReference;

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

	/** 

	 * Class constructor: creates a new empty taxon name.

	 * 

	 * @see #TaxonNameBase(Rank)

	 * @see #TaxonNameBase(HomotypicalGroup)

	 * @see #TaxonNameBase(Rank, HomotypicalGroup)

	 */

	public TaxonNameBase() {

		super();

	}

	/** 

	 * Class constructor: creates a new taxon name

	 * only containing its {@link Rank rank}.

	 * 

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

	 * @see    		 #TaxonNameBase()

	 * @see    		 #TaxonNameBase(HomotypicalGroup)

	 * @see    		 #TaxonNameBase(Rank, HomotypicalGroup)

	 */

	public TaxonNameBase(Rank rank) {

		this(rank, null);

	}

	/** 

	 * Class constructor: creates a new taxon name

	 * only containing its {@link HomotypicalGroup homotypical group}.

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

	 * belonging to this homotypical group.

	 * 

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

	 * @see    					 #TaxonNameBase()

	 * @see    					 #TaxonNameBase(Rank)

	 * @see    					 #TaxonNameBase(Rank, HomotypicalGroup)

	 */

	public TaxonNameBase(HomotypicalGroup homotypicalGroup) {

		this(null, homotypicalGroup);

	}

	/** 

	 * Class constructor: creates a new taxon name

	 * only containing its {@link Rank rank} and

	 * its {@link HomotypicalGroup homotypical group}.

	 * 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    					 #TaxonNameBase()

	 * @see    					 #TaxonNameBase(Rank)

	 * @see    					 #TaxonNameBase(HomotypicalGroup)

	 */

	public TaxonNameBase(Rank rank, HomotypicalGroup homotypicalGroup) {

		super();

		this.setRank(rank);

		if (homotypicalGroup == null){

			homotypicalGroup = new HomotypicalGroup();

		}

		homotypicalGroup.addTypifiedName(this);

	}

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

//********* METHODS **************************************/

	/**

	 * Returns the boolean value "false" since the components of <i>this</i> taxon name

	 * cannot follow the rules of a corresponding {@link NomenclaturalCode nomenclatural code}

	 * which is not defined for this class. The nomenclature code depends on

	 * the concrete name subclass ({@link BacterialName BacterialName},

	 * {@link BotanicalName BotanicalName}, {@link CultivarPlantName CultivarPlantName},

	 * {@link ZoologicalName ZoologicalName} or {@link ViralName ViralName}) 

	 * to which a taxon name belongs.

	 *  

	 * @return  false

	 */

	@Transient

	public abstract boolean isCodeCompliant();

	public abstract String generateFullTitle();

	@Transient

	public List<Object> getTaggedName(){

		return getCacheStrategy().getTaggedName(this);

	}

	@Transient

	public String getFullTitleCache(){

		if (protectedFullTitleCache){

			return this.fullTitleCache;			

		}

		if (fullTitleCache == null ){

			this.fullTitleCache = getTruncatedCache(generateFullTitle());

		}

		return fullTitleCache;

	}

    public void setFullTitleCache(String fullTitleCache){

		setFullTitleCache(fullTitleCache, PROTECTED);

	}

	public void setFullTitleCache(String fullTitleCache, boolean protectCache){

		fullTitleCache = getTruncatedCache(fullTitleCache);

		this.fullTitleCache = fullTitleCache;

		this.setProtectedFullTitleCache(protectCache);

	}

	public boolean isProtectedFullTitleCache() {

		return protectedFullTitleCache;

	}

	public void setProtectedFullTitleCache(boolean protectedFullTitleCache) {

		this.protectedFullTitleCache = protectedFullTitleCache;

	}

	/** 

	 * Returns the set of all {@link NameRelationship name relationships}

	 * in which <i>this</i> taxon name is involved. A taxon name can be both source

	 * in some name relationships or target in some others.

	 *  

	 * @see    #getRelationsToThisName()

	 * @see    #getRelationsFromThisName()

	 * @see    #addNameRelationship(NameRelationship)

	 * @see    #addRelationshipToName(TaxonNameBase, NameRelationshipType, String)

	 * @see    #addRelationshipFromName(TaxonNameBase, NameRelationshipType, String)

	 */

	@Transient

	public Set<NameRelationship> getNameRelations() {

		Set<NameRelationship> rels = new HashSet<NameRelationship>();

		rels.addAll(getRelationsFromThisName());

		rels.addAll(getRelationsToThisName());

		return rels;

	}

	/**

	 * Creates a new {@link NameRelationship#NameRelationship(TaxonNameBase, TaxonNameBase, NameRelationshipType, String) name relationship} from <i>this</i> taxon name to another taxon name

	 * and adds it both to the set of {@link #getRelationsFromThisName() relations from <i>this</i> taxon name} and

	 * to the set of {@link #getRelationsToThisName() relations to the other taxon name}.

	 * 

	 * @param toName		  the taxon name of the target for this new name relationship

	 * @param type			  the type of this new name relationship

	 * @param ruleConsidered  the string which specifies the rule on which this name relationship is based

	 * @see    				  #getRelationsToThisName()

	 * @see    				  #getNameRelations()

	 * @see    				  #addRelationshipFromName(TaxonNameBase, NameRelationshipType, String)

	 * @see    				  #addNameRelationship(NameRelationship)

	 */

	public void addRelationshipToName(TaxonNameBase toName, NameRelationshipType type, String ruleConsidered){

		addRelationshipToName(toName, type, null, null, ruleConsidered);

		//		NameRelationship rel = new NameRelationship(toName, this, type, ruleConsidered);

	}

	/**

	 * Creates a new {@link NameRelationship#NameRelationship(TaxonNameBase, TaxonNameBase, NameRelationshipType, String) name relationship} from <i>this</i> taxon name to another taxon name

	 * and adds it both to the set of {@link #getRelationsFromThisName() relations from <i>this</i> taxon name} and

	 * to the set of {@link #getRelationsToThisName() relations to the other taxon name}.

	 * 

	 * @param toName		  the taxon name of the target for this new name relationship

	 * @param type			  the type of this new name relationship

	 * @param ruleConsidered  the string which specifies the rule on which this name relationship is based

	 * @see    				  #getRelationsToThisName()

	 * @see    				  #getNameRelations()

	 * @see    				  #addRelationshipFromName(TaxonNameBase, NameRelationshipType, String)

	 * @see    				  #addNameRelationship(NameRelationship)

	 */

public void addRelationshipToName(TaxonNameBase toName, NameRelationshipType type, ReferenceBase citation, String microCitation, String ruleConsidered){

		if (toName == null){

			throw new NullPointerException("Null is not allowed as name for a name relationship");

		}

		NameRelationship rel = new NameRelationship(toName, this, type, citation, microCitation, ruleConsidered);

//		if (type.isBasionymRelation() || type.isReplacedSynonymRelation()){

//			this.getHomotypicalGroup().merge(toName.getHomotypicalGroup());

//		}

	}

	/**

	 * Creates a new {@link NameRelationship#NameRelationship(TaxonNameBase, TaxonNameBase, NameRelationshipType, String) name relationship} from another taxon name to <i>this</i> taxon name

	 * and adds it both to the set of {@link #getRelationsToThisName() relations to <i>this</i> taxon name} and

	 * to the set of {@link #getRelationsFromThisName() relations from the other taxon name}.

	 * 

	 * @param fromName		  the taxon name of the source for this new name relationship

	 * @param type			  the type of this new name relationship

	 * @param ruleConsidered  the string which specifies the rule on which this name relationship is based

	 * @param citation		  the reference in which this relation was described

	 * @param microCitation	  the reference detail for this relation (e.g. page) 

	 * @see    				  #getRelationsFromThisName()

	 * @see    				  #getNameRelations()

	 * @see    				  #addRelationshipToName(TaxonNameBase, NameRelationshipType, String)

	 * @see    				  #addNameRelationship(NameRelationship)

	 */

	public void addRelationshipFromName(TaxonNameBase fromName, NameRelationshipType type, String ruleConsidered){

		fromName.addRelationshipToName(this, type, null, null, ruleConsidered);

//		NameRelationship rel = new NameRelationship(this, fromName, type, ruleConsidered);

	}

	/**

	 * Creates a new {@link NameRelationship#NameRelationship(TaxonNameBase, TaxonNameBase, NameRelationshipType, String) name relationship} from another taxon name to <i>this</i> taxon name

	 * and adds it both to the set of {@link #getRelationsToThisName() relations to <i>this</i> taxon name} and

	 * to the set of {@link #getRelationsFromThisName() relations from the other taxon name}.

	 * 

	 * @param fromName		  the taxon name of the source for this new name relationship

	 * @param type			  the type of this new name relationship

	 * @param ruleConsidered  the string which specifies the rule on which this name relationship is based

	 * @param citation		  the reference in which this relation was described

	 * @param microCitation	  the reference detail for this relation (e.g. page) 

	 * @see    				  #getRelationsFromThisName()

	 * @see    				  #getNameRelations()

	 * @see    				  #addRelationshipToName(TaxonNameBase, NameRelationshipType, String)

	 * @see    				  #addNameRelationship(NameRelationship)

	 */

	public void addRelationshipFromName(TaxonNameBase fromName, NameRelationshipType type, ReferenceBase citation, String microCitation, String ruleConsidered){

		fromName.addRelationshipToName(this, type, citation, microCitation, ruleConsidered);

	}

	/**

	 * Adds an existing {@link NameRelationship name relationship} either to the set of

	 * {@link #getRelationsToThisName() relations to <i>this</i> taxon name} or to the set of

	 * {@link #getRelationsFromThisName() relations from <i>this</i> taxon name}. If neither the

	 * source nor the target of the name relationship match with <i>this</i> taxon name

	 * no addition will be carried out.

	 * 

	 * @param rel  the name relationship to be added to one of <i>this</i> taxon name's name relationships sets

	 * @see    	   #getNameRelations()

	 * @see    	   #addRelationshipToName(TaxonNameBase, NameRelationshipType, String)

	 * @see    	   #addRelationshipFromName(TaxonNameBase, NameRelationshipType, String)

	 */

	protected void addNameRelationship(NameRelationship rel) {

		if (rel!=null && rel.getToName().equals(this)){

			this.relationsToThisName.add(rel);

		}else if(rel!=null && rel.getFromName().equals(this)){

			this.relationsFromThisName.add(rel);			

		}else{

			throw new RuntimeException("NameRelationship is either null or the relationship does not reference this name");

		}

	}

	/** 

	 * Removes one {@link NameRelationship name relationship} from one of both sets of

	 * {@link #getNameRelations() name relationships} in which <i>this</i> taxon name is involved.

	 * The name relationship will also be removed from one of both sets belonging

	 * to the second taxon name involved. Furthermore the fromName and toName

	 * attributes of the name relationship object will be nullified. 

	 *

	 * @param  nameRelation  the name relationship which should be deleted from one of both sets

	 * @see    				 #getNameRelations()

	 */

	public void removeNameRelationship(NameRelationship nameRelation) {

		TaxonNameBase fromName = nameRelation.getFromName();

		TaxonNameBase toName = nameRelation.getToName();

		if (nameRelation != null) {

			nameRelation.setToName(null);

			nameRelation.setFromName(null);

		}

		if (fromName != null) {

			fromName.removeNameRelationship(nameRelation);

		}

		if (toName != null) {

			toName.removeNameRelationship(nameRelation);

		}

		this.relationsToThisName.remove(nameRelation);

		this.relationsFromThisName.remove(nameRelation);

	}

	public void removeRelationToTaxonName(TaxonNameBase toTaxonName) {

		Set<NameRelationship> nameRelationships = new HashSet<NameRelationship>();

//		nameRelationships.addAll(this.getNameRelations());

		nameRelationships.addAll(this.getRelationsFromThisName());

		nameRelationships.addAll(this.getRelationsToThisName());

		for(NameRelationship nameRelationship : nameRelationships) {

			// remove name relationship from this side 

			if (nameRelationship.getFromName().equals(this) && nameRelationship.getToName().equals(toTaxonName)) {

				this.removeNameRelationship(nameRelationship);

			}

		}

	}

	/**

	 * Does exactly the same as the addNameRelationship method provided that

	 * the given relationship is a name relationship.

	 * 

	 * @param relation  the relationship to be added to one of <i>this</i> taxon name's name relationships sets

	 * @see    	   		#addNameRelationship(NameRelationship)

	 * @see    	   		#getNameRelations()

	 * @see    	   		NameRelationship

	 * @see    	   		eu.etaxonomy.cdm.model.common.RelationshipBase

	 */

	public void addRelationship(RelationshipBase relation) {

		if (relation instanceof NameRelationship){

			addNameRelationship((NameRelationship)relation);

			NameRelationshipType type = (NameRelationshipType)relation.getType();

			if (type != null && ( type.isBasionymRelation() || type.isReplacedSynonymRelation() ) ){

				TaxonNameBase fromName = ((NameRelationship)relation).getFromName();

				TaxonNameBase toName = ((NameRelationship)relation).getToName();

				fromName.mergeHomotypicGroups(toName);

			}		

		}else{

			logger.warn("Relationship not of type NameRelationship!");

			throw new IllegalArgumentException("Relationship not of type NameRelationship");

		}

	}

	/** 

	 * Returns the set of all {@link NameRelationship name relationships}

	 * in which <i>this</i> taxon name is involved as a source.

	 *  

	 * @see    #getNameRelations()

	 * @see    #getRelationsToThisName()

	 * @see    #addRelationshipFromName(TaxonNameBase, NameRelationshipType, String)

	 */

	public Set<NameRelationship> getRelationsFromThisName() {

		if(relationsFromThisName == null) {

			this.relationsFromThisName = new HashSet<NameRelationship>();

		}

		return relationsFromThisName;

	}

	/** 

	 * Returns the set of all {@link NameRelationship name relationships}

	 * in which <i>this</i> taxon name is involved as a target.

	 *  

	 * @see    #getNameRelations()

	 * @see    #getRelationsFromThisName()

	 * @see    #addRelationshipToName(TaxonNameBase, NameRelationshipType, String)

	 */

	public Set<NameRelationship> getRelationsToThisName() {

		if(relationsToThisName == null) {

			this.relationsToThisName = new HashSet<NameRelationship>();

		}

		return relationsToThisName;

	}

	/** 

	 * Returns the set of {@link NomenclaturalStatus nomenclatural status} assigned

	 * to <i>this</i> taxon name according to its corresponding nomenclature code.

	 * This includes the {@link NomenclaturalStatusType type} of the nomenclatural status

	 * and the nomenclatural code rule considered.

	 *

	 * @see     NomenclaturalStatus

	 * @see     NomenclaturalStatusType

	 */

	public Set<NomenclaturalStatus> getStatus() {

		if(status == null) {

			this.status = new HashSet<NomenclaturalStatus>();

		}

		return status;

	}

	/** 

	 * Adds a new {@link NomenclaturalStatus nomenclatural status}

	 * to <i>this</i> taxon name's set of nomenclatural status.

	 *

	 * @param  nomStatus  the nomenclatural status to be added

	 * @see 			  #getStatus()

	 */

	public void addStatus(NomenclaturalStatus nomStatus) {

		this.status.add(nomStatus);

	}

	/** 

	 * Removes one element from the set of nomenclatural status of <i>this</i> taxon name.

	 * Type and ruleConsidered attributes of the nomenclatural status object

	 * will be nullified.

	 *

	 * @param  nomStatus  the nomenclatural status of <i>this</i> taxon name which should be deleted

	 * @see     		  #getStatus()

	 */

	public void removeStatus(NomenclaturalStatus nomStatus) {

		//TODO to be implemented?

		logger.warn("not yet fully implemented?");

		this.status.remove(nomStatus);

	}

	/**

	 * Indicates whether <i>this</i> taxon name is a {@link NameRelationshipType#BASIONYM() basionym}

	 * or a {@link NameRelationshipType#REPLACED_SYNONYM() replaced synonym}

	 * of any other taxon name. Returns "true", if a basionym or a replaced 

	 * synonym {@link NameRelationship relationship} from <i>this</i> taxon name to another taxon name exists,

	 * false otherwise (also in case <i>this</i> taxon name is the only one in the

	 * homotypical group).

	 */

	@Transient

	public boolean isOriginalCombination(){

		Set<NameRelationship> relationsFromThisName = this.getRelationsFromThisName();

		for (NameRelationship relation : relationsFromThisName) {

			if (relation.getType().isBasionymRelation() ||

					relation.getType().isReplacedSynonymRelation()) {

				return true;

			}

		}

		return false;

	}

	/**

	 * Returns the taxon name which is the {@link NameRelationshipType#BASIONYM() basionym} of <i>this</i> taxon name.

	 * The basionym of a taxon name is its epithet-bringing synonym.

	 * For instance <i>Pinus abies</i> L. was published by Linnaeus and the botanist

	 * Karsten transferred later <i>this</i> taxon to the genus Picea. Therefore,

	 * <i>Pinus abies</i> L. is the basionym of the new combination <i>Picea abies</i> (L.) H. Karst.

	 * 

	 * If more than one basionym exists one is choosen at radom.

	 * 

	 * If no basionym exists null is returned.

	 */

	@Transient

	public TaxonNameBase getBasionym(){

		Set<TaxonNameBase> basionyms = getBasionyms();

		if (basionyms.size() == 0){

			return null;

		}else{

			return basionyms.iterator().next();

		}

	}

	/**

	 * Returns the set of taxon names which are the {@link NameRelationshipType#BASIONYM() basionyms} of <i>this</i> taxon name.

	 * The basionym of a taxon name is its epithet-bringing synonym.

	 * For instance <i>Pinus abies</i> L. was published by Linnaeus and the botanist

	 * Karsten transferred later <i>this</i> taxon to the genus Picea. Therefore,

	 * <i>Pinus abies</i> L. is the basionym of the new combination <i>Picea abies</i> (L.) H. Karst.

	 */

	@Transient

	public Set<TaxonNameBase> getBasionyms(){

		Set<TaxonNameBase> result = new HashSet<TaxonNameBase>();

		Set<NameRelationship> rels = this.getRelationsToThisName();

		for (NameRelationship rel : rels){

			if (rel.getType().isBasionymRelation()){

				TaxonNameBase basionym = rel.getFromName();

				result.add(basionym);

			}

		}

		return result;

	}

	/**

	 * Assigns a taxon name as {@link NameRelationshipType#BASIONYM() basionym} of <i>this</i> taxon name.

	 * The basionym {@link NameRelationship relationship} will be added to <i>this</i> taxon name

	 * and to the basionym. The basionym cannot have itself a basionym.

	 * The {@link HomotypicalGroup homotypical groups} of <i>this</i> taxon name and of the basionym

	 * will be {@link HomotypicalGroup#merge(HomotypicalGroup) merged}.

	 * 

	 * @param  basionym		the taxon name to be set as the basionym of <i>this</i> taxon name

	 * @see  				#getBasionym()

	 * @see  				#addBasionym(TaxonNameBase, String)

	 */

	public void addBasionym(T basionym){

		addBasionym(basionym, null, null, null);

	}

	/**

	 * Assigns a taxon name as {@link NameRelationshipType#BASIONYM() basionym} of <i>this</i> taxon name

	 * and keeps the nomenclatural rule considered for it. The basionym

	 * {@link NameRelationship relationship} will be added to <i>this</i> taxon name and to the basionym.

	 * The basionym cannot have itself a basionym.

	 * The {@link HomotypicalGroup homotypical groups} of <i>this</i> taxon name and of the basionym

	 * will be {@link HomotypicalGroup#merge(HomotypicalGroup) merged}.

	 * 

	 * @param  basionym			the taxon name to be set as the basionym of <i>this</i> taxon name

	 * @param  ruleConsidered	the string identifying the nomenclatural rule

	 * @see  					#getBasionym()

	 * @see  					#addBasionym(TaxonNameBase)

	 */

	public void addBasionym(T basionym, ReferenceBase citation, String microcitation, String ruleConsidered){

		if (basionym != null){

			basionym.addRelationshipToName(this, NameRelationshipType.BASIONYM(), citation, microcitation, ruleConsidered);

		}

	}

	/**

	 * Assigns a taxon name as {@link NameRelationshipType#REPLACED_SYNONYM() replaced synonym} of <i>this</i> taxon name

	 * and keeps the nomenclatural rule considered for it. The replaced synonym

	 * {@link NameRelationship relationship} will be added to <i>this</i> taxon name and to the replaced synonym.

	 * The {@link HomotypicalGroup homotypical groups} of <i>this</i> taxon name and of the replaced synonym

	 * will be {@link HomotypicalGroup#merge(HomotypicalGroup) merged}.

	 * 

	 * @param  basionym			the taxon name to be set as the basionym of <i>this</i> taxon name

	 * @param  ruleConsidered	the string identifying the nomenclatural rule

	 * @see  					#getBasionym()

	 * @see  					#addBasionym(TaxonNameBase)

	 */

	//TODO: Check if true: The replaced synonym cannot have itself a replaced synonym (?).

	public void addReplacedSynonym(T replacedSynonym, ReferenceBase citation, String microcitation, String ruleConsidered){

		if (replacedSynonym != null){

			replacedSynonym.addRelationshipToName(this, NameRelationshipType.REPLACED_SYNONYM(), citation, microcitation, ruleConsidered);

		}

	}

	/** 

	 * Removes the {@link NameRelationshipType#BASIONYM() basionym} {@link NameRelationship relationship} from the set of

	 * {@link #getRelationsToThisName() name relationships to} <i>this</i> taxon name. The same relationhip will be

	 * removed from the set of {@link #getRelationsFromThisName() name relationships from} the taxon name

	 * previously used as basionym.

	 *

	 * @see   #getBasionym()

	 * @see   #addBasionym(TaxonNameBase)

	 */

	public void removeBasionyms(){

		Set<NameRelationship> removeRelations = new HashSet<NameRelationship>();

		for (NameRelationship nameRelation : this.getRelationsToThisName()){

			if (nameRelation.getType().isBasionymRelation()){

				removeRelations.add(nameRelation);

			}

		}

		// Removing relations from a set through which we are iterating causes a

		// ConcurrentModificationException. Therefore, we delete the targeted

		// relations in a second step.

		for (NameRelationship relation : removeRelations){

			this.removeNameRelationship(relation);

		}

	}

	/** 

	 * Returns the taxonomic {@link Rank rank} of <i>this</i> taxon name.

	 *

	 * @see 	Rank

	 */

	public Rank getRank(){

		return this.rank;

	}

	/**

	 * @see  #getRank()

	 */

	public void setRank(Rank rank){

		this.rank = rank;

	}

	/** 

	 * Returns the {@link eu.etaxonomy.cdm.model.reference.INomenclaturalReference nomenclatural reference} of <i>this</i> taxon name.

	 * The nomenclatural reference is here meant to be the one publication

	 * <i>this</i> taxon name was originally published in while fulfilling the formal

	 * requirements as specified by the corresponding {@link NomenclaturalCode nomenclatural code}.

	 *

	 * @see 	eu.etaxonomy.cdm.model.reference.INomenclaturalReference

	 * @see 	eu.etaxonomy.cdm.model.reference.ReferenceBase

	 */

	public INomenclaturalReference getNomenclaturalReference(){

		return this.nomenclaturalReference;

	}

	/**

	 * Assigns a {@link eu.etaxonomy.cdm.model.reference.INomenclaturalReference nomenclatural reference} to <i>this</i> taxon name.

	 * The corresponding {@link eu.etaxonomy.cdm.model.reference.ReferenceBase.isNomenclaturallyRelevant nomenclaturally relevant flag} will be set to true

	 * as it is obviously used for nomenclatural purposes.

	 *

	 * @throws IllegalArgumentException if parameter <code>nomenclaturalReference</code> is not assignable from {@link INomenclaturalReference}

	 * @see  #getNomenclaturalReference()

	 */

	public void setNomenclaturalReference(INomenclaturalReference nomenclaturalReference){

		if(nomenclaturalReference != null){

			if(!INomenclaturalReference.class.isAssignableFrom(nomenclaturalReference.getClass())){

				throw new IllegalArgumentException("Parameter nomenclaturalReference is not assignable from INomenclaturalReference");

			}

			this.nomenclaturalReference = (ReferenceBase)nomenclaturalReference;

		} else {

			this.nomenclaturalReference = null;

		}

	}

	/** 

	 * Returns the appended phrase string assigned to <i>this</i> taxon name.

	 * The appended phrase is a non-atomised addition to a name. It is

	 * not ruled by a nomenclatural code.

	 */

	public String getAppendedPhrase(){

		return this.appendedPhrase;

	}

	/**

	 * @see  #getAppendedPhrase()

	 */

	public void setAppendedPhrase(String appendedPhrase){

		this.appendedPhrase = appendedPhrase;

	}

	/** 

	 * Returns the details string of the {@link #getNomenclaturalReference() nomenclatural reference} assigned

	 * to <i>this</i> taxon name. The details describe the exact localisation within

	 * the publication used as nomenclature reference. These are mostly

	 * (implicitly) pages but can also be figures or tables or any other

	 * element of a publication. A nomenclatural micro reference (details)

	 * requires the existence of a nomenclatural reference.

	 */

	//Details of the nomenclatural reference (protologue). 

	public String getNomenclaturalMicroReference(){

		return this.nomenclaturalMicroReference;

	}

	/**

	 * @see  #getNomenclaturalMicroReference()

	 */

	public void setNomenclaturalMicroReference(String nomenclaturalMicroReference){

		this.nomenclaturalMicroReference = nomenclaturalMicroReference;

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#getHasProblem()

	 */

	public int getParsingProblem(){

		return this.parsingProblem;

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#setHasProblem(int)

	 */

	public void setParsingProblem(int parsingProblem){

		this.parsingProblem = parsingProblem;

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#addProblem(eu.etaxonomy.cdm.strategy.parser.NameParserWarning)

	 */

	public void addParsingProblem(ParserProblem problem){

		parsingProblem = ParserProblem.addProblem(parsingProblem, problem);

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#removeParsingProblem(eu.etaxonomy.cdm.strategy.parser.ParserProblem)

	 */

	public void removeParsingProblem(ParserProblem problem) {

		parsingProblem = ParserProblem.removeProblem(parsingProblem, problem);

	}

	/**

	 * @param warnings

	 */

	public void addParsingProblems(int problems){

		parsingProblem = ParserProblem.addProblems(parsingProblem, problems);

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#hasProblem()

	 */

	public boolean hasProblem(){

		return parsingProblem != 0;

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#hasProblem(eu.etaxonomy.cdm.strategy.parser.ParserProblem)

	 */

	public boolean hasProblem(ParserProblem problem) {

		return getParsingProblems().contains(problem);

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#problemStarts()

	 */

	public int getProblemStarts(){

		return this.problemStarts;

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#setProblemStarts(int)

	 */

	public void setProblemStarts(int start) {

		this.problemStarts = start;

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#problemEnds()

	 */

	public int getProblemEnds(){

		return this.problemEnds;

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IParsable#setProblemEnds(int)

	 */

	public void setProblemEnds(int end) {

		this.problemEnds = end;

	}

//*********************** TYPE DESIGNATION *********************************************//	

	/** 

	 * Returns the set of {@link TypeDesignationBase type designations} assigned

	 * to <i>this</i> taxon name.

	 * @see     NameTypeDesignation

	 * @see     SpecimenTypeDesignation

	 */

	public Set<TypeDesignationBase> getTypeDesignations() {

		if(typeDesignations == null) {

			this.typeDesignations = new HashSet<TypeDesignationBase>();

		}

		return typeDesignations;

	}

	/** 

	 * Removes one element from the set of {@link TypeDesignationBase type designations} assigned to

	 * <i>this</i> taxon name. The type designation itself will be nullified.

	 *

	 * @param  typeDesignation  the type designation which should be deleted

	 */

	public void removeTypeDesignation(TypeDesignationBase typeDesignation) {

		logger.warn("not yet fully implemented: nullify the specimen type designation itself?");

		this.typeDesignations.remove(typeDesignation);

	}

	/** 

	 * Returns the set of {@link SpecimenTypeDesignation specimen type designations} assigned

	 * to <i>this</i> taxon name. The {@link Rank rank} of <i>this</i> taxon name is generally

	 * "species" or below. The specimen type designations include all the

	 * specimens on which the typification of this name is based (which are

	 * exclusively used to typify taxon names belonging to the same

	 * {@link HomotypicalGroup homotypical group} to which <i>this</i> taxon name

	 * belongs) and eventually the status of these designations.

	 *

	 * @see     SpecimenTypeDesignation

	 * @see     NameTypeDesignation

	 * @see     HomotypicalGroup

	 */

	@Transient

	public Set<SpecimenTypeDesignation> getSpecimenTypeDesignationsOfHomotypicalGroup() {

		return this.getHomotypicalGroup().getSpecimenTypeDesignations();

	}

//*********************** NAME TYPE DESIGNATION *********************************************//	

	/** 

	 * Returns the set of {@link NameTypeDesignation name type designations} assigned

	 * to <i>this</i> taxon name the rank of which must be above "species".

	 * The name type designations include all the taxon names used to typify

	 * <i>this</i> taxon name and eventually the rejected or conserved status

	 * of these designations.

	 *

	 * @see     NameTypeDesignation

	 * @see     SpecimenTypeDesignation

	 */

	@Transient

	public Set<NameTypeDesignation> getNameTypeDesignations() {