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

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10
  11 package eu.etaxonomy.cdm.api.service;
  12
  13 import java.net.URI;
  14 import java.util.Enumeration;
  15 import java.util.List;
  16 import java.util.Locale;
  17 import java.util.Set;
  18 import java.util.UUID;
  19
  20 import eu.etaxonomy.cdm.api.service.config.TermDeletionConfigurator;
  21 import eu.etaxonomy.cdm.api.service.pager.Pager;
  22 import eu.etaxonomy.cdm.model.common.DefinedTermBase;
  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.common.Representation;
  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.persistence.dao.BeanInitializer;
  32 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  33
  34 public interface ITermService extends IIdentifiableEntityService<DefinedTermBase> {
  35
  36         /**
  37          * Returns a term according to it's uri
  38          * @param uri
  39          * @return
  40          */
  41         public DefinedTermBase getByUri(URI uri);
  42
  43         public UUID saveLanguageData(LanguageStringBase languageData);
  44
  45         public List<LanguageString> getAllLanguageStrings(int limit, int start);
  46
  47         public List<Representation> getAllRepresentations(int limit, int start);
  48
  49         public Language getLanguageByIso(String iso639);
  50
  51         public List<Language> getLanguagesByLocale(Enumeration<Locale> locales);
  52
  53         public NamedArea getAreaByTdwgAbbreviation(String tdwgAbbreviation);
  54
  55          /**
  56      * Returns a paged list of Media that represent a given DefinedTerm instance
  57      *
  58          * @param definedTerm the definedTerm represented by these media
  59          * @param pageSize The maximum number of media returned (can be null for all related media)
  60          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  61      * @return a Pager of media instances
  62      */
  63         public Pager<Media> getMedia(DefinedTermBase definedTerm, Integer pageSize, Integer pageNumber);
  64
  65         /**
  66          * Returns a paged list of NamedArea instances (optionally filtered by type or level)
  67          *
  68          * @param level restrict the result set to named areas of a certain level (can be null)
  69          * @param type restrict the result set to named areas of a certain type (can be null)
  70          * @param pageSize The maximum number of namedAreas returned (can be null for all named areas)
  71          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  72          * @return a Pager of named areas
  73          */
  74         public Pager<NamedArea> list(NamedAreaLevel level, NamedAreaType type, Integer pageSize, Integer pageNumber,  List<OrderHint> orderHints, List<String> propertyPaths);
  75
  76         /**
  77          * Return a paged list of terms which are specializations of a given definedTerm
  78          *
  79          * @param definedTerm The term which is a generalization of the terms returned
  80          * @param pageSize The maximum number of terms returned (can be null for all specializations)
  81          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  82          * @return a Pager of DefinedTerms
  83          */
  84         public <T extends DefinedTermBase> Pager<T> getGeneralizationOf(T definedTerm, Integer pageSize, Integer pageNumber);
  85
  86         /**
  87          * Return a paged list of distinct terms which include the terms supplied
  88          *
  89          * @param definedTerms the set of terms which are part of the terms of interest
  90          * @param pageSize The maximum number of terms returned (can be null for all terms)
  91          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  92          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
  93          * @return a Pager of DefinedTerms
  94          */
  95         public <T extends DefinedTermBase> Pager<T> getPartOf(Set<T> definedTerms, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  96
  97         /**
  98          * Return a paged list of terms which are part of the terms supplied
  99          *
 100          * @param definedTerms the set of terms which include the terms of interest
 101          * @param pageSize The maximum number of terms returned (can be null for all terms)
 102          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 103          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 104          * @return a Pager of DefinedTerms
 105          */
 106         public <T extends DefinedTermBase> Pager<T> getIncludes(Set<T> definedTerms, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 107
 108         /**
 109          * Return a paged list of terms which have representations that match the supplied string in the text (description)
 110          *
 111          * @param label a string to match (exactly)
 112          * @param pageSize The maximum number of terms returned (can be null for all terms)
 113          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 114          * @return a Pager of DefinedTerms
 115          */
 116         public <T extends DefinedTermBase> Pager<T> findByRepresentationText(String label, Class<T> clazz,  Integer pageSize, Integer pageNumber);
 117
 118         /**
 119          * Return a paged list of terms which have representations that match the supplied string in the abbreviated label
 120          *
 121          * @param label a string to match (exactly)
 122          * @param pageSize The maximum number of terms returned (can be null for all terms)
 123          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 124          * @return a Pager of DefinedTerms
 125          */
 126         public <T extends DefinedTermBase> Pager<T> findByRepresentationAbbreviation(String abbrev, Class<T> clazz, Integer pageSize, Integer pageNumber);
 127
 128
 129         /**
 130          *
 131          * @param <TERM>
 132          * @param clazz
 133          * @param limit
 134          * @param start
 135          * @param orderHints
 136          * @param propertyPaths
 137          * @return
 138          */
 139         public <TERM extends DefinedTermBase> List<TERM> listByTermClass(Class<TERM> clazz, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 140
 141         /**
 142          * Delete the given term according to the given delete configuration.
 143          * In case a problem occurrs while deleting the term the result will reflect this
 144          * via its status.
 145          * @param term the term to delete
 146          * @param config the configurator
 147          * @return DeleteResult which holds the status of the deletion.
 148          */
 149         public DeleteResult delete(DefinedTermBase term, TermDeletionConfigurator config);
 150 }