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 import java.util.UUID;
  15
  16 import eu.etaxonomy.cdm.model.common.DefinedTerm;
  17 import eu.etaxonomy.cdm.model.common.MarkerType;
  18 import eu.etaxonomy.cdm.model.description.CommonTaxonName;
  19 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  20 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  21 import eu.etaxonomy.cdm.model.description.Distribution;
  22 import eu.etaxonomy.cdm.model.description.Feature;
  23 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase;
  24 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  25 import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
  26 import eu.etaxonomy.cdm.model.location.NamedArea;
  27 import eu.etaxonomy.cdm.model.media.Media;
  28 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  29 import eu.etaxonomy.cdm.model.taxon.Taxon;
  30 import eu.etaxonomy.cdm.persistence.dao.common.IIdentifiableDao;
  31 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  32 import eu.etaxonomy.cdm.persistence.dao.media.IMediaDao;
  33 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  34 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  35
  36 public interface IDescriptionDao extends IIdentifiableDao<DescriptionBase> {
  37     /**
  38      * List the descriptions of type <TYPE>, filtered using the following parameters
  39      *
  40      * @param type The type of description returned (Taxon, TaxonName, or Specimen)
  41      * @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)
  42      * @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)
  43      * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
  44      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
  45      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  46      * @param orderHints may be null
  47      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  48      * @return a List of DescriptionBase instances
  49      */
  50      List<DescriptionBase> listDescriptions(Class<? extends DescriptionBase> type, Boolean hasMedia, Boolean hasText, Set<Feature> feature, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
  51
  52     /**
  53      * Count the descriptions of type <TYPE>, filtered using the following parameters
  54      *
  55      * @param type The type of description returned (Taxon, TaxonName, or Specimen)
  56      * @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)
  57      * @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)
  58      * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
  59      * @return a count of DescriptionBase instances
  60      */
  61      int countDescriptions(Class<? extends DescriptionBase> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);
  62
  63     /**
  64      * Returns a count of TaxonDescription instances, optionally filtered by parameters passed to this method
  65      *
  66      * @param taxon Restrict the results to those descriptions that refer to a specific taxon (can be null for all TaxonDescription instances)
  67      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
  68      * @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)
  69      * @param markerType Restrict the results to those descriptions which are marked as true by one of the given marker types (can be null or empty)
  70      * @return a count of TaxonDescription instances
  71      */
  72     int countTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerType);
  73
  74     /**
  75      * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
  76      *
  77      * @param description The description which these description elements belong to (can be null to count all description elements)
  78      * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
  79      * @param type The type of description
  80      * @param pageSize The maximum number of description elements returned (can be null for all description elements)
  81      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  82      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
  83      * @return a List of DescriptionElementBase instances
  84      * @deprecated use {@link #getDescriptionElements(DescriptionBase, Class, Set, Class, Integer, Integer, List)} instead
  85      */
  86      @Deprecated
  87     List<DescriptionElementBase> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  88
  89     /**
  90      * Returns description elements of type <TYPE>, belonging to a given
  91      * description, optionally filtered by one or more features
  92      *
  93      * @param description
  94      *            The description which these description elements belong to
  95      *            (can be null to count all description elements)
  96      * @param descriptionType
  97      *            A filter DescriptionElements which belong to of a specific class
  98      *            of Descriptions
  99      * @param features
 100      *            Restrict the results to those description elements which are
 101      *            scoped by one of the Features passed (can be null or empty)
 102      * @param type
 103      *            A filter for DescriptionElements of a specific class
 104      * @param pageSize
 105      *            The maximum number of description elements returned (can be
 106      *            null for all description elements)
 107      * @param pageNumber
 108      *            The offset (in pageSize chunks) from the start of the result
 109      *            set (0 - based)
 110      * @param propertyPaths
 111      *            Properties to initialize in the returned entities, following
 112      *            the syntax described in
 113      *            {@link IBeanInitializer#initialize(Object, List)}
 114      * @return a List of DescriptionElementBase instances
 115      */
 116     List<DescriptionElementBase> getDescriptionElements(DescriptionBase description, Class<? extends DescriptionBase> descriptionType, Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 117
 118
 119     /**
 120      * Returns a count of description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
 121      *
 122      * @param description The description which these description elements belong to (can be null to count all description elements)
 123      * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
 124      * @param type A filter for DescriptionElements of a specific class
 125      * @return a count of DescriptionElementBase instances
 126      * @deprecated use {@link #countDescriptionElements(DescriptionBase, Class, Set, Class)} instead
 127      */
 128     @Deprecated
 129      int countDescriptionElements(DescriptionBase description, Set<Feature> features, Class<? extends DescriptionElementBase> type);
 130
 131     /**
 132      * Returns a count of description elements of type <TYPE>, belonging to a
 133      * given description, optionally filtered by one or more features
 134      *
 135      * @param description
 136      *            The description which these description elements belong to
 137      *            (can be null to count all description elements)
 138      * @param descriptionType
 139      *            A filter DescriptionElements which belong to of a specific
 140      *            class of Descriptions
 141      * @param features
 142      *            Restrict the results to those description elements which are
 143      *            scoped by one of the Features passed (can be null or empty)
 144      * @param type
 145      *            The type of description
 146      * @return a count of DescriptionElementBase instances
 147      */
 148     int countDescriptionElements(DescriptionBase description, Class<? extends DescriptionBase> descriptionType, Set<Feature> features, Class<? extends DescriptionElementBase> type);
 149
 150     /**
 151      * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 152      *
 153      * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 154      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 155      * @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)
 156      * @param markerTypes Restrict the results to those descriptions which are marked as true by one of the given marker types (can be null or empty)
 157      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 158      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 159      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 160      * @return a List of TaxonDescription instances
 161      */
 162     List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 163
 164     /**
 165      * Returns a List of Media instances, optionally filtered by parameters passed to this method.
 166      * Maybe in future a similar method is implemented in {@link IMediaDao} which allows more
 167      * media sources to be included.
 168      *
 169      * @param taxonUuid The taxon uuid of the taxon which the description refers to (can be null for all TaxonDescription instances)
 170      * @param restrictToGalleries if true, only returns media from TaxonDescriptions with isImageGallery = true
 171      * @param markerTypes Restrict the results to those descriptions which are marked as true by one of the given marker types (can be null or empty)
 172      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 173      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 174      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 175      * @return a List of Media instances
 176      */
 177     List<Media> listTaxonDescriptionMedia(UUID taxonUuid, Boolean restrictToGalleries, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 178
 179     /**
 180      * Returns a count of Media instances, optionally filtered by parameters passed to this method
 181      * Maybe in future a similar method is implemented in {@link IMediaDao} which allows more
 182      * media sources to be included.
 183      *
 184      * @param taxonUuid The taxon uuid of the taxon which the description refers to (can be null for all TaxonDescription instances)
 185      * @param restrictToGalleries if true, only returns media from TaxonDescriptions with isImageGallery = true
 186      * @param markerTypes Restrict the results to those descriptions which are marked as true by one of the given marker types (can be null or empty)
 187      * @return a count of Media instances
 188      */
 189     int countTaxonDescriptionMedia(UUID taxonUuid, Boolean restrictToGalleries, Set<MarkerType> markerTypes);
 190
 191
 192     /**
 193      * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 194      *
 195      * @param name Restrict the results to those descripDescriptionElementBasetions that refer to a specific name (can be null for all TaxonNameDescription instances)
 196      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 197      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 198      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 199      * @return a List of TaxonNameBase instances
 200      */
 201     List<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 202
 203     /**
 204      * Returns a count of TaxonNameDescription instances, optionally filtered by the name which they refer to
 205      *
 206      * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 207      * @return a count of TaxonNameBase instances
 208      */
 209     int countTaxonNameDescriptions(TaxonNameBase name);
 210
 211     /**
 212      * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 213      * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 214      *
 215      * @param namedAreas The set of NamedArea instances
 216      * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 217      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 218      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 219      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 220      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 221      * @return a List of TaxonDescription instances
 222      */
 223     List<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 224
 225     /**
 226      * Returns a list of CommonTaxonName instances that match a search string
 227      * @param searchString
 228      * @param pageSize
 229      * @param pageNumber
 230      * @return
 231      */
 232     List<CommonTaxonName> searchDescriptionByCommonName(String queryString, MatchMode matchMode, Integer pageSize, Integer pageNumber);
 233
 234
 235     /**
 236      * @param queryString
 237      * @param matchMode
 238      * @return
 239      */
 240     Integer countDescriptionByCommonName(String queryString, MatchMode matchMode);
 241
 242     /**
 243      * Returns a count of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 244      * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 245      *
 246      * @param namedAreas The set of NamedArea instances
 247      * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 248      * @return a count of TaxonDescription instances
 249      */
 250     int countDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence);
 251
 252     /**
 253      * @param taxon
 254      * @param features
 255      *            Restrict the results to those description elements which are
 256      *            scoped by one of the Features passed (can be null or empty)
 257      * @param type A filter for DescriptionElements of a specific class
 258      * @param pageSize
 259      * @param pageNumber
 260      * @param propertyPaths
 261      * @return the list of matching DescriptionElementBase instances
 262      */
 263     <T extends DescriptionElementBase> List<T> getDescriptionElementForTaxon(Taxon taxon,
 264             Set<Feature> features,
 265             Class<T> type, Integer pageSize,
 266             Integer pageNumber, List<String> propertyPaths);
 267
 268     /**
 269      * @param taxon
 270      * @param features
 271      *            Restrict the results to those description elements which are
 272      *            scoped by one of the Features passed (can be null or empty)
 273      * @param type A filter for DescriptionElements of a specific class
 274      * @return the count of matching TaxonDescription instances
 275      */
 276     <T extends DescriptionElementBase> long countDescriptionElementForTaxon(Taxon taxon,
 277             Set<Feature> features, Class<T> type);
 278
 279     /**
 280      * Method to list all {@link NamedAreas} instances which are currently used
 281      * by {@link Distribution} elements.
 282      *
 283      * @param pageSize
 284      * @param pageNumber
 285      * @param propertyPaths
 286      * @return
 287      */
 288     List<NamedArea> listNamedAreasInUse(Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 289 }