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 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.validation.Valid;

import javax.validation.constraints.NotNull;

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

import org.hibernate.search.annotations.ClassBridges;

import org.hibernate.search.annotations.ContainedIn;

import org.hibernate.search.annotations.Indexed;

import org.hibernate.search.annotations.IndexedEmbedded;

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

import org.springframework.util.ReflectionUtils;

import eu.etaxonomy.cdm.hibernate.search.GroupByTaxonClassBridge;

import eu.etaxonomy.cdm.hibernate.search.TaxonRelationshipClassBridge;

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

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

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

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

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

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

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

/**

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

 * the opinion of the {@link eu.etaxonomy.cdm.model.reference.Reference reference} can build a classification).

 * 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

@ClassBridges({

    @ClassBridge(impl = GroupByTaxonClassBridge.class),

    @ClassBridge(impl = TaxonRelationshipClassBridge.class)

})

public class Taxon

            extends TaxonBase<ITaxonCacheStrategy<Taxon>>

            implements IRelated<RelationshipBase>, IDescribable<TaxonDescription>, Cloneable{

    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, CascadeType.MERGE, CascadeType.DELETE})

    @NotNull

    @ContainedIn

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

    // all related synonyms

    @XmlElementWrapper(name = "SynonymRelations")

    @XmlElement(name = "SynonymRelationship")

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

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

    @NotNull

    @Valid

    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, orphanRemoval=true)

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

    @NotNull

//    @Valid

    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, orphanRemoval=true)

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

    @NotNull

//    @Valid

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

    @XmlAttribute(name= "taxonStatusUnknown")

    private boolean taxonStatusUnknown = false;

    @XmlAttribute(name= "unplaced")

    private boolean unplaced = false;

    @XmlAttribute(name= "excluded")

    private boolean excluded = false;

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

    @XmlElement(name = "TaxonomicParentCache")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @ManyToOne(fetch = FetchType.LAZY)

    @Deprecated //will be removed in future versions. Use Classification/TaxonNode instead

    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})

    @IndexedEmbedded

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

    //cached number of taxonomic children

    @XmlElement(name = "TaxonomicChildrenCount")

    @Deprecated //will be removed in future versions. Use Classification/TaxonNode instead

    private int taxonomicChildrenCount;

// ************************* FACTORY 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.Reference reference}

     * using it.

     *

     * @param  taxonNameBase	the taxon name used

     * @param  sec				the reference using the taxon name

     * @see    					#Taxon(TaxonNameBase, Reference)

     */

    public static Taxon NewInstance(TaxonNameBase taxonNameBase, Reference 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.Reference reference}

     * using it.

     *

     * @param  taxonNameBase	the taxon name used

     * @param  sec				the reference using the taxon name

     * @see    					#Taxon(TaxonNameBase, Reference)

     */

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

        Taxon result = new Taxon(taxonNameBase, sec);

        result.setTaxonStatusUnknown(true);

        return result;

    }

