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

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

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

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

import eu.etaxonomy.cdm.model.name.HomotypicalGroup;

import eu.etaxonomy.cdm.model.name.TaxonNameBase;

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

import eu.etaxonomy.cdm.strategy.cache.common.IIdentifiableEntityCacheStrategy;

import eu.etaxonomy.cdm.strategy.cache.taxon.TaxonBaseDefaultCacheStrategy;

import org.apache.log4j.Logger;

import org.hibernate.annotations.Cascade;

import org.hibernate.annotations.CascadeType;

import org.hibernate.envers.Audited;

import org.hibernate.search.annotations.Indexed;

import org.springframework.beans.factory.annotation.Configurable;

import org.springframework.util.ReflectionUtils;

import java.lang.reflect.Field;

import java.util.ArrayList;

import java.util.Collections;

import java.util.HashMap;

import java.util.HashSet;

import java.util.Iterator;

import java.util.List;

import java.util.Map;

import java.util.Set;

import javax.persistence.Entity;

import javax.persistence.FetchType;

import javax.persistence.ManyToOne;

import javax.persistence.OneToMany;

import javax.persistence.Transient;

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.envers.Audited;

import org.hibernate.search.annotations.Indexed;

import org.springframework.util.ReflectionUtils;

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

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

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

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

import eu.etaxonomy.cdm.model.name.HomotypicalGroup;

import eu.etaxonomy.cdm.model.name.TaxonNameBase;

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

/**

 * The class for "accepted/correct" {@link TaxonBase taxa} (only these taxa according to

 * the opinion of the {@link eu.etaxonomy.cdm.model.reference.ReferenceBase reference} can build a taxonomic tree).

 * An {@link java.lang.Iterable interface} is supported to iterate through taxonomic children.<BR>

 * Splitting taxa in "accepted/correct" and {@link Synonym "synonyms"} makes it easier to handle

 * particular relationships between ("accepted/correct") taxa on the one hand

 * and between ("synonym") taxa and ("accepted/correct") taxa on the other.

 * 

 * @author m.doering

 * @version 1.0

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

 */

@XmlAccessorType(XmlAccessType.FIELD)

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

    "taxonomicParentCache",

    "taxonNodes",

    "taxonomicChildrenCount",

    "synonymRelations",

    "relationsFromThisTaxon",

    "relationsToThisTaxon",

    "descriptions"

})

@XmlRootElement(name = "Taxon")

@Entity

@Indexed(index = "eu.etaxonomy.cdm.model.taxon.TaxonBase")

@Audited

@Configurable

public class Taxon extends TaxonBase<IIdentifiableEntityCacheStrategy<Taxon>> implements Iterable<Taxon>, IRelated<RelationshipBase>{

	private static final long serialVersionUID = -584946869762749006L;

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

	@XmlElementWrapper(name = "Descriptions")

	@XmlElement(name = "Description")

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

	@Cascade({CascadeType.SAVE_UPDATE})

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

	// all related synonyms

	@XmlElementWrapper(name = "SynonymRelations")

	@XmlElement(name = "SynonymRelationship")

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

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

	private Set<SynonymRelationship> synonymRelations = new HashSet<SynonymRelationship>();

	// all taxa relations with rel.fromTaxon==this

	@XmlElementWrapper(name = "RelationsFromThisTaxon")

	@XmlElement(name = "FromThisTaxonRelationship")

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

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

	private Set<TaxonRelationship> relationsFromThisTaxon = new HashSet<TaxonRelationship>();

	// all taxa relations with rel.toTaxon==this

	@XmlElementWrapper(name = "RelationsToThisTaxon")

	@XmlElement(name = "ToThisTaxonRelationship")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

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

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

	private Set<TaxonRelationship> relationsToThisTaxon = new HashSet<TaxonRelationship>();

	@XmlAttribute(name= "taxonStatusUnknown")

	private boolean taxonStatusUnknown = false;

	// shortcut to the taxonomicIncluded (parent) taxon. Managed by the taxonRelations setter

	@XmlElement(name = "TaxonomicParentCache")

	@XmlIDREF

	@XmlSchemaType(name = "IDREF")

	@ManyToOne(fetch = FetchType.LAZY)

	private Taxon taxonomicParentCache;

	@XmlElementWrapper(name = "taxonNodes")

	@XmlElement(name = "taxonNode")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

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

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

	private Set<TaxonNode> taxonNodes = new HashSet<TaxonNode>();

	//cached number of taxonomic children

	@XmlElement(name = "TaxonomicChildrenCount")

	private int taxonomicChildrenCount;

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

	//TODO should be private, but still produces Spring init errors

	@Deprecated

	public Taxon(){

		this.cacheStrategy = new TaxonBaseDefaultCacheStrategy<Taxon>();

	}

	/** 

	 * Class constructor: creates a new (accepted/correct) taxon instance with

	 * the {@link eu.etaxonomy.cdm.model.name.TaxonNameBase taxon name} used and the {@link eu.etaxonomy.cdm.model.reference.ReferenceBase reference}

	 * using it.

	 * 

	 * @param  taxonNameBase	the taxon name used

	 * @param  sec				the reference using the taxon name

	 * @see    					TaxonBase#TaxonBase(TaxonNameBase, ReferenceBase)

	 */

	public Taxon(TaxonNameBase taxonNameBase, ReferenceBase sec){

		super(taxonNameBase, sec);

		this.cacheStrategy = new TaxonBaseDefaultCacheStrategy<Taxon>();

	}

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

	/** 

	 * Creates a new (accepted/correct) taxon instance with

	 * the {@link eu.etaxonomy.cdm.model.name.TaxonNameBase taxon name} used and the {@link eu.etaxonomy.cdm.model.reference.ReferenceBase reference}

	 * using it.

	 * 

	 * @param  taxonNameBase	the taxon name used

	 * @param  sec				the reference using the taxon name

	 * @see    					#Taxon(TaxonNameBase, ReferenceBase)

	 */

