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