EDIT

// $Id$

* 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.

*/

import java.util.List;

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

import eu.etaxonomy.cdm.model.taxon.TaxonBase;

import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;

public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{

	 * Computes all taxon bases.

	 * @param start

	 * @return

	 */

	/**

	 * Computes all taxon bases.

	 * @param start

	 * @return

	 */

	 * 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.

	/**

	 * 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.

	 * 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.

	 * 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.

	 *            properties to be initialized, For detailed description and

	 *            examples <b>please refer to:</b>

	 *            {@link BeanInitializer#initialize(Object, List)}. <Br>

	 *            Default: true.

	 * Computes all relationships.

	 * @param limit

	 * @param start

	 * @return

	 */

	 * Returns TaxonRelationshipType vocabulary

	 * @return

	public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();

	/** */

	 * Changes an accepted taxon to a synonym of another taxon. 

	 * 

	 * @param oldTaxon

	 * 				the accepted taxon that will be changed into a synonym

	 * @param newAcceptedTaxon

	 * 				the accepted taxon, the old taxon will become a synonym of

	 * @param synonymType

	 * 				the reference for this assumption

	 * @param citationMicroReference

	 * 				the micro citation

	 * @return

	 * 				the newly created synonym

	 */

	 * 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

	 */

	 * Change a synonym into an accepted taxon and removes existing 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 makeSynonymAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);

	 * 

	 * @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 propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}

	 */

	public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);

	 * 

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

	 */

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

	 * 

	 * @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 propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}

	 */

	public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);

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

	 *            Supports path like <code>orderHints.propertyNames</code> which

	 *            include *-to-one properties like createdBy.username or

	 *            authorTeam.persistentTitleCache

	 * @param propertyPaths properties to be initialized

	 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>

	 */

	/**

	 * 

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

	 */

	/**

	 * 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 height

	 * @param widthOrDuration

	 * @param mimeTypes

	 * @return