	public static Taxon NewInstance(TaxonNameBase taxonNameBase, ReferenceBase sec){

		Taxon result = new Taxon(taxonNameBase, sec);

		return result;

	}

	/** 

	 * Creates a new taxon instance with an unknown status (accepted/synonym) and with

	 * the {@link eu.etaxonomy.cdm.model.name.TaxonNameBase taxon name} used and the {@link eu.etaxonomy.cdm.model.reference.ReferenceBase reference}

	 * using it.

	 * 

	 * @param  taxonNameBase	the taxon name used

	 * @param  sec				the reference using the taxon name

	 * @see    					#Taxon(TaxonNameBase, ReferenceBase)

	 */

	public static Taxon NewUnknownStatusInstance(TaxonNameBase taxonNameBase, ReferenceBase sec){

		Taxon result = new Taxon(taxonNameBase, sec);

		result.setTaxonStatusUnknown(true);

		return result;

	}

	/** 

	 * Returns the set of {@link eu.etaxonomy.cdm.model.description.TaxonDescription taxon descriptions}

	 * concerning <i>this</i> taxon.

	 * 

	 * @see #removeDescription(TaxonDescription)

	 * @see #addDescription(TaxonDescription)

	 * @see eu.etaxonomy.cdm.model.description.TaxonDescription#getTaxon()

	 */

	public Set<TaxonDescription> getDescriptions() {

		return descriptions;

	}

	/** 

	 * Adds a new {@link eu.etaxonomy.cdm.model.description.TaxonDescription taxon description} to the set

	 * of taxon descriptions assigned to <i>this</i> (accepted/correct) taxon.

	 * Due to bidirectionality the content of the {@link eu.etaxonomy.cdm.model.description.TaxonDescription#getTaxon() taxon attribute} of the

	 * taxon description itself will be replaced with <i>this</i> taxon. The taxon

	 * description will also be removed from the set of taxon descriptions

	 * assigned to its previous taxon. 

	 *

	 * @param  description	the taxon description to be added for <i>this</i> taxon

	 * @see     		  	#getDescriptions()

	 * @see     		  	#removeDescription(TaxonDescription)

	 * @see 			  	eu.etaxonomy.cdm.model.description.TaxonDescription#getTaxon()

	 */

	public void addDescription(TaxonDescription description) {

		if (description.getTaxon() != null){

			description.getTaxon().removeDescription(description);

		}

		Field field = ReflectionUtils.findField(TaxonDescription.class, "taxon", Taxon.class);

		ReflectionUtils.makeAccessible(field);

		ReflectionUtils.setField(field, description, this);

		descriptions.add(description);

	}

	/** 

	 * Removes one element from the set of {@link eu.etaxonomy.cdm.model.description.TaxonDescription taxon descriptions} assigned

	 * to <i>this</i> (accepted/correct) taxon. Due to bidirectionality the content of

	 * the {@link eu.etaxonomy.cdm.model.description.TaxonDescription#getTaxon() taxon attribute} of the taxon description

	 * itself will be set to "null".

	 *

	 * @param  description  the taxon description which should be removed

	 * @see     		  	#getDescriptions()

	 * @see     		  	#addDescription(TaxonDescription)

	 * @see 			  	eu.etaxonomy.cdm.model.description.TaxonDescription#getTaxon()

	 */

	public void removeDescription(TaxonDescription description) {

		//description.setTaxon(null) for not visible method

		Field field = ReflectionUtils.findField(TaxonDescription.class, "taxon", Taxon.class);

		ReflectionUtils.makeAccessible(field);

		ReflectionUtils.setField(field, description, null);

		descriptions.remove(description);

	}

	public Set<TaxonNode> getTaxonNodes() {

		return taxonNodes;

	}

	//	protected void setTaxonNodes(Set<TaxonNode> taxonNodes) {

//		this.taxonNodes = taxonNodes;

//	}

	protected void addTaxonNode(TaxonNode taxonNode){

		taxonNodes.add(taxonNode);

	}

	protected void removeTaxonNode(TaxonNode taxonNode){

		taxonNodes.remove(taxonNode);

	}

	/** 

	 * Returns the set of all {@link SynonymRelationship synonym relationships}

	 * in which <i>this</i> ("accepted/correct") taxon is involved. <i>This</i> taxon can only

	 * be the target of these synonym relationships. 

	 *  

	 * @see    #addSynonymRelation(SynonymRelationship)

	 * @see    #removeSynonymRelation(SynonymRelationship)

	 * @see    #getSynonyms()

	 */

	public Set<SynonymRelationship> getSynonymRelations() {

		return synonymRelations;

	}

	/**

	 * Adds an existing {@link SynonymRelationship synonym relationship} to the set of

	 * {@link #getSynonymRelations() synonym relationships} assigned to <i>this</i> taxon. If

	 * the target of the synonym relationship does not match with <i>this</i> taxon

	 * no addition will be carried out.

	 * 

	 * @param synonymRelation	the synonym relationship to be added to <i>this</i> taxon's

	 * 							synonym relationships set

	 * @see    	   				#getSynonymRelations()

	 * @see    	   				#addSynonym(Synonym, SynonymRelationshipType)

	 * @see    	   				#addSynonym(Synonym, SynonymRelationshipType, ReferenceBase, String)

	 * @see    	   				#addSynonymName(TaxonNameBase, SynonymRelationshipType)

	 * @see    	   				#addSynonymName(TaxonNameBase, SynonymRelationshipType, ReferenceBase, String)

	 */

	protected void addSynonymRelation(SynonymRelationship synonymRelation) {

		this.synonymRelations.add(synonymRelation);

	}

