+// $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.net.URI;
import java.util.Collection;
+import java.util.Enumeration;
import java.util.List;
-import java.util.Map;
+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.TermBase;
-import eu.etaxonomy.cdm.model.common.TermVocabulary;
-import eu.etaxonomy.cdm.model.name.TaxonNameBase;
+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.common.TermType;
+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 IService<DefinedTermBase> {
+public interface ITermService extends IIdentifiableEntityService<DefinedTermBase> {
- public abstract DefinedTermBase getTermByUri(String uri);
+ /**
+ * Returns a term according to it's uri
+ * @param uri
+ * @return
+ */
+ public DefinedTermBase getByUri(URI uri);
- public abstract DefinedTermBase getTermByUuid(UUID uuid);
+ public UUID saveLanguageData(LanguageStringBase languageData);
- /**
- * @param limit
- * @param start
- * @return
- */
- public abstract List<DefinedTermBase> getAllDefinedTerms(int limit, int start);
+ public List<LanguageString> getAllLanguageStrings(int limit, int start);
- public abstract TermVocabulary getVocabulary(UUID vocabularyUuid);
-
- public abstract Set<TermVocabulary> listVocabularies(Class termClass);
+ public List<Representation> getAllRepresentations(int limit, int start);
- /**
- * @param termBase
- * @return
- */
- public abstract UUID saveTerm(DefinedTermBase termBase);
+ public Language getLanguageByIso(String iso639);
- public Map<UUID, DefinedTermBase> saveTermsAll(Collection<DefinedTermBase> termBaseCollection);
+ 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(Collection<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);
+
+ /**
+ * Retrieves all {@link DefinedTermBase}s with the given {@link TermType}
+ * @param termType the term type to filter the terms
+ * @param limit
+ * @param start
+ * @param orderHints
+ * @param propertyPaths
+ * @return a list containing the terms
+ */
+ public List<DefinedTermBase<?>> listByTermType(TermType termType, 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);
+
+ /**
+ * Returns the term with the given idInVocabulary for the given vocabulary.
+ * If the same idInVocabulary exists with same vocabulary for multiple terms (though this is against the general
+ * contract of idInVocabulary) always the same term should be returned.
+ * @param id idInVocabulary
+ * @param vocabularyUuid uuid of vocabulary
+ * @param clazz term clazz filter on certain term classes. May be <code>null</code> for no filter.
+ * @return the term
+ * @throws IllegalArgumentException if id or vocabularyUuid is <code>null</code>
+ */
+ public <TERM extends DefinedTermBase> TERM findByIdInVocabulary(String id, UUID vocabularyUuid, Class<TERM> clazz)
+ throws IllegalArgumentException;
}