cdmlib-persistence/src/main/java/eu/etaxonomy/cdm/persistence/dao/description/IDescriptionDao.java

   1 /**
   2 * Copyright (C) 2007 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.persistence.dao.description;
  11
  12 import java.util.List;
  13 import java.util.Set;
  14
  15 import eu.etaxonomy.cdm.model.description.CommonTaxonName;
  16 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  17 import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
  18 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  19 import eu.etaxonomy.cdm.model.description.Feature;
  20 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase;
  21 import eu.etaxonomy.cdm.model.description.Scope;
  22 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  23 import eu.etaxonomy.cdm.model.location.NamedArea;
  24 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  25 import eu.etaxonomy.cdm.model.taxon.Taxon;
  26 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  27 import eu.etaxonomy.cdm.persistence.dao.common.IIdentifiableDao;
  28 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  29 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  30
  31 public interface IDescriptionDao extends IIdentifiableDao<DescriptionBase> {
  32         /**
  33          * List the descriptions of type <TYPE>, filtered using the following parameters
  34          *
  35          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
  36          * @param hasMedia Restrict the description to those that do (true) or don't (false) contain <i>elements</i> that have one or more media (can be null)
  37          * @param hasText Restrict the description to those that do (true) or don't (false) contain TextData <i>elements</i> that have some textual content (can be null)
  38          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
  39          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
  40          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  41          * @param orderHints may be null
  42          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
  43          * @return a List of DescriptionBase instances
  44          */
  45          List<DescriptionBase> listDescriptions(Class<? extends DescriptionBase> type, Boolean hasMedia, Boolean hasText, Set<Feature> feature, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
  46
  47         /**
  48          * Count the descriptions of type <TYPE>, filtered using the following parameters
  49          *
  50          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
  51          * @param hasMedia Restrict the description to those that do (true) or don't (false) contain <i>elements</i> that have one or more media (can be null)
  52          * @param hasText Restrict the description to those that do (true) or don't (false) contain TextData <i>elements</i> that have some textual content (can be null)
  53          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
  54          * @return a count of DescriptionBase instances
  55          */
  56          int countDescriptions(Class<? extends DescriptionBase> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);
  57
  58         /**
  59          * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
  60          *
  61          * @param description The description which these description elements belong to (can be null to count all description elements)
  62          * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
  63          * @param type The type of description
  64          * @param pageSize The maximum number of description elements returned (can be null for all description elements)
  65          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  66          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
  67          * @return a List of DescriptionElementBase instances
  68          */
  69          List<DescriptionElementBase> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  70
  71         /**
  72          * Returns a count of description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
  73          *
  74          * @param description The description which these description elements belong to (can be null to count all description elements)
  75          * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
  76          * @param type The type of description
  77          * @return a count of DescriptionElementBase instances
  78          */
  79          int countDescriptionElements(DescriptionBase description,      Set<Feature> features, Class<? extends DescriptionElementBase> type);
  80
  81         /**
  82          * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
  83          *
  84          * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
  85          * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
  86          * @param geographicalScope Restrict the results to those descriptions which have a geographical scope that overlaps with the NamedArea instances passed (can be null or empty)
  87          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
  88          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  89          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
  90          * @return a List of TaxonDescription instances
  91          */
  92         List<TaxonDescription> getTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  93
  94         /**
  95          * Returns a count of TaxonDescription instances, optionally filtered by parameters passed to this method
  96          *
  97          * @param taxon Restrict the results to those descriptions that refer to a specific taxon (can be null for all TaxonDescription instances)
  98          * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
  99          * @param geographicalScope Restrict the results to those descriptions which have a geographical scope that overlaps with the NamedArea instances passed (can be null or empty)
 100          * @return a count of TaxonDescription instances
 101          */
 102         int countTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope);
 103
 104         /**
 105          * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 106          *
 107          * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 108          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 109          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 110          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 111          * @return a List of TaxonNameBase instances
 112          */
 113     List<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 114
 115     /**
 116          * Returns a count of TaxonNameDescription instances, optionally filtered by the name which they refer to
 117          *
 118          * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 119          * @return a count of TaxonNameBase instances
 120          */
 121         int countTaxonNameDescriptions(TaxonNameBase name);
 122
 123         /**
 124          * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 125          * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 126          *
 127          * @param namedAreas The set of NamedArea instances
 128          * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 129          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 130          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 131          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 132          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 133          * @return a List of TaxonDescription instances
 134          */
 135         List<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 136
 137         /**
 138          * Returns a list of CommonTaxonName instances that match a search string
 139          * @param searchString
 140          * @param pageSize
 141          * @param pageNumber
 142          * @return
 143          */
 144         List<CommonTaxonName> searchDescriptionByCommonName(String queryString, MatchMode matchMode, Integer pageSize, Integer pageNumber);
 145
 146
 147         /**
 148          * @param queryString
 149          * @param matchMode
 150          * @return
 151          */
 152         Integer countDescriptionByCommonName(String queryString, MatchMode matchMode);
 153
 154         /**
 155          * Returns a count of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 156          * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 157          *
 158          * @param namedAreas The set of NamedArea instances
 159          * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 160          * @return a count of TaxonDescription instances
 161          */
 162         int countDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence);
 163 }