	/** 

	 * Removes one element from the set of {@link SynonymRelationship synonym relationships} assigned

	 * to <i>this</i> (accepted/correct) taxon. Due to bidirectionality the given

	 * synonym relationship will also be removed from the set of synonym

	 * relationships assigned to the {@link Synonym#getSynonymRelations() synonym} involved in the

	 * relationship. Furthermore the content of

	 * the {@link SynonymRelationship#getAcceptedTaxon() accepted taxon} attribute and of the

	 * {@link SynonymRelationship#getSynonym() synonym} attribute within the synonym relationship

	 * itself will be set to "null".

	 *

	 * @param  synonymRelation  the synonym relationship which should be deleted

	 * @see     		  		#getSynonymRelations()

	 * @see     		  		#addSynonymRelation(SynonymRelationship)

	 * @see 			  		#removeSynonym(Synonym)

	 */

	public void removeSynonymRelation(SynonymRelationship synonymRelation) {

		synonymRelation.setAcceptedTaxon(null);

		Synonym synonym = synonymRelation.getSynonym();

		if (synonym != null){

			synonymRelation.setSynonym(null);

			synonym.removeSynonymRelation(synonymRelation);

		}

		this.synonymRelations.remove(synonymRelation);

	}

	/** 

	 * Returns the set of all {@link TaxonRelationship taxon relationships}

	 * between two taxa in which <i>this</i> taxon is involved as a source.

	 *  

	 * @see    #getRelationsToThisTaxon()

	 * @see    #getTaxonRelations()

	 */

	public Set<TaxonRelationship> getRelationsFromThisTaxon() {

		return relationsFromThisTaxon;

	}

	/** 

	 * Returns the set of all {@link TaxonRelationship taxon relationships}

	 * between two taxa in which <i>this</i> taxon is involved as a target.

	 *  

	 * @see    #getRelationsFromThisTaxon()

	 * @see    #getTaxonRelations()

	 */

	public Set<TaxonRelationship> getRelationsToThisTaxon() {

		return relationsToThisTaxon;

	}

	/** 

	 * @see    #getRelationsToThisTaxon()

	 */

	protected void setRelationsToThisTaxon(Set<TaxonRelationship> relationsToThisTaxon) {

		this.relationsToThisTaxon = relationsToThisTaxon;

	}

	/** 

	 * Returns the set of all {@link TaxonRelationship taxon relationships}

	 * between two taxa in which <i>this</i> taxon is involved either as a source or

	 * as a target.

	 *  

	 * @see    #getRelationsFromThisTaxon()

	 * @see    #getRelationsToThisTaxon()

	 */

	@Transient

	public Set<TaxonRelationship> getTaxonRelations() {

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

		rels.addAll(getRelationsToThisTaxon());

		rels.addAll(getRelationsFromThisTaxon());

		return rels;

	}

	/** 

	 * Removes one {@link TaxonRelationship taxon relationship} from one of both sets of

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

	 * either as a {@link #getRelationsFromThisTaxon() source} or as a {@link #getRelationsToThisTaxon() target}.

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

	 * belonging to the second taxon involved. Furthermore the inherited RelatedFrom and

	 * RelatedTo attributes of the given taxon relationship will be nullified.<P>

	 * If the taxon relationship concerns the taxonomic tree possible

	 * modifications of the {@link #getTaxonomicParent() parent taxon} or of the number of

	 * {@link #getTaxonomicChildrenCount() childrens} will be stored.

	 *

	 * @param  rel  the taxon relationship which should be removed from one

	 * 				of both sets

	 * @see    		#getTaxonRelations()

	 * @see    	    #getTaxonomicParent()

	 * @see    	    #getTaxonomicChildrenCount()

	 * @see    		eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom()

	 * @see    		eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedTo()

	 * 

	 */

	public void removeTaxonRelation(TaxonRelationship rel) {

		logger.warn("remove TaxonRelation");  //for testing only 

		this.relationsToThisTaxon.remove(rel);

		this.relationsFromThisTaxon.remove(rel);

		Taxon fromTaxon = rel.getFromTaxon();

		Taxon toTaxon = rel.getToTaxon();

		// check if this removes the taxonomical parent. If so, also remove shortcut to the higher taxon

		if (rel.getType().equals(TaxonRelationshipType.TAXONOMICALLY_INCLUDED_IN()) ){

			if (fromTaxon != null && fromTaxon.equals(this)){

				this.taxonomicParentCache = null;

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

				this.setTaxonomicChildrenCount(computeTaxonomicChildrenCount());	

			}

		}

		//delete Relationship from other related Taxon

		if (fromTaxon != null && fromTaxon != this){

			rel.setToTaxon(null);  //remove this Taxon from relationship

			fromTaxon.removeTaxonRelation(rel);

		}

		if (toTaxon != null && toTaxon != this){

			rel.setFromTaxon(null); //remove this Taxon from relationship

			toTaxon.removeTaxonRelation(rel);

		}

	}

	/**

	 * Adds an existing {@link TaxonRelationship taxon relationship} either to the set of

	 * {@link #getRelationsToThisTaxon() taxon relationships to <i>this</i> taxon} or to the set of

	 * {@link #getRelationsFromThisTaxon() taxon relationships from <i>this</i> taxon}. If neither the

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

	 * no addition will be carried out. The taxon relationship will also be

	 * added to the second taxon involved in the given relationship.<P>

	 * If the taxon relationship concerns the taxonomic tree possible

	 * modifications of the {@link #getTaxonomicParent() parent taxon} or of the number of

	 * {@link #getTaxonomicChildrenCount() childrens} will be stored.

	 * 

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

	 * @see    	   #addTaxonRelation(Taxon, TaxonRelationshipType, ReferenceBase, String)

	 * @see    	   #getTaxonRelations()

	 * @see    	   #getRelationsFromThisTaxon()

	 * @see    	   #getRelationsToThisTaxon()

	 * @see    	   #getTaxonomicParent()

	 * @see    	   #getTaxonomicChildrenCount()

	 */

