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