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