	public void addTaxonRelation(TaxonRelationship rel) {

		if (rel!=null && rel.getType()!=null && !getTaxonRelations().contains(rel) ){

			Taxon toTaxon=rel.getToTaxon();

			Taxon fromTaxon=rel.getFromTaxon();

			if ( this.equals(toTaxon) || this.equals(fromTaxon) ){

				if (this.equals(fromTaxon)){

					relationsFromThisTaxon.add(rel);

					// also add relation to other taxon object

					if (toTaxon!=null){

						toTaxon.addTaxonRelation(rel);

					}

					// check if this sets the taxonomical parent. If so, remember a shortcut to this taxon

					if (rel.getType().equals(TaxonRelationshipType.TAXONOMICALLY_INCLUDED_IN()) && toTaxon!=null ){

						this.taxonomicParentCache = toTaxon;

					}

				}else if (this.equals(toTaxon)){

					relationsToThisTaxon.add(rel);

					// also add relation to other taxon object

					if (fromTaxon!=null){

						fromTaxon.addTaxonRelation(rel);

					}

					if (rel.getType().equals(TaxonRelationshipType.TAXONOMICALLY_INCLUDED_IN()) && fromTaxon!=null ){

						this.taxonomicChildrenCount++;

					}

				}

			}

		}	

	}

	/* (non-Javadoc)

	 * @see eu.etaxonomy.cdm.model.common.IRelated#addRelationship(eu.etaxonomy.cdm.model.common.RelationshipBase)

	 */

	@Deprecated //for inner use by RelationshipBase only

	public void addRelationship(RelationshipBase rel){

		if (rel instanceof TaxonRelationship){

			addTaxonRelation((TaxonRelationship)rel);

		}else if (rel instanceof SynonymRelationship){

			addSynonymRelation((SynonymRelationship)rel);

		}else{

			throw new ClassCastException("Wrong Relationsship type for Taxon.addRelationship");

		}

	}

	/**

	 * Creates a new {@link TaxonRelationship taxon relationship} instance where <i>this</i> taxon

	 * plays the source role and adds it to the set of

	 * {@link #getRelationsFromThisTaxon() "taxon relationships from"} belonging to <i>this</i> taxon.

	 * The taxon relationship will also be added to the set of taxon

	 * relationships to the second taxon involved in the created relationship.<P>

	 * If the taxon relationship concerns the taxonomic tree possible

	 * modifications of the {@link #getTaxonomicParent() parent taxon} or of the number of

	 * {@link #getTaxonomicChildrenCount() childrens} will be stored.

	 * 

	 * @param toTaxon		the taxon which plays the target role in the new taxon relationship

	 * @param type			the taxon relationship type for the new taxon relationship

	 * @param citation		the reference source for the new taxon relationship

	 * @param microcitation	the string with the details describing the exact localisation within the reference

	 * @see    	   			#addTaxonRelation(TaxonRelationship)

	 * @see    	   			#getTaxonRelations()

	 * @see    	   			#getRelationsFromThisTaxon()

	 * @see    	   			#getRelationsToThisTaxon()

	 * @see    	   			#getTaxonomicParent()

	 * @see    	   			#getTaxonomicChildrenCount()

	 */

	public void addTaxonRelation(Taxon toTaxon, TaxonRelationshipType type, ReferenceBase citation, String microcitation) {

		TaxonRelationship rel = new TaxonRelationship(this, toTaxon, type, citation, microcitation);

	}

	/**

	 * Creates a new {@link TaxonRelationship taxon relationship} (with {@link TaxonRelationshipType taxon relationship type}

	 * "misapplied name for") instance where <i>this</i> taxon plays the target role

	 * and adds it to the set of {@link #getRelationsToThisTaxon() taxon relationships to <i>this</i> taxon}.

	 * The taxon relationship will also be added to the set of taxon

	 * relationships to the other (misapplied name) taxon involved in the created relationship.

	 * 

	 * @param misappliedNameTaxon	the taxon which plays the target role in the new taxon relationship

	 * @param citation				the reference source for the new taxon relationship

	 * @param microcitation			the string with the details describing the exact localisation within the reference

	 * @see    	   					#getMisappliedNames()

	 * @see    	   					#addTaxonRelation(Taxon, TaxonRelationshipType, ReferenceBase, String)

	 * @see    	   					#addTaxonRelation(TaxonRelationship)

	 * @see    	   					#getTaxonRelations()

	 * @see    	   					#getRelationsFromThisTaxon()

	 * @see    	   					#getRelationsToThisTaxon()

	 */

	public void addMisappliedName(Taxon misappliedNameTaxon, ReferenceBase citation, String microcitation) {

		misappliedNameTaxon.addTaxonRelation(this, TaxonRelationshipType.MISAPPLIED_NAME_FOR(), citation, microcitation);

	}

//	public void removeMisappliedName(Taxon misappliedNameTaxon){

//		Set<TaxonRelationship> taxRels = this.getTaxonRelations();

//		for (TaxonRelationship taxRel : taxRels ){

//			if (taxRel.getType().equals(TaxonRelationshipType.MISAPPLIED_NAME_FOR()) 

//				&& taxRel.getFromTaxon().equals(misappliedNameTaxon)){

//				this.removeTaxonRelation(taxRel);

//			}

//		}

//	}

	/** 

	 * TODO update documentation 

	 * Removes one {@link TaxonRelationship taxon relationship} with {@link TaxonRelationshipType taxon relationship type}

	 * taxonRelType and with the given child taxon playing the

	 * source role from the set of {@link #getRelationsToThisTaxon() "taxon relationships to"} belonging

	 * to <i>this</i> taxon. The taxon relationship will also be removed from the set

	 * of {@link #getRelationsFromThisTaxon() "taxon relationships from"} belonging to the other side taxon.

	 * Furthermore, the inherited RelatedFrom and RelatedTo attributes of the

	 * taxon relationship will be nullified.<P>

	 *

	 * @param taxon			the taxon which plays the source role in the taxon relationship

	 * @param taxonRelType	the taxon relationship type

	 */

