cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/ITermService.java

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10
  11 package eu.etaxonomy.cdm.api.service;
  12
  13 import java.net.URI;
  14 import java.util.Collection;
  15 import java.util.Enumeration;
  16 import java.util.List;
  17 import java.util.Locale;
  18 import java.util.Set;
  19 import java.util.UUID;
  20
  21 import eu.etaxonomy.cdm.api.service.config.TermDeletionConfigurator;
  22 import eu.etaxonomy.cdm.api.service.pager.Pager;
  23 import eu.etaxonomy.cdm.model.common.DefinedTermBase;
  24 import eu.etaxonomy.cdm.model.common.Language;
  25 import eu.etaxonomy.cdm.model.common.LanguageString;
  26 import eu.etaxonomy.cdm.model.common.LanguageStringBase;
  27 import eu.etaxonomy.cdm.model.common.Representation;
  28 import eu.etaxonomy.cdm.model.common.TermType;
  29 import eu.etaxonomy.cdm.model.location.NamedArea;
  30 import eu.etaxonomy.cdm.model.location.NamedAreaLevel;
  31 import eu.etaxonomy.cdm.model.location.NamedAreaType;
  32 import eu.etaxonomy.cdm.model.media.Media;
  33 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  34 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  35
  36 public interface ITermService extends IIdentifiableEntityService<DefinedTermBase> {
  37
  38     /**
  39      * Returns a term according to it's uri
  40      * @param uri
  41      * @return
  42      */
  43     public DefinedTermBase getByUri(URI uri);
  44
  45     public UUID saveLanguageData(LanguageStringBase languageData);
  46
  47     public List<LanguageString> getAllLanguageStrings(int limit, int start);
  48
  49     public List<Representation> getAllRepresentations(int limit, int start);
  50
  51     public Language getLanguageByIso(String iso639);
  52
  53     public List<Language> getLanguagesByLocale(Enumeration<Locale> locales);
  54
  55     public NamedArea getAreaByTdwgAbbreviation(String tdwgAbbreviation);
  56
  57      /**
  58      * Returns a paged list of Media that represent a given DefinedTerm instance
  59      *
  60      * @param definedTerm the definedTerm represented by these media
  61      * @param pageSize The maximum number of media returned (can be null for all related media)
  62      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  63      * @return a Pager of media instances
  64      */
  65     public Pager<Media> getMedia(DefinedTermBase definedTerm, Integer pageSize, Integer pageNumber);
  66
  67     /**
  68      * Returns a paged list of NamedArea instances (optionally filtered by type or level)
  69      *
  70      * @param level restrict the result set to named areas of a certain level (can be null)
  71      * @param type restrict the result set to named areas of a certain type (can be null)
  72      * @param pageSize The maximum number of namedAreas returned (can be null for all named areas)
  73      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  74      * @return a Pager of named areas
  75      */
  76     public Pager<NamedArea> list(NamedAreaLevel level, NamedAreaType type, Integer pageSize, Integer pageNumber,  List<OrderHint> orderHints, List<String> propertyPaths);
  77
  78     /**
  79      * Return a paged list of terms which are specializations of a given definedTerm
  80      *
  81      * @param definedTerm The term which is a generalization of the terms returned
  82      * @param pageSize The maximum number of terms returned (can be null for all specializations)
  83      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  84      * @return a Pager of DefinedTerms
  85      */
  86     public <T extends DefinedTermBase> Pager<T> getGeneralizationOf(T definedTerm, Integer pageSize, Integer pageNumber);
  87
  88     /**
  89      * Return a paged list of distinct terms which include the terms supplied
  90      *
  91      * @param definedTerms the set of terms which are part of the terms of interest
  92      * @param pageSize The maximum number of terms returned (can be null for all terms)
  93      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  94      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  95      * @return a Pager of DefinedTerms
  96      */
  97     public <T extends DefinedTermBase> Pager<T> getPartOf(Set<T> definedTerms, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  98
  99     /**
 100      * Return a paged list of terms which are part of the terms supplied
 101      *
 102      * @param definedTerms the set of terms which include the terms of interest
 103      * @param pageSize The maximum number of terms returned (can be null for all terms)
 104      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 105      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 106      * @return a Pager of DefinedTerms
 107      */
 108     public <T extends DefinedTermBase> Pager<T> getIncludes(Collection<T> definedTerms, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 109
 110     /**
 111      * Return a paged list of terms which have representations that match the supplied string in the text (description)
 112      *
 113      * @param label a string to match (exactly)
 114      * @param pageSize The maximum number of terms returned (can be null for all terms)
 115      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 116      * @return a Pager of DefinedTerms
 117      */
 118     public <T extends DefinedTermBase> Pager<T> findByRepresentationText(String label, Class<T> clazz,  Integer pageSize, Integer pageNumber);
 119
 120     /**
 121      * Return a paged list of terms which have representations that match the supplied string in the abbreviated label
 122      *
 123      * @param label a string to match (exactly)
 124      * @param pageSize The maximum number of terms returned (can be null for all terms)
 125      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 126      * @return a Pager of DefinedTerms
 127      */
 128     public <T extends DefinedTermBase> Pager<T> findByRepresentationAbbreviation(String abbrev, Class<T> clazz, Integer pageSize, Integer pageNumber);
 129
 130     /**
 131      * Retrieves all {@link DefinedTermBase}s with the given {@link TermType}
 132      * @param termType the term type to filter the terms
 133      * @param limit
 134      * @param start
 135      * @param orderHints
 136      * @param propertyPaths
 137      * @return a list containing the terms
 138      */
 139     public List<DefinedTermBase<?>> listByTermType(TermType termType, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 140
 141     /**
 142      * Delete the given term according to the given delete configuration.
 143      * In case a problem occurrs while deleting the term the result will reflect this
 144      * via its status.
 145      * @param term the term to delete
 146      * @param config the configurator
 147      * @return DeleteResult which holds the status of the deletion.
 148      */
 149     public DeleteResult delete(DefinedTermBase term, TermDeletionConfigurator config);
 150
 151     /**
 152      * Returns the term with the given idInVocabulary for the given vocabulary.
 153      * If the same idInVocabulary exists with same vocabulary for multiple terms (though this is against the general
 154      * contract of idInVocabulary) always the same term should be returned.
 155      * @param id idInVocabulary
 156      * @param vocabularyUuid uuid of vocabulary
 157      * @param clazz term clazz filter on certain term classes. May be <code>null</code> for no filter.
 158      * @return the term
 159      * @throws IllegalArgumentException if id or vocabularyUuid is <code>null</code>
 160      */
 161     public <TERM extends DefinedTermBase> TERM findByIdInVocabulary(String id, UUID vocabularyUuid, Class<TERM> clazz)
 162         throws IllegalArgumentException;
 163 }