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

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

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

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

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

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

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

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

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

 */

@XmlAccessorType(XmlAccessType.FIELD)

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

    "taxonNodes",

    "synonyms",

    "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>, ICdmTarget{

    private static final long serialVersionUID = -584946869762749006L;

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

    private static final TaxonComparator defaultTaxonComparator = new TaxonComparator();

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

    // all related synonyms

    @XmlElementWrapper(name = "Synonyms")

    @XmlElement(name = "Synonym")

    @XmlIDREF

    @XmlSchemaType(name = "IDREF")

    @OneToMany(mappedBy="acceptedTaxon", fetch=FetchType.LAZY, orphanRemoval=false) //we allow synonyms to stay on their own for dirty data and for intermediate states during e.g. imports

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

    @NotNull

    @Valid

    @ContainedIn

    private Set<Synonym> synonyms = new HashSet<>();

    // 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

    @ContainedIn

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

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

//    @Valid

    @ContainedIn

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

    @XmlAttribute(name= "taxonStatusUnknown")

    private boolean taxonStatusUnknown = false;

    /**

     * The status of this taxon is unknown it could also be some kind of synonym.

     * @return the taxonStatusUnknown

     */

    public boolean isTaxonStatusUnknown() {return taxonStatusUnknown;}

     /** @see #isTaxonStatusUnknown()*/

    public void setTaxonStatusUnknown(boolean taxonStatusUnknown) {this.taxonStatusUnknown = taxonStatusUnknown;}

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

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

    /**

     * @see #NewInstance(TaxonName, Reference)

     * @param taxonName

     * @param sec

     * @return

     */

    public static Taxon NewInstance(ITaxonNameBase taxonName, Reference sec){

        return NewInstance(TaxonName.castAndDeproxy(taxonName), sec);

    }

    /**

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

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

     * using it.

     *

     * @param  taxonName	the taxon name used

     * @param  sec				the reference using the taxon name

     * @see    					#Taxon(TaxonName, Reference)

     */

    public static Taxon NewInstance(TaxonName taxonName, Reference sec){

        Taxon result = new Taxon(taxonName, sec);

        return result;

    }

    /**

     * Creates a new Taxon for the given name, secundum reference and secundum detail

     * @param taxonName

     * @param sec

     * @param secMicroReference

     * @see #

     */

    public static Taxon NewInstance(TaxonName taxonName, Reference sec, String secMicroReference){

        Taxon result = new Taxon(taxonName, sec, secMicroReference);

        return result;

    }

    /**

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

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

     * using it.

     *

     * @param  taxonName	the taxon name used

     * @param  sec				the reference using the taxon name

     * @see    					#Taxon(TaxonName, Reference)

     */

    public static Taxon NewUnknownStatusInstance(TaxonName taxonName, Reference sec){

        Taxon result = new Taxon(taxonName, sec);

        result.setTaxonStatusUnknown(true);

        return result;

    }

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

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

    @Deprecated

    public Taxon(){

        this.cacheStrategy = new TaxonBaseDefaultCacheStrategy<>();

    }

    private Taxon(TaxonName taxonName, Reference sec){

        super(taxonName, sec, null);

        this.cacheStrategy = new TaxonBaseDefaultCacheStrategy<>();

    }

    private Taxon(TaxonName taxonName, Reference sec, String secMicroReference){

        super(taxonName, sec, secMicroReference);

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

        }

        return descriptions;

    }

    public Set<TaxonDescription> getDescriptions(DescriptionType type) {

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

        for (TaxonDescription description : getDescriptions()){

            if (description.getTypes().contains(type)){

                result.add(description);

            }

        }

        return result;

    }

    /**

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

        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;

    }

    public TaxonNode getTaxonNode(Classification classification) {

        if (classification == null){

            return null;

        }

        for (TaxonNode node : this.getTaxonNodes()){

            if (classification.equals(node.getClassification())){

                return node;

            }

        }

        return null;

    }

    /**

     * Returns the set of all {@link Synonym synonyms}

     * for which <i>this</i> ("accepted/valid") taxon is the accepted taxon.

     *

     * @see    #addSynonym(Synonym, SynonymType)

     * @see    #removeSynonym(Synonym)

     */

    public Set<Synonym> getSynonyms() {

        if(synonyms == null) {

            this.synonyms = new HashSet<>();

        }

        return synonyms;

    }

    /**

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

        }

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

        }

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

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

        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>

     *

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

     * 				of both sets

     * @see    		#getTaxonRelations()

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

        //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>

     *

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

     */

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

                    }

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

                    relationsToThisTaxon.add(rel);

                    // also add relation to other taxon object

                    if (fromTaxon!=null){

                        fromTaxon.addTaxonRelation(rel);

                    }

                }

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

                if (toTaxon == null){

                    toTaxon = this;

                    relationsToThisTaxon.add(rel);

                    if (fromTaxon!= null){

                        fromTaxon.addTaxonRelation(rel);

                    }

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

                    fromTaxon = this;

                    relationsFromThisTaxon.add(rel);

                    toTaxon.addTaxonRelation(rel);

                }

            }

        }

    }

    @Override

    @Deprecated //for inner use by RelationshipBase only

    public void addRelationship(RelationshipBase rel){

        if (rel instanceof TaxonRelationship){

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

     *

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

     */

    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 source 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                         #addProParteMisappliedName(Taxon, Reference, String)

     * @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);

//			}

//		}

//	}

    /**

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

     * "pro parte 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 (pro parte misapplied name) taxon involved in the created relationship.

     *

     * @param proParteMisappliedNameTaxon   the taxon which plays the source 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                         #addMisappliedName(Taxon, Reference, String)

     * @see                         #getMisappliedNames()

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

     * @see                         #addTaxonRelation(TaxonRelationship)

     * @see                         #getTaxonRelations()

     * @see                         #getRelationsFromThisTaxon()

     * @see                         #getRelationsToThisTaxon()

     */

    public TaxonRelationship addProParteMisappliedName(Taxon proParteMisappliedNameTaxon, Reference citation, String microcitation) {

        return proParteMisappliedNameTaxon.addTaxonRelation(this, TaxonRelationshipType.PRO_PARTE_MISAPPLIED_NAME_FOR(), citation, microcitation);

    }

    /**

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

     * "partial 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 (pro parte misapplied name) taxon involved in the created relationship.

     *

     * @param partialMisappliedNameTaxon   the taxon which plays the source 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 localization within the reference

     * @return

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

     * @see                         #addProParteMisappliedName(Taxon, Reference, String)

     * @see                         #getMisappliedNames()

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

     * @see                         #addTaxonRelation(TaxonRelationship)

     * @see                         #getTaxonRelations()

     * @see                         #getRelationsFromThisTaxon()

     * @see                         #getRelationsToThisTaxon()

     */

    public TaxonRelationship addPartialMisappliedName(Taxon partialMisappliedNameTaxon, Reference citation, String microcitation) {

        return partialMisappliedNameTaxon.addTaxonRelation(this, TaxonRelationshipType.PARTIAL_MISAPPLIED_NAME_FOR(), citation, microcitation);

    }

    /**

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

     * "pro parte synonym 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 (pro parte synonym) taxon involved in the created relationship.

     *

     * @param proParteTaxon         the taxon which plays the source 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                         #addProParteMisappliedName(Taxon, Reference, String)

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

     * @see                         #addTaxonRelation(TaxonRelationship)

     * @see                         #getTaxonRelations()

     * @see                         #getRelationsFromThisTaxon()

     * @see                         #getRelationsToThisTaxon()

     */

    public TaxonRelationship addProparteSynonym(Taxon proParteTaxon, Reference citation, String microcitation) {

        return proParteTaxon.addTaxonRelation(this, TaxonRelationshipType.PRO_PARTE_SYNONYM_FOR(), citation, microcitation);

    }

    /**

     * Creates a new {@link TaxonRelationship taxon relationship} instance with

     * {@link TaxonRelationshipType taxon relationship type} {@link TaxonRelationshipType#PARTIAL_SYNONYM_FOR()

     * partial synonym for} 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 (partial synonym) taxon involved in the created relationship.

     *

     * @param partialTaxon         the taxon which plays the source 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                         #addProparteSynonym(Taxon, Reference, String)

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

     * @see                         #addTaxonRelation(TaxonRelationship)

     * @see                         #getTaxonRelations()

     * @see                         #getRelationsFromThisTaxon()

     * @see                         #getRelationsToThisTaxon()

     */

    public TaxonRelationship addPartialSynonym(Taxon partialTaxon, Reference citation, String microcitation) {

        return partialTaxon.addTaxonRelation(this, TaxonRelationshipType.PARTIAL_SYNONYM_FOR(), citation, microcitation);

    }

    /**

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

            }

        }

    }

    /**

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

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

     */

    // TODO cache as for #hasTaxonomicChildren

    @Transient

    public boolean isMisapplication(){

        return computeMisapliedNameRelations() > 0;

    }

    /**

     * Counts the number of misapplied name relationships (including pro parte and partial

     * misapplied names) where this taxon represents the

     * misapplied name for another taxon.

     * @return

     */

    private int computeMisapliedNameRelations(){

        int count = 0;

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

            if (rel.getType().isAnyMisappliedName()){

                count++;

            }

        }

        return count;

    }

    /**

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

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

     */

    // TODO cache as for #hasTaxonomicChildren

    @Transient

    public boolean isProparteSynonym(){

        return computeProparteSynonymRelations() > 0;

    }

    /**

     * Counts the number of misapplied name relationships (including pro parte misapplied

     * names) where this taxon represents the

     * misapplied name for another taxon.

     * @return

     */

    private int computeProparteSynonymRelations(){

        int count = 0;

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

            if (rel.getType().isAnySynonym()){

                count++;

            }

        }

        return count;

    }

    /**

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

     * concept for at least one other taxon.

     */

    @Transient

    public boolean isRelatedConcept(){

        return computeConceptRelations() > 0;

    }

    /**

     * Counts the number of concept relationships where this taxon represents the

     * related concept for another taxon.

     * @return

     */

    private int computeConceptRelations(){

        int count = 0;

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

            TaxonRelationshipType type = rel.getType();

            if (type.isConceptRelationship()){

                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 #getSynonyms() set of synonyms}

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

     *

     * @see  #getSynonyms()

     * @see  #getSynonymNames()

     * @see  #removeSynonym(Synonym)

     */

    @Transient

    public boolean hasSynonyms(){

        return this.getSynonyms().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.TaxonName 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, Reference, String)

     * @param includeNonCongruent if <code>true</code> also those taxa are returned that are related

     * via a non congruent relationship like {@link TaxonRelationshipType#PRO_PARTE_MISAPPLIED_NAME_FOR()

     * pro parte misapplied name}

     */

    @Transient

    public Set<Taxon> getMisappliedNames(boolean includeNonCongruent){

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

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

        for (TaxonRelationship rel: rels){

            TaxonRelationshipType relType = rel.getType();

            if ( (includeNonCongruent && relType.isAnyMisappliedName())

                    || relType.equals(TaxonRelationshipType.MISAPPLIED_NAME_FOR())){

                taxa.add(rel.getFromTaxon());

            }

        }

        return taxa;

    }

    /**