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