// $Id$
/**
* Copyright (C) 2007 EDIT
-* European Distributed Institute of Taxonomy
+* 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.api.service;
+import java.io.IOException;
+import java.util.EnumSet;
import java.util.List;
import java.util.Set;
+import java.util.UUID;
-import eu.etaxonomy.cdm.api.service.config.ITaxonServiceConfigurator;
+import org.apache.lucene.index.CorruptIndexException;
+import org.apache.lucene.queryParser.ParseException;
+
+import eu.etaxonomy.cdm.api.service.config.IFindTaxaAndNamesConfigurator;
+import eu.etaxonomy.cdm.api.service.config.IncludedTaxonConfiguration;
+import eu.etaxonomy.cdm.api.service.config.MatchingTaxonConfigurator;
+import eu.etaxonomy.cdm.api.service.config.SynonymDeletionConfigurator;
+import eu.etaxonomy.cdm.api.service.config.TaxonDeletionConfigurator;
+import eu.etaxonomy.cdm.api.service.dto.IncludedTaxaDTO;
+import eu.etaxonomy.cdm.api.service.exception.DataChangeNoRollbackException;
+import eu.etaxonomy.cdm.api.service.exception.HomotypicalGroupChangeException;
import eu.etaxonomy.cdm.api.service.pager.Pager;
+import eu.etaxonomy.cdm.api.service.search.LuceneMultiSearchException;
+import eu.etaxonomy.cdm.api.service.search.SearchResult;
+import eu.etaxonomy.cdm.api.service.util.TaxonRelationshipEdge;
import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
+import eu.etaxonomy.cdm.model.common.Language;
import eu.etaxonomy.cdm.model.common.OrderedTermVocabulary;
import eu.etaxonomy.cdm.model.common.RelationshipBase;
import eu.etaxonomy.cdm.model.common.RelationshipBase.Direction;
+import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
+import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
+import eu.etaxonomy.cdm.model.description.Feature;
+import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase;
+import eu.etaxonomy.cdm.model.location.NamedArea;
+import eu.etaxonomy.cdm.model.media.Media;
import eu.etaxonomy.cdm.model.media.MediaRepresentation;
+import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
import eu.etaxonomy.cdm.model.name.Rank;
import eu.etaxonomy.cdm.model.name.TaxonNameBase;
-import eu.etaxonomy.cdm.model.reference.ReferenceBase;
+import eu.etaxonomy.cdm.model.reference.Reference;
+import eu.etaxonomy.cdm.model.taxon.Classification;
import eu.etaxonomy.cdm.model.taxon.Synonym;
import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
import eu.etaxonomy.cdm.model.taxon.Taxon;
import eu.etaxonomy.cdm.model.taxon.TaxonBase;
-import eu.etaxonomy.cdm.model.taxon.TaxonNode;
import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
-import eu.etaxonomy.cdm.model.taxon.TaxonomicTree;
-import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
+import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
import eu.etaxonomy.cdm.persistence.query.OrderHint;
public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{
- /**
- * Computes all taxon bases.
- * FIXME could substitute with list(Synonym.class, limit, start)
- * @param limit
- * @param start
- * @return
- */
- public List<Synonym> getAllSynonyms(int limit, int start);
-
- /**
- * Computes all taxon bases.
- * FIXME could substitute with list(Taxon.class, limit,start)
- * @param limit
- * @param start
- * @return
- */
- public List<Taxon> getAllTaxa(int limit, int start);
-
- /**
- * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
- * @param sec The concept reference that the taxon belongs to
- * @return The List<Taxon> of root taxa.
- * @deprecated obsolete when using taxonomicTree
- */
- public List<Taxon> getRootTaxa(ReferenceBase sec);
-
-
- /**
- * Computes all Taxon instances that do not have a taxonomic parent.
- * @param sec The concept reference that the taxon belongs to
- *
- * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
- * @return The List<Taxon> of root taxa.
- * @deprecated obsolete when using taxonomicTree
- */
- public List<Taxon> getRootTaxa(ReferenceBase sec, CdmFetch cdmFetch, boolean onlyWithChildren);
-
- /**
- * Computes all Taxon instances that do not have a taxonomic parent.
- * @param sec The concept reference that the taxon belongs to
- * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
- * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
- * the misapplied name are not returned.<Br>Default: true.
- * @return The List<Taxon> of root taxa.
- * @deprecated obsolete when using taxonomicTree
- */
- public List<Taxon> getRootTaxa(ReferenceBase sec, boolean onlyWithChildren, boolean withMisapplications);
-
- /**
- * Computes all Taxon instances which name is of a certain Rank.
- * @param rank The rank of the taxon name
- * @param sec The concept reference that the taxon belongs to
- * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
- * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
- * the misapplied name are not returned.<Br>Default: true.
- * @param propertyPaths
- * properties to be initialized, For detailed description and
- * examples <b>please refer to:</b>
- * {@link BeanInitializer#initialize(Object, List)}. <Br>
- * Default: true.
- * @return The List<Taxon> of root taxa.
- * @deprecated obsolete when using taxonomicTree
- */
- public List<Taxon> getRootTaxa(Rank rank, ReferenceBase sec, boolean onlyWithChildren, boolean withMisapplications, List<String> propertyPaths);
-
- /**
- * Computes all relationships.
- * @param limit
- * @param start
- * @return
- */
+ /**
+ * Computes all Taxon instances that do not have a taxonomic parent.
+ * @param sec The concept reference that the taxon belongs to
+ *
+ * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
+ * @return The List<Taxon> of root taxa.
+ * @deprecated obsolete when using classification
+ */
+ @Deprecated
+ public List<Taxon> getRootTaxa(Reference sec, CdmFetch cdmFetch, boolean onlyWithChildren);
+
+ /**
+ * Computes all Taxon instances which name is of a certain Rank.
+ * @param rank The rank of the taxon name
+ * @param sec The concept reference that the taxon belongs to
+ * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
+ * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
+ * the misapplied name are not returned.<Br>Default: true.
+ * @param propertyPaths
+ * properties to be initialized, For detailed description and
+ * examples <b>please refer to:</b>
+ * {@link IBeanInitializer#initialize(Object, List)}. <Br>
+ * Default: true.
+ * @return The List<Taxon> of root taxa.
+ * @deprecated obsolete when using classification
+ */
+ @Deprecated
+ public List<Taxon> getRootTaxa(Rank rank, Reference sec, boolean onlyWithChildren, boolean withMisapplications, List<String> propertyPaths);
+
+ /**
+ * Computes all relationships.
+ * @param limit
+ * @param start
+ * @return
+ * FIXME candidate for harmonization - rename to listRelationships
+ */
public List<RelationshipBase> getAllRelationships(int limit, int start);
- /**
- * Returns TaxonRelationshipType vocabulary
- * @return
- * @deprecated use TermService#getVocabulary(VocabularyType) instead
- */
- public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();
-
- /**
- * Returns a list of taxa that matches the name string and the sec reference
- * @param name the name string to search for
- * @param sec the taxons sec reference
- * @return a list of taxa matching the name and the sec reference
- */
- public List<TaxonBase> searchTaxaByName(String name, ReferenceBase sec);
-
- /**
- * Changes an accepted taxon to a synonym of another taxon.
- *
- * @param oldTaxonNode
- * the <code>TaxonNode</code> of the accepted taxon that will be changed into a synonym
- * @param newAcceptedTaxonNode
- * the <code>TaxonNode</code> of the accepted taxon, the old taxon will become a synonym of
- * @param synonymType
- * <code>SynonymRelationshipType</code> to indicate whether hetero or homotypic
- * @param citation
- * the reference for this assumption
- * @param citationMicroReference
- * the micro citation
- * @return
- * the newly created synonym
- */
- public Synonym changeAcceptedTaxonToSynonym (TaxonNode oldTaxonNode, TaxonNode newAcceptedTaxonNode, SynonymRelationshipType synonymType, ReferenceBase citation, String citationMicroReference);
-
- /**
- * Swaps given synonym and accepted taxon.
- * In particular:
- * <ul>
- * <li>A new accepted taxon with the synonyms name is created</li>
- * <li>The synonym is deleted from the old accepted taxons synonym list</li>
- * <li>A new synonym with the name of the old accepted taxon is created</li>
- * <li>The newly created synonym get related to the newly created accepted taxon</li>
- * </ul>
- *
- * @param synonym
- * @param acceptedTaxon
- * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
- */
- public void swapSynonymAndAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
-
- /**
- * Change a synonym into an accepted taxon and removes
- * the synonym relationship to the given accepted taxon.
- *
- * @param synonym
- * the synonym to change into an accepted taxon
- * @param acceptedTaxon
- * an accepted taxon, the synonym had a relationship to
- * @return
- * the newly created accepted taxon
- */
- public Taxon changeSynonymToAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
-
- /**
- * Change a synonym into a related concept
- *
- * @param synonym
- * the synonym to change into the concept taxon
- * @param toTaxon
- * the taxon the newly created concept should be related to
- * @param taxonRelationshipType
- * the type of relationship
- * @param citation
- * @param microcitation
- * @return
- * the newly created concept
- */
- public Taxon changeSynonymToRelatedTaxon(Synonym synonym, Taxon toTaxon, TaxonRelationshipType taxonRelationshipType, ReferenceBase citation, String microcitation);
-
- /**
- * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
- * where the supplied taxon is relatedTo.
- *
- * @param taxon The taxon that is relatedTo
- * @param type The type of TaxonRelationship (can be null)
- * @param pageSize The maximum number of relationships returned (can be null for all relationships)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * @param orderHints Properties to order by
- * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
- * @return a List of TaxonRelationship instances
- */
- public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
-
-
-
- /**
- * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
- * where the supplied taxon is relatedTo.
- *
- * @param taxon The taxon that is relatedTo
- * @param type The type of TaxonRelationship (can be null)
- * @param pageSize The maximum number of relationships returned (can be null for all relationships)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * @param orderHints Properties to order by
- * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
- * @return a Pager of TaxonRelationship instances
- */
- public Pager<TaxonRelationship> pageToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
-
- /**
- * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
- * where the supplied taxon is relatedFrom.
- *
- * @param taxon The taxon that is relatedFrom
- * @param type The type of TaxonRelationship (can be null)
- * @param pageSize The maximum number of relationships returned (can be null for all relationships)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * @param orderHints Properties to order by
- * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
- * @return a List of TaxonRelationship instances
- */
- public List<TaxonRelationship> listFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
-
-
- /**
- * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
- * where the supplied taxon is relatedFrom.
- *
- * @param taxon The taxon that is relatedFrom
- * @param type The type of TaxonRelationship (can be null)
- * @param pageSize The maximum number of relationships returned (can be null for all relationships)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * @param orderHints Properties to order by
- * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
- * @return a Pager of TaxonRelationship instances
- */
- public Pager<TaxonRelationship> pageFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
-
- /**
- * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
- * where the supplied synonym is relatedFrom.
- *
- * @param taxon The synonym that is relatedFrom
- * @param type The type of SynonymRelationship (can be null)
- * @param pageSize The maximum number of relationships returned (can be null for all relationships)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * * @param orderHints Properties to order by
- * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
- * @return a Pager of SynonymRelationship instances
- */
- public Pager<SynonymRelationship> getSynonyms(Synonym synonym, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
-
- /**
- * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
- * where the supplied taxon is relatedTo.
- *
- * @param taxon The taxon that is relatedTo
- * @param type The type of SynonymRelationship (can be null)
- * @param pageSize The maximum number of relationships returned (can be null for all relationships)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * * @param orderHints Properties to order by
- * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
- * @return a Pager of SynonymRelationship instances
- */
- public Pager<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
-
- public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
-
- public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
-
- /**
- * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
- *
- * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
- * @param queryString
- * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * @param orderHints
- * Supports path like <code>orderHints.propertyNames</code> which
- * include *-to-one properties like createdBy.username or
- * authorTeam.persistentTitleCache
- * @param propertyPaths properties to be initialized
- * @return a Pager Taxon instances
- * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
- */
- public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
-
- /**
- * Returns a list of TaxonBase instances where the
- * taxon.name properties match the parameters passed.
- *
- * @param clazz optionally filter by class
- * @param uninomial
- * @param infragenericEpithet
- * @param specificEpithet
- * @param infraspecificEpithet
- * @param rank
- * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * @return a Pager of TaxonBase instances
- */
- public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
-
- /**
- * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
- * that match the properties specified in the configurator.
- * @param configurator
- * @return
- */
- public Pager<IdentifiableEntity> findTaxaAndNames(ITaxonServiceConfigurator configurator);
-
- /**
- *
- * @param taxon
- * @param size
- * @param height
- * @param widthOrDuration
- * @param mimeTypes
- * @return
- */
- public List<MediaRepresentation> getAllMedia(Taxon taxon, int size, int height, int widthOrDuration, String[] mimeTypes);
-
- public List<TaxonBase> findTaxaByID(Set<Integer> listOfIDs);
- /**
- * returns a list of inferred synonyms concerning the taxon with synonymrelationshiptype type
- * @param tree
- * @param taxon
- * @param type
- * @return
- */
- public List<Synonym> createInferredSynonyms(TaxonomicTree tree, Taxon taxon, SynonymRelationshipType type);
- /**
- * returns a list of all inferred synonyms (inferred epithet, inferred genus and potential combination) concerning the taxon
- * @param tree
- * @param taxon
- * @return
- */
- public List<Synonym> createAllInferredSynonyms(TaxonomicTree tree, Taxon taxon);
-
- public int countAllRelationships();
-
- public List<TaxonNameBase> findIdenticalTaxonNames(List<String> propertyPath);
- public List<TaxonNameBase> findIdenticalTaxonNameIds(List<String> propertyPath);
- public String getPhylumName(TaxonNameBase name);
-
- public long deleteSynonymRelationships(Synonym syn);
- /**
- * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
- * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
- *
- * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
- * @param type The type of SynonymRelationship (can be null)
- * @param pageSize The maximum number of relationships returned (can be null for all relationships)
- * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
- * @param orderHints Properties to order by
- * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
- * @param direction The direction of the relationship
- * @return a List of SynonymRelationship instances
- */
- public List<SynonymRelationship> listSynonymRelationships(
- TaxonBase taxonBase, SynonymRelationshipType type, Integer pageSize, Integer pageNumber,
- List<OrderHint> orderHints, List<String> propertyPaths, Direction direction);
+ /**
+ * Returns TaxonRelationshipType vocabulary
+ * @return
+ * @deprecated use TermService#getVocabulary(VocabularyType) instead
+ */
+ @Deprecated
+ public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();
+
+ /**
+ * Returns a list of taxa that matches the name string and the sec reference
+ * @param name the name string to search for
+ * @param sec the taxons sec reference
+ * @return a list of taxa matching the name and the sec reference
+ */
+ public List<TaxonBase> searchTaxaByName(String name, Reference sec);
+
+ /**
+ * Swaps given synonym and accepted taxon.
+ * In particular:
+ * <ul>
+ * <li>A new accepted taxon with the synonyms name is created</li>
+ * <li>The synonym is deleted from the old accepted taxons synonym list</li>
+ * <li>A new synonym with the name of the old accepted taxon is created</li>
+ * <li>The newly created synonym get related to the newly created accepted taxon</li>
+ * </ul>
+ *
+ * @param synonym
+ * @param acceptedTaxon
+ * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
+ */
+ public void swapSynonymAndAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
+
+ /**
+ * Changes a synonym into an accepted taxon and removes
+ * the synonym relationship to the given accepted taxon.
+ * Other synonyms homotypic to the synonym to change are
+ * moved to the same new accepted taxon as homotypic
+ * synonyms. The new accepted taxon has the same name and
+ * the same sec reference as the old synonym.<BR>
+ * If the given accepted taxon and the synonym are homotypic
+ * to each other an exception may be thrown as taxonomically it doesn't
+ * make sense to have two accepted taxa in the same homotypic group
+ * but also it is than difficult to decide how to handle other names
+ * in the homotypic group. It is up to the implementing class to
+ * handle this situation via an exception or in another way.
+ *
+ *
+ * @param synonym
+ * the synonym to change into an accepted taxon
+ * @param acceptedTaxon
+ * an accepted taxon, the synonym had a relationship to
+ * @param deleteSynonym
+ * if true the method tries to delete the old synonym from the database
+ * @param copyCitationInfo
+ * if true the citation and the microcitation of newly created synonyms
+ * is taken from the old synonym relationships.
+ * @param citation
+ * if given this citation is added to the newly created synonym
+ * relationships as citation. Only used if copyCitationInfo is <code> false</code>
+ * @param microCitation
+ * if given this microCitation is added to the newly created synonym
+ * relationships as microCitation.Only used if copyCitationInfo is <code> false</code>
+ * @return
+ * the newly created accepted taxon
+ * @throws IllegalArgumentException
+ * if the given accepted taxon and the synonym are homotypic
+ * to each other an exception may be thrown as taxonomically it doesn't
+ * make sense to have two accepted taxa in the same homotypic group
+ * but also it is than difficult to decide how to handle other names
+ * in the homotypic group. It is up to the implementing class to
+ * handle this situation via an exception or in another way.
+ */
+ public Taxon changeSynonymToAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon, boolean deleteSynonym, boolean copyCitationInfo, Reference citation, String microCitation) throws HomotypicalGroupChangeException;
+
+ /**
+ * TODO still needed and correct?
+ * Change a synonym into a related concept
+ *
+ * @param synonym
+ * the synonym to change into the concept taxon
+ * @param toTaxon
+ * the taxon the newly created concept should be related to
+ * @param taxonRelationshipType
+ * the type of relationship
+ * @param reference
+ * @param microReference
+ * @return
+ * the newly created concept
+ */
+ public Taxon changeSynonymToRelatedTaxon(Synonym synonym, Taxon toTaxon, TaxonRelationshipType taxonRelationshipType, Reference reference, String microReference);
+
+ /**
+ * TODO still needed and correct?
+ * Change a synonym into a related concept
+ *
+ * @param synonym
+ * the synonym to change into the concept taxon
+ * @param toTaxon
+ * the taxon the newly created concept should be related to
+ * @param taxonRelationshipType
+ * the type of relationship
+ * @param reference
+ * @param microReference
+ * @return
+ * the newly created concept
+ * @throws DataChangeNoRollbackException
+ */
+ public Synonym changeRelatedTaxonToSynonym(Taxon fromTaxon, Taxon toTaxon,
+ TaxonRelationshipType oldRelationshipType,
+ SynonymRelationshipType synonymRelationshipType) throws DataChangeNoRollbackException;
+ /**
+ * Deletes all synonym relationships of a given synonym. If taxon is given
+ * only those relationships to the taxon are deleted.
+ *
+ * @param syn
+ * the synonym
+ * @param taxon
+ * @return
+ * @deprecated This method must no longer being used since the
+ * SynonymRelationship is annotated at the {@link Taxon} and at
+ * the {@link Synonym} with <code>orphanDelete=true</code>. Just
+ * remove the from and to entities from the relationship and
+ * hibernate will care for the deletion. Using this method can cause
+ * <code>StaleStateException</code> (see http://dev.e-taxonomy.eu/trac/ticket/3797)
+ *
+ */
+ @Deprecated
+ public long deleteSynonymRelationships(Synonym syn, Taxon taxon);
+
+ /**
+ * Deletes a taxon from the underlying database according to the given {@link TaxonDeletionConfigurator configurator}.
+ * @param taxon
+ * @param config
+ *
+ */
+ public DeleteResult deleteTaxon(Taxon taxon, TaxonDeletionConfigurator config, Classification classification) ;
+
+ /**
+ * Changes the homotypic group of a synonym into the new homotypic group.
+ * All relations to taxa are updated correctly depending on the homotypic
+ * group of the accepted taxon. <BR>
+ * All existing basionym relationships to and from this name are removed.<BR>
+ * If the parameter <code>targetTaxon</code> is defined, the synonym is
+ * added to this taxon irrespctive of if it has been related to this
+ * taxon before.<BR>
+ * If <code>removeFromOtherTaxa</code> is true and <code>targetTaxon</code> is
+ * defined all relationships to other taxa are deleted.<BR>
+ * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
+ * between the existing basionym(s) of the new homotypic group and the synonyms name
+ * is added.<BR>
+ *
+ * @param synonym
+ * @param newHomotypicalGroup
+ * @param taxon
+ * @param setBasionymRelationIfApplicable
+ */
+ public void changeHomotypicalGroupOfSynonym(Synonym synonym, HomotypicalGroup newHomotypicalGroup, Taxon targetTaxon,
+ boolean removeFromOtherTaxa, boolean setBasionymRelationIfApplicable);
+
+
+ /**
+ * Moves a synonym to another taxon and removes the old synonym relationship.
+ *
+ * @param oldSynonymRelation the old synonym relationship defining the synonym to move and the old accepted taxon.
+ * @param newTaxon the taxon the synonym will be moved to
+ * @param moveHomotypicGroup if the synonym belongs to a homotypical group with other synonyms and
+ * <code>moveHomotypicGroup</code> is <code>true</code> all these synonyms are moved to the new taxon,
+ * if <code>false</code> a {@link HomotypicalGroupChangeException} is thrown.
+ * <code>MoveHomotypicGroup</code> has no effect if the synonym is the only synonym in it's homotypic group.
+ * @param newSynonymRelationshipType the synonym relationship type of the new synonym relations. Default is
+ * {@link SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF() heterotypic}.
+ * @param newReference The reference for the new synonym relation(s).
+ * @param newReferenceDetail The reference detail for the new synonym relation(s).
+ * @param keepReference if no <code>newReference</code> and/or no <code>newReferenceDetail</code>
+ * is defined they are taken from the old synonym relation(s) if <code>keepReference</code> is
+ * <code>true</code>. If <code>false</code> the reference and the reference detail will be taken
+ * only from the <code>newReference</code> and <code>newReferenceDetail</code>.
+ * @return The new synonym relationship. If <code>moveHomotypicGroup</code> is <code>true</code> additionally
+ * created new synonym relationships must be retrieved separately from the new taxon.
+ * @throws HomotypicalGroupChangeException Exception is thrown if (1) synonym is homotypic to the old accepted taxon or
+ * (2) synonym is in homotypic group with other synonyms and <code>moveHomotypicGroup</code> is false
+ */
+ public SynonymRelationship moveSynonymToAnotherTaxon(SynonymRelationship oldSynonymRelation, Taxon newTaxon, boolean moveHomotypicGroup,
+ SynonymRelationshipType newSynonymRelationshipType, Reference newReference, String newReferenceDetail, boolean keepReference) throws HomotypicalGroupChangeException;
+
+ /**
+ * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
+ * where the supplied taxon is relatedTo.
+ *
+ * @param taxon The taxon that is relatedTo
+ * @param type The type of TaxonRelationship (can be null)
+ * @param pageSize The maximum number of relationships returned (can be null for all relationships)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * @param orderHints Properties to order by
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
+ * @return a List of TaxonRelationship instances
+ */
+ public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
+
+
+
+ /**
+ * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
+ * where the supplied taxon is relatedTo.
+ *
+ * @param taxon The taxon that is relatedTo
+ * @param type The type of TaxonRelationship (can be null)
+ * @param pageSize The maximum number of relationships returned (can be null for all relationships)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * @param orderHints Properties to order by
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
+ * @return a Pager of TaxonRelationship instances
+ */
+ public Pager<TaxonRelationship> pageToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
+
+ /**
+ * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
+ * where the supplied taxon is relatedFrom.
+ *
+ * @param taxon The taxon that is relatedFrom
+ * @param type The type of TaxonRelationship (can be null)
+ * @param pageSize The maximum number of relationships returned (can be null for all relationships)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * @param orderHints Properties to order by
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
+ * @return a List of TaxonRelationship instances
+ */
+ public List<TaxonRelationship> listFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
+
+
+ /**
+ * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
+ * where the supplied taxon is relatedFrom.
+ *
+ * @param taxon The taxon that is relatedFrom
+ * @param type The type of TaxonRelationship (can be null)
+ * @param pageSize The maximum number of relationships returned (can be null for all relationships)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * @param orderHints Properties to order by
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
+ * @return a Pager of TaxonRelationship instances
+ */
+ public Pager<TaxonRelationship> pageFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
+
+ /**
+ * lists all taxa which are related to the <code>taxon</code> given as
+ * parameter.
+ *
+ * @param taxon
+ * @param includeRelationships
+ * @param maxDepth
+ * <code>1</code> for one level, <code>null</code> for infinite
+ * depth, <code>0</code> will completely omit collecting related taxa.
+ * @param limit
+ * @param start
+ * @param propertyPaths
+ * @return
+ */
+ public Set<Taxon> listRelatedTaxa(Taxon taxon, Set<TaxonRelationshipEdge> includeRelationships, Integer maxDepth,
+ Integer limit, Integer start, List<String> propertyPaths);
+
+ /**
+ * lists all accepted taxa for the given {@link Synonym}
+ *
+ * @param taxonBase
+ * @param limit
+ * @param start
+ * @param propertyPaths
+ * @return
+ */
+ public List<Classification> listClassifications(TaxonBase taxonBase, Integer limit, Integer start, List<String> propertyPaths);
+
+ /**
+ * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
+ * where the supplied synonym is relatedFrom.
+ *
+ * @param taxon The synonym that is relatedFrom
+ * @param type The type of SynonymRelationship (can be null)
+ * @param pageSize The maximum number of relationships returned (can be null for all relationships)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * * @param orderHints Properties to order by
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
+ * @return a Pager of SynonymRelationship instances
+ */
+ public Pager<SynonymRelationship> getSynonyms(Synonym synonym, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
+
+ /**
+ * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
+ * where the supplied taxon is relatedTo.
+ *
+ * @param taxon The taxon that is relatedTo
+ * @param type The type of SynonymRelationship (can be null)
+ * @param pageSize The maximum number of relationships returned (can be null for all relationships)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * * @param orderHints Properties to order by
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
+ * @return a Pager of SynonymRelationship instances
+ */
+ public Pager<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
+
+ /**
+ * This method returns in the first entry the list of synonyms of the
+ * homotypic group of the accepted taxon. All other entries represent the lists of heterotypic
+ * synonym groups. For detailed information about these 2 groups see
+ * {@link #getHomotypicSynonymsByHomotypicGroup(Taxon, List)} and
+ * {@link #getHeterotypicSynonymyGroups(Taxon, List)}
+ *
+ * @see #getSynonyms()
+ * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
+ * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
+
+ * @param taxon the accepted taxon
+ * @param propertyPaths the property path
+ * @return the list of groups of synonyms
+ */
+ public List<List<Synonym>> getSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
+
+
+ /**
+ * Returns the list of all synonyms that share the same homotypical group with the given taxon.
+ * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
+ * @param taxon
+ * @param propertyPaths
+ * @return
+ */
+ public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
+
+ /**
+ * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
+ * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
+ * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
+ * belong to a homotypical group which cannot be the homotypical group to which the
+ * taxon name of the given taxon belongs. This method does not return the homotypic group the given
+ * taxon belongs to.<BR>
+ * This method does neglect the type of synonym relationship that is defined between the given taxon
+ * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
+ * in one of the result lists as long as the synonym does not belong to the same homotypic group as
+ * the given taxon.<BR>
+ * The list returned is ordered according to the date of publication of the
+ * first published name within each homotypical group.
+ *
+ * @see #getHeterotypicSynonymyGroups()
+ * @see #getSynonyms()
+ * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
+ * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
+
+ * @param taxon
+ * @param propertyPaths
+ * @return
+ */
+ public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
+
+ /**
+ * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
+ *
+ * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
+ * @param queryString
+ * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * @param orderHints
+ * Supports path like <code>orderHints.propertyNames</code> which
+ * include *-to-one properties like createdBy.username or
+ * authorTeam.persistentTitleCache
+ * @param propertyPaths properties to be initialized
+ * @return a Pager Taxon instances
+ * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
+ */
+ @Override
+ public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
+
+ /**
+ * Returns a list of TaxonBase instances where the
+ * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
+ * <i>null</i> will search for those taxa with a value of null in that field
+ *
+ * @param clazz optionally filter by class (can be null to return all taxa)
+ * @param uninomial
+ * @param infragenericEpithet
+ * @param specificEpithet
+ * @param infraspecificEpithet
+ * @param rank
+ * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * @return a list of TaxonBase instances
+ */
+ public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
+
+ /**
+ * Returns a list of TaxonBase instances where the
+ * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
+ * <i>null</i> will search for those taxa with a value of null in that field
+ *
+ * @param clazz optionally filter by class
+ * @param uninomial
+ * @param infragenericEpithet
+ * @param specificEpithet
+ * @param infraspecificEpithet
+ * @param rank
+ * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * @return a List of TaxonBase instances
+ */
+ public List<TaxonBase> listTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
+
+ /**
+ * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
+ * that match the properties specified in the configurator.
+ * @param configurator
+ * @return
+ */
+ public Pager<IdentifiableEntity> findTaxaAndNames(IFindTaxaAndNamesConfigurator configurator);
+
+ /**
+ * performes a union searches for TaxonBase instances on all available
+ * free text indexes. At the time of writing this documentation it combines
+ * {@link #findByDescriptionElementFullText(Class, String, Classification, List, List, boolean, Integer, Integer, List, List)}
+ * and {@link #findByFullText(Class, String, Classification, List, boolean, Integer, Integer, List, List)
+ *
+ * @param queryString
+ * the query string
+ * @param classification
+ * Additional filter criterion: If a taxonomic classification
+ * three is specified here the result set will only contain taxa
+ * of the given classification
+ * @param languages
+ * Additional filter criterion: Search only in these languages.
+ * Not all text fields in the cdm model are multilingual, thus
+ * this setting will only apply to the multilingiual fields.
+ * Other fields are searched nevertheless if this parameter is
+ * set or not.
+ * @param highlightFragments
+ * TODO
+ * @param pageSize
+ * The maximum number of objects returned (can be null for all
+ * objects)
+ * @param pageNumber
+ * The offset (in pageSize chunks) from the start of the result
+ * set (0 - based)
+ * @param orderHints
+ * Supports path like <code>orderHints.propertyNames</code> which
+ * include *-to-one properties like createdBy.username or
+ * authorTeam.persistentTitleCache
+ * @param propertyPaths
+ * properties to initialize - see
+ * {@link IBeanInitializer#initialize(Object, List)}
+ * @return a paged list of instances of type T matching the queryString and
+ * the additional filter criteria
+ * @return
+ * @throws CorruptIndexException
+ * @throws IOException
+ * @throws ParseException
+ * @throws LuceneMultiSearchException
+ * @deprecated this search should fully be covered by the new method
+ * {@link #findTaxaAndNamesByFullText(EnumSet, String, Classification, Set, List, boolean, Integer, Integer, List, List)}
+ * , maybe we should rename this latter method to give it a more meaningful name
+ */
+ @Deprecated
+ public Pager<SearchResult<TaxonBase>> findByEverythingFullText(String queryString,
+ Classification classification, List<Language> languages, boolean highlightFragments,
+ Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException, LuceneMultiSearchException;
+
+ /**
+ * Searches for TaxonBase instances using the TaxonBase free text index.
+ *
+ * <h4>This is an experimental feature, it may be moved, modified, or even
+ * removed in future releases!!!</h4>
+ *
+ * @param clazz
+ * Additional filter criterion: The specific TaxonBase subclass
+ * to search for
+ * @param queryString
+ * the query string
+ * @param classification
+ * Additional filter criterion: If a taxonomic classification
+ * three is specified here the result set will only contain taxa
+ * of the given classification
+ * @param languages
+ * Additional filter criterion: Search only in these languages.
+ * Not all text fields in the cdm model are multilingual, thus
+ * this setting will only apply to the multilingiual fields.
+ * Other fields are searched nevertheless if this parameter is
+ * set or not.
+ * @param highlightFragments
+ * TODO
+ * @param pageSize
+ * The maximum number of objects returned (can be null for all
+ * objects)
+ * @param pageNumber
+ * The offset (in pageSize chunks) from the start of the result
+ * set (0 - based)
+ * @param orderHints
+ * Supports path like <code>orderHints.propertyNames</code> which
+ * include *-to-one properties like createdBy.username or
+ * authorTeam.persistentTitleCache
+ * @param propertyPaths
+ * properties to initialize - see
+ * {@link IBeanInitializer#initialize(Object, List)}
+ * @return a paged list of instances of type T matching the queryString and
+ * the additional filter criteria
+ * @throws CorruptIndexException
+ * @throws IOException
+ * @throws ParseException
+ */
+ public Pager<SearchResult<TaxonBase>> findByFullText(Class<? extends TaxonBase> clazz, String queryString, Classification classification,
+ List<Language> languages, boolean highlightFragments, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints,
+ List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException;
+
+
+ /**
+ * @param areaFilter
+ * @param statusFilter
+ * @param classification
+ * Additional filter criterion: If a taxonomic classification
+ * three is specified here the result set will only contain taxa
+ * of the given classification
+ * @param highlightFragments
+ * @param pageSize
+ * The maximum number of objects returned (can be null for all
+ * objects)
+ * @param pageNumber
+ * The offset (in pageSize chunks) from the start of the result
+ * set (0 - based)
+ * @param orderHints
+ * Supports path like <code>orderHints.propertyNames</code> which
+ * include *-to-one properties like createdBy.username or
+ * authorTeam.persistentTitleCache
+ * @param propertyPath
+ * Common properties to initialize the instances of the
+ * CDM types ({@link Taxon} and {@link Synonym}
+ * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
+ * @return a paged list of instances of {@link Taxon} instances
+ * @throws IOException
+ * @throws ParseException
+ */
+ public Pager<SearchResult<TaxonBase>> findByDistribution(List<NamedArea> areaFilter, List<PresenceAbsenceTermBase<?>> statusFilter,
+ Classification classification,
+ Integer pageSize, Integer pageNumber,
+ List<OrderHint> orderHints, List<String> propertyPaths) throws IOException, ParseException;
+
+ /**
+ * Searches for TaxonBase instances using the TaxonBase free text index.
+ *
+ *
+ *
+ * <h4>This is an experimental feature, it may be moved, modified, or even
+ * removed in future releases!!!</h4>
+ * @param searchModes
+ * Additional filter criterion: defaults to [doTaxa] if set null
+ * @param queryString
+ * the query string
+ * @param classification
+ * Additional filter criterion: If a taxonomic classification
+ * three is specified here the result set will only contain taxa
+ * of the given classification
+ * @param namedAreas
+ * @param languages
+ * Additional filter criterion: Search only in these languages.
+ * Not all text fields in the cdm model are multilingual, thus
+ * this setting will only apply to the multilingiual fields.
+ * Other fields are searched nevertheless if this parameter is
+ * set or not.
+ * @param highlightFragments
+ * TODO
+ * @param pageSize
+ * The maximum number of objects returned (can be null for all
+ * objects)
+ * @param pageNumber
+ * The offset (in pageSize chunks) from the start of the result
+ * set (0 - based)
+ * @param orderHints
+ * Supports path like <code>orderHints.propertyNames</code> which
+ * include *-to-one properties like createdBy.username or
+ * authorTeam.persistentTitleCache
+ * @param propertyPath
+ * Common properties to initialize the instances of the
+ * CDM types ({@link Taxon} and {@link Synonym}
+ * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
+ * @return a paged list of instances of {@link Taxon}, {@link Synonym}, matching the queryString and
+ * the additional filter criteria
+ * @throws CorruptIndexException
+ * @throws IOException
+ * @throws ParseException
+ * @throws LuceneMultiSearchException
+ */
+ public Pager<SearchResult<TaxonBase>> findTaxaAndNamesByFullText(
+ EnumSet<TaxaAndNamesSearchMode> searchModes,
+ String queryString, Classification classification, Set<NamedArea> namedAreas, Set<PresenceAbsenceTermBase<?>> distributionStatus,
+ List<Language> languages, boolean highlightFragments, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints,
+ List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException, LuceneMultiSearchException;
+
+ /**
+ * Searches for TaxonBase instances by using the DescriptionElement free text index.
+ *
+ * <h4>This is an experimental feature, it may be moved, modified, or even
+ * removed in future releases!!!</h4>
+ *
+ * @param clazz
+ * Additional filter criterion:
+ * @param queryString
+ * the query string to filter by
+ * @param classification
+ * Additional filter criterion: If a taxonomic classification
+ * three is specified here the result set will only contain taxa
+ * of the given classification
+ * @param features
+ * TODO
+ * @param languages
+ * Additional filter criterion: Search only in these languages.
+ * Not all text fields in the cdm model are multilingual, thus
+ * this setting will only apply to the multilingiual fields.
+ * Other fields are searched nevertheless if this parameter is
+ * set or not.
+ * @param highlightFragments
+ * TODO
+ * @param pageSize
+ * The maximum number of objects returned (can be null for all
+ * objects)
+ * @param pageNumber
+ * The offset (in pageSize chunks) from the start of the result
+ * set (0 - based)
+ * @param orderHints
+ * Supports path like <code>orderHints.propertyNames</code> which
+ * include *-to-one properties like createdBy.username or
+ * authorTeam.persistentTitleCache
+ * @param propertyPaths
+ * properties to initialize - see
+ * {@link IBeanInitializer#initialize(Object, List)}
+ * @return a paged list of instances of type T matching the queryString and
+ * the additional filter criteria
+ * @throws IOException
+ * @throws CorruptIndexException
+ * @throws ParseException
+ */
+ public Pager<SearchResult<TaxonBase>> findByDescriptionElementFullText(Class<? extends DescriptionElementBase> clazz, String queryString, Classification classification, List<Feature> features, List<Language> languages, boolean highlightFragments, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException;
+
+
+ /**
+ *
+ * @param taxon
+ * @param size
+ * @param height
+ * @param widthOrDuration
+ * @param mimeTypes
+ * @return
+ *
+ * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
+ */
+ @Deprecated
+ public List<MediaRepresentation> getAllMedia(Taxon taxon, int size, int height, int widthOrDuration, String[] mimeTypes);
+
+
+ /**
+ * Lists all Media found in an any TaxonDescription associated with this
+ * taxon.
+ *
+ * @param taxon
+ * @param includeRelationships
+ * the given list of TaxonRelationshipEdges will be taken into
+ * account when retrieving media associated with the given taxon.
+ * Can be NULL.
+ * @param limitToGalleries
+ * whether to take only TaxonDescription into account which are
+ * marked as gallery
+ * @return
+ * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
+ */
+ @Deprecated
+ public List<Media> listTaxonDescriptionMedia(Taxon taxon, Set<TaxonRelationshipEdge> includeRelationships, boolean limitToGalleries, List<String> propertyPath);
+
+ /**
+ * Lists all Media found in an any TaxonDescription, NameDescription,
+ * SpecimenOrObservationBase, DnaSample Chromatograms, etc. associated with this taxon.
+ *
+ * @param taxon
+ * @param includeRelationships
+ * the given list of TaxonRelationshipEdges will be taken into
+ * account when retrieving media associated with the given taxon.
+ * Can be NULL.
+ * @param limitToGalleries
+ * whether to take only descriptions into account which are
+ * marked as gallery, can be NULL
+ * @param includeTaxonDescriptions
+ * whether to take TaxonDescriptions into account, can be NULL
+ * @param includeOccurrences
+ * whether to take TaxonDescriptions into account, can be NULL
+ * @param includeTaxonNameDescriptions
+ * whether to take TaxonNameDescriptions into account, can be NULL
+ * @param propertyPath
+ * @return
+ */
+ public List<Media> listMedia(Taxon taxon, Set<TaxonRelationshipEdge> includeRelationships,
+ Boolean limitToGalleries, Boolean includeTaxonDescriptions, Boolean includeOccurrences,
+ Boolean includeTaxonNameDescriptions, List<String> propertyPath);
+
+ public List<TaxonBase> findTaxaByID(Set<Integer> listOfIDs);
+
+ /**
+ * Returns the TaxonBase with the given UUID
+ * using the given match mode and initialization strategy
+ *
+ * @param uuid
+ * @param propertyPaths
+ * @return
+ */
+ public TaxonBase findTaxonByUuid(UUID uuid, List<String> propertyPaths);
+
+ public int countAllRelationships();
+
+ public List<TaxonNameBase> findIdenticalTaxonNames(List<String> propertyPath);
+
+ public List<TaxonNameBase> findIdenticalTaxonNameIds(List<String> propertyPath);
+
+ public String getPhylumName(TaxonNameBase name);
+
+ public long deleteSynonymRelationships(Synonym syn);
+
+ /**
+ * Returns all {@link Taxon taxa} which are {@link TaxonRelationshipType#CONGRUENT_TO() congruent} or
+ * {@link TaxonRelationshipType#INCLUDES() included} in the taxon represented by the given taxon uuid.
+ * The result also returns the path to these taxa represented by the uuids of
+ * the {@link TaxonRelationshipType taxon relationships types} and doubtful information.
+ * If classificationUuids is set only taxa of classifications are returned which are included
+ * in the given {@link Classification classifications}. ALso the path to these taxa may not include
+ * taxa from other classifications.
+ * @param taxonUuid uuid of the original taxon
+ * @param classificationUuids List of uuids of classifications used as a filter
+ * @param includeDoubtful set to <code>true</code> if also doubtfully included taxa should be included in the result
+ * @return a DTO which includes a list of taxa with the pathes from the original taxon to the given taxon as well
+ * as doubtful and date information. The original taxon is included in the result.
+ */
+ public IncludedTaxaDTO listIncludedTaxa(UUID taxonUuid, IncludedTaxonConfiguration configuration);
+
+
+ /**
+ * Removes a synonym.<BR><BR>
+ *
+ * In detail it removes
+ * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
+ * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
+ * <BR><BR>
+ * If <code>removeNameIfPossible</code> is true
+ * it also removes the synonym name if it is not used in any other context
+ * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
+ * If <code>newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
+ * the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
+ *
+ * If synonym is <code>null</code> the method has no effect.
+ *
+ * @param taxon
+ * @param synonym
+ * @param removeNameIfPossible
+ * @return deleteResult
+ *
+ */
+ public DeleteResult deleteSynonym(Synonym synonym, SynonymDeletionConfigurator config);
+
+
+ /**
+ * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
+ * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
+ *
+ * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
+ * @param type The type of SynonymRelationship (can be null)
+ * @param pageSize The maximum number of relationships returned (can be null for all relationships)
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
+ * @param orderHints Properties to order by
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
+ * @param direction The direction of the relationship
+ * @return a List of SynonymRelationship instances
+ */
+ public List<SynonymRelationship> listSynonymRelationships(
+ TaxonBase taxonBase, SynonymRelationshipType type, Integer pageSize, Integer pageNumber,
+ List<OrderHint> orderHints, List<String> propertyPaths, Direction direction);
+
+ /**
+ * @param tnb
+ * @return
+ */
+ public Taxon findBestMatchingTaxon(String taxonName);
+
+ public Taxon findBestMatchingTaxon(MatchingTaxonConfigurator config);
+
+ public Synonym findBestMatchingSynonym(String taxonName);
+
+ public List<UuidAndTitleCache<TaxonBase>> getUuidAndTitleCacheTaxon();
+
+ public List<UuidAndTitleCache<TaxonBase>> getUuidAndTitleCacheSynonym();
+
+ public List<UuidAndTitleCache<TaxonBase>> findTaxaAndNamesForEditor(IFindTaxaAndNamesConfigurator configurator);
+
+ /**
+ * Creates the specified inferred synonyms for the taxon in the classification, but do not insert it to the database
+ * @param taxon
+ * @param tree
+ * @return list of inferred synonyms
+ */
+ public List<Synonym> createInferredSynonyms(Taxon taxon, Classification tree, SynonymRelationshipType type, boolean doWithMisappliedNames);
+
+ /**
+ * Creates all inferred synonyms for the taxon in the classification, but do not insert it to the database
+ * @param taxon
+ * @param tree
+ * @param iDatabase
+ * @return list of inferred synonyms
+ */
+ public List<Synonym> createAllInferredSynonyms(Taxon taxon, Classification tree, boolean doWithMisappliedNames);
+
+
+
+
+ /**
+ * Removes a synonym.<BR><BR>
+ *
+ * In detail it removes
+ * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
+ * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
+ * <BR><BR>
+ * If <code>config.removeNameIfPossible</code> is true
+ * it also removes the synonym name if it is not used in any other context
+ * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
+ * If <code>config.newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
+ * the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
+ *
+ * If synonym is <code>null</code> the method has no effect.
+ *
+ * @param taxon
+ * @param synonym
+ * @param config
+ * @return deleteResult
+ */
+ DeleteResult deleteSynonym(Synonym synonym, Taxon taxon,
+ SynonymDeletionConfigurator config);
+
+ public Pager<Taxon> pageAcceptedTaxaFor(UUID synonymUuid, UUID classificationUuid, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints,
+ List<String> propertyPaths);
+
+ public List<Taxon> listAcceptedTaxaFor(UUID synonymUuid, UUID classificationUuid, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints,
+ List<String> propertyPaths);
+
+ public List<TaxonBase> findTaxaByName(MatchingTaxonConfigurator config);
+
+
+
+
+
+
+
}