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.

*/

package eu.etaxonomy.cdm.api.service;

import java.net.URI;

import java.util.Enumeration;

import java.util.List;

import java.util.Locale;

import java.util.Set;

import java.util.UUID;

import eu.etaxonomy.cdm.api.service.config.TermDeletionConfigurator;

import eu.etaxonomy.cdm.api.service.pager.Pager;

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

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

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

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

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

import eu.etaxonomy.cdm.model.location.NamedArea;

import eu.etaxonomy.cdm.model.location.NamedAreaLevel;

import eu.etaxonomy.cdm.model.location.NamedAreaType;

import eu.etaxonomy.cdm.model.media.Media;

import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;

import eu.etaxonomy.cdm.persistence.query.OrderHint;

public interface ITermService extends IIdentifiableEntityService<DefinedTermBase> {

	/**

	 * Returns a term according to it's uri

	 * @param uri

	 * @return

	 */

	public DefinedTermBase getByUri(URI uri);

	public UUID saveLanguageData(LanguageStringBase languageData);

	public List<LanguageString> getAllLanguageStrings(int limit, int start);

	public List<Representation> getAllRepresentations(int limit, int start);

	public Language getLanguageByIso(String iso639);

	public List<Language> getLanguagesByLocale(Enumeration<Locale> locales);

	public NamedArea getAreaByTdwgAbbreviation(String tdwgAbbreviation);

	 /**

     * Returns a paged list of Media that represent a given DefinedTerm instance

     * 

	 * @param definedTerm the definedTerm represented by these media

	 * @param pageSize The maximum number of media returned (can be null for all related media)

	 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)

     * @return a Pager of media instances

     */

	public Pager<Media> getMedia(DefinedTermBase definedTerm, Integer pageSize, Integer pageNumber);

	/**

	 * Returns a paged list of NamedArea instances (optionally filtered by type or level)

	 * 

	 * @param level restrict the result set to named areas of a certain level (can be null)

	 * @param type restrict the result set to named areas of a certain type (can be null)

	 * @param pageSize The maximum number of namedAreas returned (can be null for all named areas)

	 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)

	 * @return a Pager of named areas

	 */

	public Pager<NamedArea> list(NamedAreaLevel level, NamedAreaType type, Integer pageSize, Integer pageNumber,  List<OrderHint> orderHints, List<String> propertyPaths);

	/**

	 * Return a paged list of terms which are specializations of a given definedTerm

	 * 

	 * @param definedTerm The term which is a generalization of the terms returned

	 * @param pageSize The maximum number of terms returned (can be null for all specializations)

	 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)

	 * @return a Pager of DefinedTerms

	 */

	public <T extends DefinedTermBase> Pager<T> getGeneralizationOf(T definedTerm, Integer pageSize, Integer pageNumber);

	/**

	 * Return a paged list of distinct terms which include the terms supplied

	 * 

	 * @param definedTerms the set of terms which are part of the terms of interest 

	 * @param pageSize The maximum number of terms returned (can be null for all terms)

	 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)

	 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}

	 * @return a Pager of DefinedTerms

	 */

	public <T extends DefinedTermBase> Pager<T> getPartOf(Set<T> definedTerms, Integer pageSize, Integer pageNumber, List<String> propertyPaths);

	/**

	 * Return a paged list of terms which are part of the terms supplied

	 * 

	 * @param definedTerms the set of terms which include the terms of interest 

	 * @param pageSize The maximum number of terms returned (can be null for all terms)

	 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)

	 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}

	 * @return a Pager of DefinedTerms

	 */

	public <T extends DefinedTermBase> Pager<T> getIncludes(Set<T> definedTerms, Integer pageSize, Integer pageNumber, List<String> propertyPaths);

	/**

	 * Return a paged list of terms which have representations that match the supplied string in the text (description)

	 * 

	 * @param label a string to match (exactly)

	 * @param pageSize The maximum number of terms returned (can be null for all terms)

	 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)

	 * @return a Pager of DefinedTerms

	 */

	public <T extends DefinedTermBase> Pager<T> findByRepresentationText(String label, Class<T> clazz,  Integer pageSize, Integer pageNumber);

	/**

	 * Return a paged list of terms which have representations that match the supplied string in the abbreviated label

	 * 

	 * @param label a string to match (exactly)

	 * @param pageSize The maximum number of terms returned (can be null for all terms)

	 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)

	 * @return a Pager of DefinedTerms

	 */

	public <T extends DefinedTermBase> Pager<T> findByRepresentationAbbreviation(String abbrev, Class<T> clazz, Integer pageSize, Integer pageNumber);

	/**

	 * 

	 * @param <TERM>

	 * @param clazz

	 * @param limit

	 * @param start

	 * @param orderHints

	 * @param propertyPaths

	 * @return

	 */

	public <TERM extends DefinedTermBase> List<TERM> listByTermClass(Class<TERM> clazz, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);

	/**

	 * Delete the given term according to the given delete configuration. 

	 * In case a problem occurrs while deleting the term the result will reflect this

	 * via its status.

	 * @param term the term to delete

	 * @param config the configurator

	 * @return DeleteResult which holds the status of the deletion.

	 */

	public DeleteResult delete(DefinedTermBase term, TermDeletionConfigurator config);

}