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

   1 /**
   2 * Copyright (C) 2007 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9
  10 package eu.etaxonomy.cdm.api.service;
  11
  12 import java.net.URI;
  13 import java.util.Collection;
  14 import java.util.Enumeration;
  15 import java.util.List;
  16 import java.util.Locale;
  17 import java.util.Map;
  18 import java.util.Set;
  19 import java.util.UUID;
  20
  21 import eu.etaxonomy.cdm.api.service.TermServiceImpl.TermMovePosition;
  22 import eu.etaxonomy.cdm.api.service.config.TermDeletionConfigurator;
  23 import eu.etaxonomy.cdm.api.service.pager.Pager;
  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.location.NamedArea;
  28 import eu.etaxonomy.cdm.model.location.NamedAreaLevel;
  29 import eu.etaxonomy.cdm.model.location.NamedAreaType;
  30 import eu.etaxonomy.cdm.model.media.Media;
  31 import eu.etaxonomy.cdm.model.term.DefinedTermBase;
  32 import eu.etaxonomy.cdm.model.term.OrderedTermBase;
  33 import eu.etaxonomy.cdm.model.term.OrderedTermVocabulary;
  34 import eu.etaxonomy.cdm.model.term.Representation;
  35 import eu.etaxonomy.cdm.model.term.TermType;
  36 import eu.etaxonomy.cdm.model.term.TermVocabulary;
  37 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  38 import eu.etaxonomy.cdm.persistence.dto.TermDto;
  39 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  40 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  41
  42 public interface ITermService extends IIdentifiableEntityService<DefinedTermBase> {
  43
  44     /**
  45      * Returns a term according to it's uri
  46      * @param uri
  47      * @return
  48      */
  49     public DefinedTermBase getByUri(URI uri);
  50
  51     public UUID saveLanguageData(LanguageStringBase languageData);
  52
  53     public List<LanguageString> getAllLanguageStrings(int limit, int start);
  54
  55     public List<Representation> getAllRepresentations(int limit, int start);
  56
  57     public Language getLanguageByIso(String iso639);
  58
  59     public List<Language> getLanguagesByLocale(Enumeration<Locale> locales);
  60
  61     public NamedArea getAreaByTdwgAbbreviation(String tdwgAbbreviation);
  62
  63      /**
  64      * Returns a paged list of Media that represent a given DefinedTerm instance
  65      *
  66      * @param definedTerm the definedTerm represented by these media
  67      * @param pageSize The maximum number of media returned (can be null for all related media)
  68      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  69      * @return a Pager of media instances
  70      */
  71     public Pager<Media> getMedia(DefinedTermBase definedTerm, Integer pageSize, Integer pageNumber);
  72
  73     /**
  74      * Returns a paged list of NamedArea instances (optionally filtered by type or level)
  75      *
  76      * @param level restrict the result set to named areas of a certain level (can be null)
  77      * @param type restrict the result set to named areas of a certain type (can be null)
  78      * @param pageSize The maximum number of namedAreas returned (can be null for all named areas)
  79      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  80      * @return a Pager of named areas
  81      */
  82     public Pager<NamedArea> list(NamedAreaLevel level, NamedAreaType type, Integer pageSize, Integer pageNumber,  List<OrderHint> orderHints, List<String> propertyPaths);
  83
  84     /**
  85      * Return a paged list of terms which are specializations of a given definedTerm
  86      *
  87      * @param definedTerm The term which is a generalization of the terms returned
  88      * @param pageSize The maximum number of terms returned (can be null for all specializations)
  89      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  90      * @return a Pager of DefinedTerms
  91      */
  92     public <T extends DefinedTermBase> Pager<T> getGeneralizationOf(T definedTerm, Integer pageSize, Integer pageNumber);
  93
  94     /**
  95      * Return a paged list of distinct terms which include the terms supplied
  96      *
  97      * @param definedTerms the set of terms which are part of the terms of interest
  98      * @param pageSize The maximum number of terms returned (can be null for all terms)
  99      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 100      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 101      * @return a Pager of DefinedTerms
 102      */
 103     public <T extends DefinedTermBase> Pager<T> getPartOf(Set<T> definedTerms, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 104
 105     /**
 106      * Return a paged list of terms which are part of the terms supplied
 107      *
 108      * @param definedTerms the set of terms which include the terms of interest
 109      * @param pageSize The maximum number of terms returned (can be null for all terms)
 110      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 111      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 112      * @return a Pager of DefinedTerms
 113      */
 114     public <T extends DefinedTermBase> Pager<T> getIncludes(Collection<T> definedTerms, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 115
 116     /**
 117      * Return a paged list of terms which have representations that match the supplied string in the text (description)
 118      *
 119      * @param label a string to match (exactly)
 120      * @param pageSize The maximum number of terms returned (can be null for all terms)
 121      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 122      * @return a Pager of DefinedTerms
 123      */
 124     public <T extends DefinedTermBase> Pager<T> findByRepresentationText(String label, Class<T> clazz,  Integer pageSize, Integer pageNumber);
 125
 126     /**
 127      * Return a paged list of terms which have representations that match the supplied string in the abbreviated label
 128      *
 129      * @param label a string to match (exactly)
 130      * @param pageSize The maximum number of terms returned (can be null for all terms)
 131      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 132      * @return a Pager of DefinedTerms
 133      */
 134     public <T extends DefinedTermBase> Pager<T> findByRepresentationAbbreviation(String abbrev, Class<T> clazz, Integer pageSize, Integer pageNumber);
 135
 136     /**
 137      * Retrieves all {@link DefinedTermBase}s with the given {@link TermType}
 138      * @param termType the term type to filter the terms
 139      * @param limit
 140      * @param start
 141      * @param orderHints
 142      * @param propertyPaths
 143      * @return a list containing the terms
 144      */
 145     public <T extends DefinedTermBase> List<T> listByTermType(TermType termType, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 146
 147     /**
 148      * Delete the given term according to the given delete configuration.
 149      * In case a problem occurrs while deleting the term the result will reflect this
 150      * via its status.
 151      * @param term the term to delete
 152      * @param config the configurator
 153      * @return DeleteResult which holds the status of the deletion.
 154      */
 155     public DeleteResult delete(DefinedTermBase term, TermDeletionConfigurator config);
 156
 157     /**
 158      * Returns the term with the given idInVocabulary for the given vocabulary.
 159      * If the same idInVocabulary exists with same vocabulary for multiple terms (though this is against the general
 160      * contract of idInVocabulary) always the same term should be returned.
 161      * @param id idInVocabulary
 162      * @param vocabularyUuid uuid of vocabulary
 163      * @param clazz term clazz filter on certain term classes. May be <code>null</code> for no filter.
 164      * @return the term
 165      * @throws IllegalArgumentException if id or vocabularyUuid is <code>null</code>
 166      */
 167     public <TERM extends DefinedTermBase> TERM findByIdInVocabulary(String id, UUID vocabularyUuid, Class<TERM> clazz)
 168         throws IllegalArgumentException;
 169
 170     /**
 171      * @param termUuid
 172      * @param config
 173      * @return
 174      */
 175     public DeleteResult delete(UUID termUuid, TermDeletionConfigurator config);
 176
 177     /**
 178      * @param label
 179      * @return
 180      */
 181     public Language getLanguageByLabel(String label);
 182
 183     /**
 184      * @param representations
 185      * @return
 186      */
 187     public Map<UUID, Representation> saveOrUpdateRepresentations(Collection<Representation> representations);
 188
 189
 190     /**
 191      * @param vocs
 192      * @param limit
 193      * @param pattern
 194      * @param lang
 195      * @return
 196      */
 197     List<UuidAndTitleCache<NamedArea>> getUuidAndTitleCacheNamedArea(List<TermVocabulary> vocs, Integer limit, String pattern,
 198             Language lang);
 199
 200     /**
 201      * Returns all terms that are included in the given parent term resp. a part of the given term.
 202      * @param parentTerm the parent term
 203      * @return a collection of included terms
 204      */
 205     public Collection<TermDto> getIncludesAsDto(TermDto parentTerm);
 206
 207     /**
 208      * Returns all terms that the given term is a generalization of resp. that are a kind of the given term
 209      * @param parentTerm the parent term
 210      * @return a collection of included terms
 211      */
 212     public Collection<TermDto> getKindOfsAsDto(TermDto parentTerm);
 213
 214     /**
 215      * Move the given term to the given parent
 216      * @param termDto the {@link TermDto} of the term to move
 217      * @param parentUuid the {@link UUID} of the new parent term
 218      * @param termMovePosition enum to specify the position for {@link OrderedTermBase}s in an {@link OrderedTermVocabulary}
 219      */
 220     public void moveTerm(TermDto termDto, UUID parentUuid, TermMovePosition termMovePosition);
 221
 222     /**
 223      * Move the given term to the given parent
 224      * @param termDto the {@link TermDto} of the term to move
 225      * @param parentUuid the {@link UUID} of the new parent term
 226      */
 227     public void moveTerm(TermDto termDto, UUID parentUuid);
 228
 229     /**
 230      * Creates a new term as a child of the given parent.
 231      * @param termType the {@link TermType} of the term to create
 232      * @param parentUuid the {@link UUID} of the parent term
 233      * @param isKindOf if <code>true</code> the term will be added via a
 234      * kindOf relation. Otherwise it will added via a partOf relation
 235      * @return the new term
 236      */
 237     public TermDto addNewTerm(TermType termType, UUID parentUuid, boolean isKindOf);
 238
 239
 240     /**
 241      * Returns a collection of {@link TermDto}s that match the given search parameters.
 242      * @param title  the term label that the terms have to match
 243      * @param termType the termType that the terms have to match
 244      * @return a collection of matching term DTOs
 245      */
 246     public Collection<TermDto> findByTitleAsDto(String title, TermType termType);
 247
 248     /**
 249      * Returns a collection of {@link TermDto}s that match the given search parameters.
 250      * @param uri the {@link URI} that the terms have to match
 251      * @param termLabel  the term label that the terms have to match
 252      * @param termType the termType that the terms have to match
 253      * @return a collection of matching term DTOs
 254      */
 255     public Collection<TermDto> findByUriAsDto(URI uri, String termLabel, TermType termType);
 256
 257
 258 }