	public void removeTaxon(Taxon taxon, TaxonRelationshipType taxonRelType){

		Set<TaxonRelationship> taxRels = this.getTaxonRelations();

		for (TaxonRelationship taxRel : taxRels ){

			if (taxRel.getType().equals(taxonRelType) 

				&& taxRel.getFromTaxon().equals(taxon)){

				this.removeTaxonRelation(taxRel);

			}

		}

	}

	/**

	 * Creates a new {@link TaxonRelationship taxon relationship} (with {@link TaxonRelationshipType taxon relationship type}

	 * "taxonomically included in") instance where <i>this</i> taxon plays the target

	 * role (parent) and adds it to the set of

	 * {@link #getRelationsToThisTaxon() "taxon relationships to"} belonging to <i>this</i> taxon.

	 * The taxon relationship will also be added to the set of

	 * {@link #getRelationsFromThisTaxon() "taxon relationships from"} belonging to the second taxon

	 * (child) involved in the created relationship.<P>

	 * Since the taxon relationship concerns the modifications

	 * of the number of {@link #getTaxonomicChildrenCount() childrens} for <i>this</i> taxon and

	 * of the {@link #getTaxonomicParent() parent taxon} for the child taxon will be stored.

	 * The {@link name.Rank rank} of the taxon name used as a parent taxon must be higher

	 * than the rank of the taxon name used as a child taxon.

	 * 

	 * @param child			the taxon which plays the source role (child) in the new taxon relationship

	 * @param citation		the reference source for the new taxon relationship

	 * @param microcitation	the string with the details describing the exact localisation within the reference

	 * @see    	   			#setTaxonomicParent(Taxon, ReferenceBase, String)

	 * @see    	   			#addTaxonRelation(Taxon, TaxonRelationshipType, ReferenceBase, String)

	 * @see    	   			#addTaxonRelation(TaxonRelationship)

	 * @see    	   			#getTaxonRelations()

	 * @see    	   			#getRelationsFromThisTaxon()

	 * @see    	   			#getRelationsToThisTaxon()

	 * @see    	   			#getTaxonomicParent()

	 * @see    	   			#getTaxonomicChildrenCount()

	 */

	public void addTaxonomicChild(Taxon child, ReferenceBase citation, String microcitation){

		if (child == null){

			throw new NullPointerException("Child Taxon is 'null'");

		}else{

			child.setTaxonomicParent(this, citation, microcitation);

		}

	}

	/** 

	 * Removes one {@link TaxonRelationship taxon relationship} with {@link TaxonRelationshipType taxon relationship type}

	 * "taxonomically included in" and with the given child taxon playing the

	 * source role from the set of {@link #getRelationsToThisTaxon() "taxon relationships to"} belonging

	 * to <i>this</i> taxon. The taxon relationship will also be removed from the set

	 * of {@link #getRelationsFromThisTaxon() "taxon relationships from"} belonging to the child taxon.

	 * Furthermore the inherited RelatedFrom and RelatedTo attributes of the

	 * taxon relationship will be nullified.<P>

	 * Since the taxon relationship concerns the taxonomic tree modifications

	 * of the number of {@link #getTaxonomicChildrenCount() childrens} for <i>this</i> taxon and

	 * of the {@link #getTaxonomicParent() parent taxon} for the child taxon will be stored.

	 *

	 * @param  child	the taxon playing the source role in the relationship to be removed

	 * @see    	    	#removeTaxonRelation(TaxonRelationship)

	 * @see    			#getRelationsToThisTaxon()

	 * @see    			#getRelationsFromThisTaxon()

	 * @see    	    	#getTaxonomicParent()

	 * @see    	    	#getTaxonomicChildrenCount()

	 * @see    			eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedFrom()

	 * @see    			eu.etaxonomy.cdm.model.common.RelationshipBase#getRelatedTo()

	 * 

	 */

	public void removeTaxonomicChild(Taxon child){

		Set<TaxonRelationship> taxRels = this.getTaxonRelations();

		for (TaxonRelationship taxRel : taxRels ){

			if (taxRel.getType().equals(TaxonRelationshipType.TAXONOMICALLY_INCLUDED_IN()) 

				&& taxRel.getFromTaxon().equals(child)){

				this.removeTaxonRelation(taxRel);

			}

		}

	}

	/** 

	 * Returns the taxon which is the next higher taxon (parent) of <i>this</i> taxon

	 * within the taxonomic tree and which is stored in the

	 * TaxonomicParentCache attribute. Each taxon can have only one parent taxon.

	 * The child taxon and the parent taxon play the source respectively the

	 * target role in one {@link TaxonRelationship taxon relationship} with

	 * {@link TaxonRelationshipType taxon relationship type} "taxonomically included in".

	 * The {@link name.Rank rank} of the taxon name used as a parent taxon must be higher

	 * than the rank of the taxon name used as a child taxon.

	 * 

	 * @see  #setTaxonomicParent(Taxon, ReferenceBase, String)

	 * @see  #getTaxonomicChildren()

	 * @see  #getTaxonomicChildrenCount()

	 * @see  #getRelationsFromThisTaxon()

	 */

	public Taxon getTaxonomicParent() {

		return this.taxonomicParentCache;

	}

	/** 

	 * Sets the taxononomic parent of <i>this</i> taxon to null.

	 * Note that this method does not handle taxonomic relationships.

	 */

	public void nullifyTaxonomicParent() {

		this.taxonomicParentCache = null;

	}

