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