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

   1 /**
   2 * Copyright (C) 2009 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.List;
  13 import java.util.Set;
  14 import java.util.UUID;
  15
  16 import eu.etaxonomy.cdm.api.service.pager.Pager;
  17 import eu.etaxonomy.cdm.filter.VocabularyFilter;
  18 import eu.etaxonomy.cdm.model.common.CdmClass;
  19 import eu.etaxonomy.cdm.model.common.Language;
  20 import eu.etaxonomy.cdm.model.term.DefinedTermBase;
  21 import eu.etaxonomy.cdm.model.term.TermType;
  22 import eu.etaxonomy.cdm.model.term.TermVocabulary;
  23 import eu.etaxonomy.cdm.persistence.dto.TermCollectionDto;
  24 import eu.etaxonomy.cdm.persistence.dto.TermDto;
  25 import eu.etaxonomy.cdm.persistence.dto.TermVocabularyDto;
  26 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  27 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  28
  29 public interface IVocabularyService extends IIdentifiableEntityService<TermVocabulary> {
  30
  31     /**
  32      * Returns term vocabularies that contain terms of a certain {@link TermType} e.g. Feature, Modifier, State.
  33      *
  34      * @param <TERMTYPE>
  35      * @param termType the {@link TermType} of the terms in the vocabulary and of the vocabulary
  36      * @param includeSubTypes if <code>true</code> all subtypes will be included for computation of the result
  37      * @param limit The maximum number of vocabularies returned (can be null for all vocabularies)
  38      * @param start The offset from the start of the result set (0 - based, can be null - equivalent of starting at the beginning of the recordset)
  39      * @param orderHints
  40      *            Supports path like <code>orderHints.propertyNames</code> which
  41      *            include *-to-one properties like createdBy.username or
  42      *            authorTeam.persistentTitleCache
  43      * @param propertyPaths properties to be initialized
  44      * @return a list of term vocabularies
  45      */
  46     public List<TermVocabulary> listByTermType(TermType termType, boolean includeSubTypes, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  47
  48     public List<TermVocabulary> listByTermType(Set<TermType> termType, boolean includeSubTypes, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  49
  50         /**
  51          * Returns Language Vocabulary
  52          * @return
  53          */
  54         //TODO candidate for harmonization: rename to loadLanguageVocabulary(...
  55         public TermVocabulary<Language> getLanguageVocabulary();
  56
  57         /**
  58          * Returns a list of terms belonging to the vocabulary passed as an argument
  59          *
  60          * @param vocabulary The vocabulary for which the list of terms is desired
  61          * @param limit The maximum number of terms returned (can be null for all terms in the vocabulary)
  62          * @param start The offset from the start of the result set (0 - based, can be null - equivalent of starting at the beginning of the recordset)
  63          * @param orderHints
  64          *            Supports path like <code>orderHints.propertyNames</code> which
  65          *            include *-to-one properties like createdBy.username or
  66          *            authorTeam.persistentTitleCache
  67          * @param propertyPaths properties to be initialized
  68          * @return a paged list of terms
  69          */
  70         //TODO candidate for harmonization: rename to getTerms(...
  71         public Pager<DefinedTermBase> getTerms(TermVocabulary vocabulary, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  72
  73         /**
  74          * Returns a list of term vocabularies corresponding to a term type
  75          *
  76          * @param termType The term type for which the list of vocabularies is desired
  77          * @return a list of vocabularies
  78          */
  79         //FIXME shouldn't this be list(...), can be deduplicated
  80         public <T extends DefinedTermBase> List<TermVocabulary<T>> findByTermType(TermType termType, List<String> propertyPaths);
  81
  82         //FIXME shouldn't this be list(...), can be deduplicated
  83         public <T extends DefinedTermBase> List<TermVocabulary<T>> findByTermType(Set<TermType> termTypes, List<String> propertyPaths);
  84
  85         /**
  86          * Loads all top level terms, i.e. terms that have no parent terms, for the given vocabulary
  87          * @param vocabularyUuid the uuid of the vocabulary
  88          * @return a collection of top level terms
  89          */
  90         public Collection<TermDto> getTopLevelTerms(UUID vocabularyUuid);
  91
  92         /**
  93      * Loads all terms for the given vocabulary
  94      * @param vocabularyUuid the id of the vocabulary
  95      * @return a collection of terms
  96      */
  97     public Collection<TermDto> getTerms(UUID vocabularyUuid);
  98
  99     /**
 100      * Loads all terms for the given vocabularies
 101      * @param vocabularyUuids the ids of the vocabularies
 102      * @return a collection of terms
 103      */
 104     public Collection<TermDto> getTerms(List<UUID> vocabularyUuids);
 105
 106     /**
 107      * Loads all namedArea term dtos with level informations for the given vocabularies
 108      * @param vocabularyUuids the ids of the vocabularies
 109      * @return a collection of named areaterm dtos
 110      */
 111     public Collection<TermDto> getNamedAreaTerms(List<UUID> vocabularyUuids);
 112         /**
 113          * Initializes the complete term hierarchy consisting of {@link TermDto}s
 114          * for the given vocabulary
 115          * @param collectionDto the dto of the term collection
 116          * @return a the top level elements for this collection
 117          */
 118         public Collection<TermDto> getCompleteTermHierarchy(TermCollectionDto vocabularyDto);
 119
 120         /**
 121      * Returns term vocabularies that contain terms of a certain {@link TermType} e.g. Feature, Modifier, State.
 122      *
 123      * @param termType the {@link TermType} of the terms in the vocabulary and of the vocabulary
 124      * @return a list of term vocabulary DTOs
 125      */
 126     public List<TermVocabularyDto> findVocabularyDtoByTermType(TermType termType);
 127
 128     /**
 129      * Returns term vocabularies that contain terms of the given types {@link TermType} e.g. Feature, Modifier, State.
 130      *
 131      * @param termTypes a set of {@link TermType}s of the terms in the vocabulary and of the vocabulary
 132      * @return a list of term vocabulary DTOs
 133      */
 134     public List<TermVocabularyDto> findVocabularyDtoByTermTypes(Set<TermType> termTypes);
 135
 136     /**
 137      * Returns term vocabularies that contain terms of a certain {@link TermType} e.g. Feature, Modifier, State.
 138      *
 139      * @param termType the {@link TermType} of the terms in the vocabulary and of the vocabulary
 140      * @param includeSubtypes if <code>true</code> also vocabularies with subtypes of the given type
 141      * will be returned
 142      * @return a list of term vocabulary DTOs
 143      */
 144     public List<TermVocabularyDto> findVocabularyDtoByTermType(TermType termType, boolean includeSubtypes);
 145
 146     /**
 147      * Returns term vocabularies that contain terms of the given types {@link TermType} e.g. Feature, Modifier, State.
 148      *
 149      * @param termTypes a set of {@link TermType}s of the terms in the vocabulary and of the vocabulary
 150      * @param includeSubtypes if <code>true</code> also vocabularies with subtypes of the given type
 151      * will be returned
 152      * @return a list of term vocabulary DTOs
 153      */
 154     public List<TermVocabularyDto> findVocabularyDtoByTermTypes(Set<TermType> termTypes, boolean includeSubtypes);
 155
 156     /**
 157      * Creates a new term as a direct child of the given vocabulary.
 158      * @param termType the {@link TermType} of the term to create
 159      * @param vocabularyUUID the {@link UUID} of the vocabulary
 160      * kindOf relation. Otherwise it will added via a partOf relation
 161      * @return the new term
 162      */
 163     public TermDto addNewTerm(TermType termType, UUID vocabularyUUID, Language lang);
 164
 165     /**
 166      *
 167      * Like {@link #getUuidAndTitleCache(Class, Integer, String)} but filtering
 168      * the results by {@link TermType} of the vocabularies.
 169      *
 170      *
 171      * @param clazz
 172      *            the (sub)class
 173      * @param termType
 174      *            the {@link TermType} of the vocabularies to be retrieved
 175      * @param limit
 176      *            max number of results
 177      * @param pattern
 178      *            search pattern
 179      * @return a list of {@link UuidAndTitleCache}
 180      *
 181      * @see #getUuidAndTitleCache(Class, Integer, String))
 182      */
 183     public <S extends TermVocabulary> List<UuidAndTitleCache<S>> getUuidAndTitleCache(Class<S> clazz, TermType termType,
 184             Integer limit, String pattern);
 185
 186     /**
 187      * @param vocUuid
 188      * @return
 189      */
 190     public TermCollectionDto findVocabularyDtoByVocabularyUuid(UUID vocUuid);
 191
 192     /**
 193      * @param vocUuid
 194      * @return
 195      */
 196     public List<TermVocabularyDto> findVocabularyDtoByVocabularyUuids(List<UUID> vocUuid);
 197
 198     public List<TermVocabularyDto> findVocabularyDtoByTermTypeAndPattern(String pattern, TermType termType);
 199
 200     /**
 201      * @param termTypes
 202      * @param includeSubtypes
 203      * @return
 204      */
 205     public List<TermVocabularyDto> findFeatureVocabularyDtoByTermTypes(Set<CdmClass> availableFor);
 206
 207     /**
 208      * Returns a list of vocabulary {@link UUID uuids} according to the given filter.
 209      */
 210     public List<UUID> uuidList(VocabularyFilter filter);
 211
 212     /**
 213      * Returns a list of vocabulary IDs according to the given filter.
 214      */
 215     public List<Integer> idList(VocabularyFilter filter);
 216
 217     /**
 218      * Returns the total count of vocabularies according to the given filter.
 219      */
 220     public long count(VocabularyFilter filter);
 221 }