	/**

	 * Replaces both the taxonomic parent cache with the given new parent taxon

	 * and the corresponding taxon relationship with a new {@link TaxonRelationship taxon relationship}

	 * (with {@link TaxonRelationshipType taxon relationship type} "taxonomically included in") instance.

	 * In the new taxon relationship <i>this</i> taxon plays the source role (child).

	 * This method creates and adds the new taxon relationship to the set of

	 * {@link #getRelationsFromThisTaxon() "taxon relationships from"} belonging to <i>this</i> taxon.

	 * The taxon relationship will also be added to the set of

	 * {@link #getRelationsToThisTaxon() "taxon relationships to"} belonging to the second taxon

	 * (parent) involved in the new relationship.<P>

	 * Since the taxon relationship concerns the taxonomic tree modifications

	 * of the {@link #getTaxonomicParent() parent taxon} for <i>this</i> taxon and of the number of

	 * {@link #getTaxonomicChildrenCount() childrens} for the child taxon will be stored.

	 * 

	 * @param newParent		the taxon which plays the target role (parent) in the new taxon relationship

	 * @param citation		the reference source for the new taxon relationship

	 * @param microcitation	the string with the details describing the exact localisation within the reference

	 * @see    	   			#removeTaxonRelation(TaxonRelationship)

	 * @see    	   			#getTaxonomicParent()

	 * @see    	   			#addTaxonRelation(Taxon, TaxonRelationshipType, ReferenceBase, String)

	 * @see    	   			#addTaxonRelation(TaxonRelationship)

	 * @see    	   			#getTaxonRelations()

	 * @see    	   			#getRelationsFromThisTaxon()

	 * @see    	   			#getRelationsToThisTaxon()

	 * @see    	   			#getTaxonomicChildrenCount()

	 */

	public void setTaxonomicParent(Taxon newParent, ReferenceBase citation, String microcitation){

		//remove previously existing parent relationship!!!

		Taxon oldParent = this.getTaxonomicParent();

		Set<TaxonRelationship> taxRels = this.getTaxonRelations();

		for (TaxonRelationship taxRel : taxRels ){

			if (taxRel.getType().equals(TaxonRelationshipType.TAXONOMICALLY_INCLUDED_IN()) && taxRel.getToTaxon().equals(oldParent)){

				this.removeTaxonRelation(taxRel);

			}

		}

		//add new parent

		if (newParent != null){

			addTaxonRelation(newParent, TaxonRelationshipType.TAXONOMICALLY_INCLUDED_IN(),citation,microcitation);

		}

	}

	/** 

	 * Returns the set of taxa which have <i>this</i> taxon as next higher taxon

	 * (parent) within the taxonomic tree. Each taxon can have several child

	 * taxa. The child taxon and the parent taxon play the source respectively

	 * the target role in one {@link TaxonRelationship taxon relationship} with

	 * {@link TaxonRelationshipType taxon relationship type} "taxonomically included in".

	 * The {@link name.Rank rank} of the taxon name used as a parent taxon must be higher

	 * than the rank of the taxon name used as a child taxon.

	 * 

	 * @see  #getTaxonomicParent()

	 * @see  #addTaxonomicChild(Taxon, ReferenceBase, String)

	 * @see  #getTaxonomicChildrenCount()

	 * @see  #getRelationsToThisTaxon()

	 */

	@Transient

	public Set<Taxon> getTaxonomicChildren() {

		Set<Taxon> taxa = new HashSet<Taxon>();

		Set<TaxonRelationship> rels = this.getRelationsToThisTaxon();

		for (TaxonRelationship rel: rels){

			TaxonRelationshipType tt = rel.getType();

			TaxonRelationshipType incl = TaxonRelationshipType.TAXONOMICALLY_INCLUDED_IN(); 

			if (tt.equals(incl)){

				taxa.add(rel.getFromTaxon());

			}

		}

		return taxa;

	}

	/** 

	 * Returns the number of taxa which have <i>this</i> taxon as next higher taxon

	 * (parent) within the taxonomic tree and the number of which is stored in

	 * the TaxonomicChildrenCount attribute. Each taxon can have several child

	 * taxa. The child taxon and the parent taxon play the source respectively

	 * the target role in one {@link TaxonRelationship taxon relationship} with

	 * {@link TaxonRelationshipType taxon relationship type} "taxonomically included in".

	 * The {@link name.Rank rank} of the taxon name used as a parent taxon must be higher

	 * than the rank of the taxon name used as a child taxon.

	 * 

	 * @see  #getTaxonomicChildren()

	 * @see  #getRelationsToThisTaxon()

	 */

	public int getTaxonomicChildrenCount(){

		return taxonomicChildrenCount;

	}	

	/**

	 * @see  #getTaxonomicChildrenCount()

	 */

	public void setTaxonomicChildrenCount(int taxonomicChildrenCount) {

		this.taxonomicChildrenCount = taxonomicChildrenCount;

	}

	/**

	 * Returns the boolean value indicating whether <i>this</i> taxon has at least one

	 * taxonomic child taxon within the taxonomic tree (true) or not (false).

	 * 

	 * @see  #getTaxonomicChildrenCount()

	 * @see  #getTaxonomicChildren()

	 */

	public boolean hasTaxonomicChildren(){

		return this.taxonomicChildrenCount > 0;

	}

	private int computeTaxonomicChildrenCount(){

		int count = 0;

		for (TaxonRelationship rel: this.getRelationsToThisTaxon()){

			if (rel.getType().equals(TaxonRelationshipType.TAXONOMICALLY_INCLUDED_IN())){

				count++;

			}

		}

		return count;

	}

	/**

	 * Returns the boolean value indicating whether <i>this</i> taxon is a misaplication

	 * (misapplied name) for at least one other taxon. 

	 */

	// TODO cache as for #hasTaxonomicChildren

	@Transient

	public boolean isMisappliedName(){

		return computeMisapliedNameRelations() > 0;

	}

	/**

	 * Counts the number of misaplied names relationships where this taxon represents the

	 * misaplied name for another taxon.

	 * @return

	 */

	private int computeMisapliedNameRelations(){

		int count = 0;

		for (TaxonRelationship rel: this.getRelationsFromThisTaxon()){

			if (rel.getType().equals(TaxonRelationshipType.MISAPPLIED_NAME_FOR())){

				count++;

			}

		}

		return count;

	}