// ************* 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.Reference reference}

     * using it.

     *

     * @param  taxonNameBase	the taxon name used

     * @param  sec				the reference using the taxon name

     * @see    					TaxonBase#TaxonBase(TaxonNameBase, Reference)

     */

    public Taxon(TaxonNameBase taxonNameBase, Reference sec){

        super(taxonNameBase, sec);

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

    }

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

    /**

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

     */

    @Override

    public Set<TaxonDescription> getDescriptions() {

        if(descriptions == null) {

            descriptions = new HashSet<TaxonDescription>();

        }

        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()

     */

    @Override

    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()

     */

    @Override

    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 void removeDescription(TaxonDescription description, boolean removeElements){

    	if (removeElements){

    		Set<DescriptionElementBase> elements = new HashSet<DescriptionElementBase>(description.getElements());

            for (DescriptionElementBase el:elements){

            	description.getElements().remove(el);

            }

            removeDescription(description);

    	} else{

    		removeDescription(description);

    	}

    }

    /**

     * Returns the image gallery for a taxon. If there are multiple taxon descriptions

     * marked as image galleries an arbitrary one is chosen.

     * If no image gallery exists, a new one is created if <code>createNewIfNotExists</code>

     * is <code>true</code>.

     * @param createNewIfNotExists

     * @return

     */

    public TaxonDescription getImageGallery(boolean createNewIfNotExists) {

        TaxonDescription result = null;

        Set<TaxonDescription> descriptions= getDescriptions();

        for (TaxonDescription description : descriptions){

            if (description.isImageGallery()){

                result = description;

                break;

            }

        }

        if (result == null && createNewIfNotExists){

            result = TaxonDescription.NewInstance(this);

            result.setImageGallery(true);

        }

        return result;

    }

    public Set<TaxonNode> getTaxonNodes() {

        return taxonNodes;

    }

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

//		this.taxonNodes = taxonNodes;

//	}

    protected void addTaxonNode(TaxonNode taxonNode){

        taxonNodes.add(taxonNode);

    }

    public boolean removeTaxonNode(TaxonNode taxonNode){

        if (!taxonNodes.contains(taxonNode)){

            return false;

        }

        TaxonNode parent = taxonNode.getParent();

        if (parent != null){

            parent.removeChildNode(taxonNode);

        }

        taxonNode.setTaxon(null);

        return taxonNodes.remove(taxonNode);

    }

    public boolean removeTaxonNode(TaxonNode taxonNode, boolean deleteChildren){

        TaxonNode parent = taxonNode.getParent();

        boolean success = true;

        if ((!taxonNode.getChildNodes().isEmpty() && deleteChildren) || (taxonNode.getChildNodes().isEmpty()) ){

            taxonNode.delete();

        } else if (!taxonNode.isTopmostNode()){

            List<TaxonNode> nodes = new ArrayList<TaxonNode> (taxonNode.getChildNodes());

            for (TaxonNode childNode: nodes){

                taxonNode.getChildNodes().remove(childNode);

                parent.addChildNode(childNode, null, null);

            }

            taxonNode.delete();

        } else if (taxonNode.isTopmostNode()){

            success = false;

        }

        return success;

    }

    public boolean removeTaxonNodes(boolean deleteChildren){

        Iterator<TaxonNode> nodesIterator = taxonNodes.iterator();

        TaxonNode node;

        TaxonNode parent;

        boolean success = false;

        List<TaxonNode> removeNodes = new ArrayList<TaxonNode>();

        while (nodesIterator.hasNext()){

            node = nodesIterator.next();

            if (!deleteChildren){

                List<TaxonNode> children = node.getChildNodes();

                Iterator<TaxonNode> childrenIterator = children.iterator();

                parent = node.getParent();

                while (childrenIterator.hasNext()){

                    TaxonNode childNode = childrenIterator.next();

                    if (parent != null){

                        parent.addChildNode(childNode, null, null);

                    }else{

                        childNode.setParent(null);

                    }

                }

                for (int i = 0; i<node.getChildNodes().size(); i++){

                    node.removeChild(i);

                }

            }

            removeNodes.add(node);

         }

        for (int i = 0; i<removeNodes.size(); i++){

            TaxonNode removeNode = removeNodes.get(i);

            success = removeNode.delete(deleteChildren);

            removeNode.setTaxon(null);

            removeTaxonNode(removeNode);

        }

        return success;

    }

    /**

     * 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() {

        if(synonymRelations == null) {

            this.synonymRelations = new HashSet<SynonymRelationship>();

        }

        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, Reference, String)

     * @see    	   				#addSynonymName(TaxonNameBase, SynonymRelationshipType)

     * @see    	   				#addSynonymName(TaxonNameBase, SynonymRelationshipType, Reference, 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

     * @param removeSynonymNameFromHomotypicalGroup

     * 				if <code>true</code> the synonym name will also be deleted from its homotypical group if the

     * 				group contains other names

     * @see    	#getSynonymRelations()

     * @see    	#addSynonymRelation(SynonymRelationship)

     * @see 	#removeSynonym(Synonym)

     */

    public void removeSynonymRelation(SynonymRelationship synonymRelation, boolean removeSynonymNameFromHomotypicalGroup) {

        synonymRelation.setAcceptedTaxon(null);

        Synonym synonym = synonymRelation.getSynonym();

        if (synonym != null){

            synonymRelation.setSynonym(null);

            synonym.removeSynonymRelation(synonymRelation);

            if(removeSynonymNameFromHomotypicalGroup){

                HomotypicalGroup synHG = synonym.getName().getHomotypicalGroup();

                if (synHG.getTypifiedNames().size() > 1){

                    synHG.removeTypifiedName(synonym.getName(), false);

                }

            }

        }

        this.synonymRelations.remove(synonymRelation);

    }

    /**

     * Like {@link Taxon#removeSynonymRelation(SynonymRelationship, boolean)} but synonym name

     * will be deleted from homotypical group by default

     *

     * @param synonymRelation   the synonym relationship which should be deleted

     *

     * @see					#removeSynonymRelation(SynonymRelationship, boolean)

     */

    public void removeSynonymRelation(SynonymRelationship synonymRelation){

        removeSynonymRelation(synonymRelation, true);

    }

    /**

     * 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() {

        if(relationsFromThisTaxon == null) {

            this.relationsFromThisTaxon = new HashSet<TaxonRelationship>();

        }

        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() {

        if(relationsToThisTaxon == null) {

            this.relationsToThisTaxon = new HashSet<TaxonRelationship>();

        }

        return 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;

    }

    /**

     * @see    #getRelationsToThisTaxon()

     */

    protected void setRelationsToThisTaxon(Set<TaxonRelationship> relationsToThisTaxon) {

        this.relationsToThisTaxon = relationsToThisTaxon;

    }

    /**

     * @see    #getRelationsFromThisTaxon()

     */

    protected void setRelationsFromThisTaxon(Set<TaxonRelationship> relationsFromThisTaxon) {

        this.relationsFromThisTaxon = relationsFromThisTaxon;

    }

    /**

     * If a relationships between <i>this</i> and the given taxon exists they will be returned.

     * <i>This</i> taxon is involved either as a source or as a target in the relationships.

     * The method will return <code>null</code> if no relations exist between the two taxa.

     *

     * @param possiblyRelatedTaxon

     * 			a taxon to check for a relationship

     * @return

     * 			a set of <code>TaxonRelationship</code>s or <code>null</null> if none exists.

     */

    public Set<TaxonRelationship> getTaxonRelations(Taxon possiblyRelatedTaxon){

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

        for(TaxonRelationship relationship : getTaxonRelations()){

            if(relationship.getFromTaxon().equals(possiblyRelatedTaxon)) {

                relations.add(relationship);

            }

            if(relationship.getToTaxon().equals(possiblyRelatedTaxon)) {

                relations.add(relationship);

            }

        }

        return relations.size() > 0 ? relations : null;

    }

    /**

     * 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 classification 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) {

        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 != this){

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

            if (fromTaxon != null){

                if (fromTaxon.getTaxonRelations().contains(rel)){

                    fromTaxon.removeTaxonRelation(rel);

                }

            }

        }

        if (toTaxon != this ){

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

           if (toTaxon != null){

               if (toTaxon.getTaxonRelations().contains(rel)) {

                   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 classification 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, Reference, 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++;

                    }

                }

            }else if (toTaxon == null || fromTaxon == null){

                if (toTaxon == null){

                    toTaxon = this;

                    relationsToThisTaxon.add(rel);

                    if (fromTaxon!= null){

                        fromTaxon.addTaxonRelation(rel);

                    }

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

                        this.taxonomicChildrenCount++;

                    }

                }else if (fromTaxon == null && toTaxon != null){

                    fromTaxon = this;

                    relationsFromThisTaxon.add(rel);

                    if (toTaxon!=null){

                        toTaxon.addTaxonRelation(rel);

                    }

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

                        this.taxonomicParentCache = toTaxon;

                    }

                }

            }

        }

    }

    /* (non-Javadoc)

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

     */

    @Override

    @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 classification 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

     * @return

     * @see    	   			#addTaxonRelation(TaxonRelationship)

     * @see    	   			#getTaxonRelations()

     * @see    	   			#getRelationsFromThisTaxon()

     * @see    	   			#getRelationsToThisTaxon()

     * @see    	   			#getTaxonomicParent()

     * @see    	   			#getTaxonomicChildrenCount()

     */

    public TaxonRelationship addTaxonRelation(Taxon toTaxon, TaxonRelationshipType type, Reference citation, String microcitation) {

        return 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

     * @return

     * @see    	   					#getMisappliedNames()

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

     * @see    	   					#addTaxonRelation(TaxonRelationship)

     * @see    	   					#getTaxonRelations()

     * @see    	   					#getRelationsFromThisTaxon()

     * @see    	   					#getRelationsToThisTaxon()

     */

    public TaxonRelationship addMisappliedName(Taxon misappliedNameTaxon, Reference citation, String microcitation) {

        return 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, Reference, String)

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

     * @see    	   			#addTaxonRelation(TaxonRelationship)

     * @see    	   			#getTaxonRelations()

     * @see    	   			#getRelationsFromThisTaxon()

     * @see    	   			#getRelationsToThisTaxon()

     * @see    	   			#getTaxonomicParent()

     * @see    	   			#getTaxonomicChildrenCount()

     */

    @Deprecated //will be removed in future versions. Use Classification/TaxonNode instead

    public void addTaxonomicChild(Taxon child, Reference 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 classification 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()

     *

     */

    @Deprecated //will be removed in future versions. Use classification/TaxonNode instead

    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 classification 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, Reference, String)

     * @see  #getTaxonomicChildren()

     * @see  #getTaxonomicChildrenCount()

     * @see  #getRelationsFromThisTaxon()

     */

    @Deprecated //will be removed in future versions. Use Classification/TaxonNode instead

    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.

     */

    @Deprecated //will be removed in future versions. Use Classification/TaxonNode instead

    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 classification 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, Reference, String)

     * @see    	   			#addTaxonRelation(TaxonRelationship)

     * @see    	   			#getTaxonRelations()

     * @see    	   			#getRelationsFromThisTaxon()

     * @see    	   			#getRelationsToThisTaxon()

     * @see    	   			#getTaxonomicChildrenCount()

     */

    @Deprecated //will be removed in future versions. Use Classification/TaxonNode instead

    public void setTaxonomicParent(Taxon newParent, Reference 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 classification. 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, Reference, String)

     * @see  #getTaxonomicChildrenCount()