	/**

	 * Returns the boolean value indicating whether <i>this</i> taxon has at least one

	 * {@link Synonym synonym} (true) or not (false). If true the {@link #getSynonymRelations() set of synonym relationships}

	 * belonging to <i>this</i> ("accepted/correct") taxon is not empty .

	 * 

	 * @see  #getSynonymRelations()

	 * @see  #getSynonyms()

	 * @see  #getSynonymNames()

	 * @see  #removeSynonym(Synonym)

	 * @see  SynonymRelationship

	 */

	public boolean hasSynonyms(){

		return this.getSynonymRelations().size() > 0;

	}

	/**

	 * Returns the boolean value indicating whether <i>this</i> taxon is at least

	 * involved in one {@link #getTaxonRelations() taxon relationship} between

	 * two taxa (true), either as a source or as a target, or not (false).

	 * 

	 * @see  #getTaxonRelations()

	 * @see  #getRelationsToThisTaxon()

	 * @see  #getRelationsFromThisTaxon()

	 * @see  #removeTaxonRelation(TaxonRelationship)

	 * @see  TaxonRelationship

	 */

	public boolean hasTaxonRelationships(){

		return this.getTaxonRelations().size() > 0;

	}

	/*

	 * MISAPPLIED NAMES

	 */

	/** 

	 * Returns the set of taxa playing the source role in {@link TaxonRelationship taxon relationships}

	 * (with {@link TaxonRelationshipType taxon relationship type} "misapplied name for") where

	 * <i>this</i> taxon plays the target role. A misapplied name is a taxon the

	 * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase taxon name} of which has been erroneously used

	 * by its {@link TaxonBase#getSec() taxon reference} to denominate the same real taxon

	 * as the one meant by <i>this</i> ("accepted/correct") taxon. 

	 * 

	 * @see  #getTaxonRelations()

	 * @see  #getRelationsToThisTaxon()

	 * @see  #addMisappliedName(Taxon, ReferenceBase, String)

	 */

	@Transient

	public Set<Taxon> getMisappliedNames(){

		Set<Taxon> taxa = new HashSet<Taxon>();

		Set<TaxonRelationship> rels = this.getRelationsToThisTaxon();

		for (TaxonRelationship rel: rels){

			TaxonRelationshipType tt = rel.getType();

			TaxonRelationshipType incl = TaxonRelationshipType.MISAPPLIED_NAME_FOR(); 

			if (tt.equals(incl)){

				taxa.add(rel.getFromTaxon());

			}

		}

		return taxa;

	}

	/*

	 * DEALING WITH SYNONYMS

	 */

	/** 

	 * Returns the set of all {@link Synonym synonyms} of <i>this</i> ("accepted/correct") taxon.

	 * Each synonym is the source and <i>this</i> taxon is the target of a {@link SynonymRelationship synonym relationship}

	 * belonging to the {@link #getSynonymRelations() set of synonym relationships} assigned to <i>this</i> taxon.

	 * For a particular synonym and for a particular ("accepted/correct") taxon

	 * there can be several synonym relationships (if two or more

	 * {@link SynonymRelationshipType synonym relationship types} - for instance

	 * "pro parte synonym of" and "is homotypic synonym of" - must be combined). 

	 *  

	 * @see    #getSynonymsSortedByType()

	 * @see    #getSynonymNames()

	 * @see    #getSynonymRelations()

	 * @see    #addSynonym(Synonym, SynonymRelationshipType)

	 * @see    #addSynonym(Synonym, SynonymRelationshipType, ReferenceBase, String)

	 * @see    #removeSynonymRelation(SynonymRelationship)

	 * @see    #removeSynonym(Synonym)

	 */

	@Transient

	public Set<Synonym> getSynonyms(){

		Set<Synonym> syns = new HashSet<Synonym>();

		for (SynonymRelationship rel: this.getSynonymRelations()){

			syns.add(rel.getSynonym());

		}

		return syns;

	}

	/** 

	 * Returns the set of all {@link Synonym synonyms} of <i>this</i> ("accepted/correct") taxon

	 * sorted by the different {@link SynonymRelationshipType categories of synonym relationships}.

	 * Each synonym is the source and <i>this</i> taxon is the target of a {@link SynonymRelationship synonym relationship}

	 * belonging to the {@link #getSynonymRelations() set of synonym relationships} assigned to <i>this</i> taxon.

	 *  

	 * @see    #getSynonyms()

	 * @see    #getSynonymNames()

	 * @see    #getSynonymRelations()

	 * @see    #addSynonym(Synonym, SynonymRelationshipType)

	 * @see    #addSynonym(Synonym, SynonymRelationshipType, ReferenceBase, String)

	 * @see    #removeSynonymRelation(SynonymRelationship)

	 * @see    #removeSynonym(Synonym)

	 */

	@Transient

	public Set<Synonym> getSynonymsSortedByType(){

		// FIXME: need to sort synonyms according to type!!!

		logger.warn("getSynonymsSortedByType() not yet implemented");

		return getSynonyms();

	}

	/** 

	 * Returns the set of all {@link name.TaxonNameBase taxon names} used as {@link Synonym synonyms}

	 * of <i>this</i> ("accepted/correct") taxon. Each synonym is the source and

	 * <i>this</i> taxon is the target of a {@link SynonymRelationship synonym relationship} belonging

	 * to the {@link #getSynonymRelations() set of synonym relationships} assigned to <i>this</i> taxon.

	 *  

	 * @see    #getSynonyms()

	 * @see    #getSynonymsSortedByType()

	 * @see    #getSynonymRelations()

	 * @see    #addSynonymName(TaxonNameBase, SynonymRelationshipType)

	 * @see    #addSynonym(Synonym, SynonymRelationshipType, ReferenceBase, String)

	 * @see    #removeSynonymRelation(SynonymRelationship)

	 * @see    #removeSynonym(Synonym)

	 */

	@Transient

	public Set<TaxonNameBase> getSynonymNames(){

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

		for (SynonymRelationship rel: this.getSynonymRelations()){

			names.add(rel.getSynonym().getName());

		}

		return names;

	}

	/**

	 * Creates a new {@link SynonymRelationship synonym relationship} (with the given {@link Synonym synonym}

	 * and with the given {@link SynonymRelationshipType synonym relationship type}), returns it and adds it

	 * to the set of {@link #getSynonymRelations() synonym relationships} assigned to <i>this</i> taxon.

	 * The new synonym relationship will also be added to the set of

	 * {@link Synonym#getSynonymRelations() synonym relationships} belonging to the synonym

	 * involved in this synonym relationship.<BR>

	 * The returned synonym relationship allows to add further information to it.

	 * 

	 * @param synonym		the synonym involved in the relationship to be created

	 * 						and added to <i>this</i> taxon's synonym relationships set

	 * @param synonymType	the synonym relationship category of the synonym

	 * 						relationship to be added

	 * @return 				the created synonym relationship

	 * @see    	   			#addSynonymRelation(SynonymRelationship)

	 * @see    	   			#addSynonym(Synonym, SynonymRelationshipType, ReferenceBase, String)

	 * @see    	   			#addSynonymName(TaxonNameBase, SynonymRelationshipType)

	 * @see    	   			#addSynonymName(TaxonNameBase, SynonymRelationshipType, ReferenceBase, String)

	 * @see    	   			#addHomotypicSynonym(Synonym, ReferenceBase, String)

	 * @see    	   			#addHomotypicSynonymName(TaxonNameBase, ReferenceBase, String)

	 * @see    	   			#addHeterotypicSynonymName(TaxonNameBase)

	 * @see    	   			#addHeterotypicSynonymName(TaxonNameBase, HomotypicalGroup, ReferenceBase, String)

	 * @see    	   			#getSynonymRelations()

	 * @see    				#removeSynonym(Synonym)

	 * @see    	   			Synonym#getSynonymRelations()

	 */

	public SynonymRelationship addSynonym(Synonym synonym, SynonymRelationshipType synonymType){

		return addSynonym(synonym, synonymType, null, null);

	}

	/**

	 * Creates a new {@link SynonymRelationship synonym relationship} (with the given {@link Synonym synonym},

	 * with the given {@link SynonymRelationshipType synonym relationship type} and with the

	 * {@link eu.etaxonomy.cdm.model.reference.ReferenceBase reference source} on which the relationship assertion is based),

	 * returns it and adds it to the set of {@link #getSynonymRelations() synonym relationships}

	 * assigned to <i>this</i> taxon. The new synonym relationship will also be

	 * added to the set of {@link Synonym#getSynonymRelations() synonym relationships} belonging to the synonym

	 * involved in this synonym relationship.<BR>

	 * The returned synonym relationship allows to add further information to it.

	 * 

	 * @param synonym		the synonym involved in the relationship to be created

	 * 						and added to <i>this</i> taxon's synonym relationships set

	 * @param synonymType	the synonym relationship category of the synonym

	 * 						relationship to be added

	 * @param citation		the reference source for the new synonym relationship

	 * @param microcitation	the string with the details describing the exact localisation within the reference

	 * @return 				the created synonym relationship

	 * @see    	   			#addSynonymRelation(SynonymRelationship)

	 * @see    	   			#addSynonym(Synonym, SynonymRelationshipType, ReferenceBase, String)

	 * @see    	   			#addSynonymName(TaxonNameBase, SynonymRelationshipType)

	 * @see    	   			#addSynonymName(TaxonNameBase, SynonymRelationshipType, ReferenceBase, String)

	 * @see    	   			#addHomotypicSynonym(Synonym, ReferenceBase, String)

	 * @see    	   			#addHomotypicSynonymName(TaxonNameBase, ReferenceBase, String)

	 * @see    	   			#addHeterotypicSynonymName(TaxonNameBase)

	 * @see    	   			#addHeterotypicSynonymName(TaxonNameBase, HomotypicalGroup, ReferenceBase, String)

	 * @see    	   			#getSynonymRelations()

	 * @see    				#removeSynonym(Synonym)

	 * @see    	   			Synonym#getSynonymRelations()

	 */

	public SynonymRelationship addSynonym(Synonym synonym, SynonymRelationshipType synonymType, ReferenceBase citation, String citationMicroReference){

		SynonymRelationship synonymRelationship = new SynonymRelationship(synonym, this, synonymType, citation, citationMicroReference);

		return synonymRelationship;

	}

	/**

	 * Creates a new {@link Synonym synonym} (with the given {@link eu.etaxonomy.cdm.model.name.TaxonNameBase taxon name}),

	 * a new {@link SynonymRelationship synonym relationship} (with the new synonym and with the given 

	 * {@link SynonymRelationshipType synonym relationship type}), returns the relationship and adds it

	 * to the set of {@link #getSynonymRelations() synonym relationships} assigned to <i>this</i> taxon.

	 * The new synonym will have the same {@link TaxonBase#getSec() concept reference}

	 * as <i>this</i> taxon. The new synonym relationship will also be added to 

	 * the set of {@link Synonym#getSynonymRelations() synonym relationships} belonging

	 * to the created synonym.<BR>

	 * The returned synonym relationship allows to add further information to it.

	 * 

	 * @param synonymName	the taxon name to be used as a synonym to be added

	 * 						to <i>this</i> taxon's set of synonyms

	 * @param synonymType	the synonym relationship category of the synonym

	 * 						relationship to be added

	 * @return 				the created synonym relationship

	 * @see    	   			#addSynonymName(TaxonNameBase, SynonymRelationshipType, ReferenceBase, String)

	 * @see    	   			#addSynonym(Synonym, SynonymRelationshipType)

	 * @see    	   			#addSynonym(Synonym, SynonymRelationshipType, ReferenceBase, String)

	 * @see    	   			#addSynonymRelation(SynonymRelationship)

	 * @see    	   			#addHomotypicSynonym(Synonym, ReferenceBase, String)