cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IDescriptionService.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.util.Collection;
  14 import java.util.List;
  15 import java.util.Map;
  16 import java.util.Set;
  17 import java.util.UUID;
  18
  19 import eu.etaxonomy.cdm.api.service.pager.Pager;
  20 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  21 import eu.etaxonomy.cdm.model.common.VersionableEntity;
  22 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  23 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  24 import eu.etaxonomy.cdm.model.description.Feature;
  25 import eu.etaxonomy.cdm.model.description.FeatureNode;
  26 import eu.etaxonomy.cdm.model.description.FeatureTree;
  27 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase;
  28 import eu.etaxonomy.cdm.model.description.Scope;
  29 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  30 import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
  31 import eu.etaxonomy.cdm.model.description.TextData;
  32 import eu.etaxonomy.cdm.model.location.NamedArea;
  33 import eu.etaxonomy.cdm.model.media.Media;
  34 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  35 import eu.etaxonomy.cdm.model.taxon.Taxon;
  36
  37 public interface IDescriptionService extends IIdentifiableEntityService<DescriptionBase> {
  38
  39         /**
  40          * @param uuid
  41          * @return
  42          */
  43         // FIXME candidate for harmonization? findByUuid
  44         public DescriptionBase getDescriptionBaseByUuid(UUID uuid);
  45
  46         /**
  47          * Persists a <code>Description</code>
  48           * @param description
  49          * @return
  50          */
  51         // FIXME candidate for harmonization? save
  52         public UUID saveDescription(DescriptionBase description);
  53
  54         /**
  55          * Persists a <code>FeatureTree</code>
  56          * @param tree
  57          * @return
  58          */
  59         public UUID saveFeatureTree(FeatureTree tree);
  60         // FIXME could you handle the feature data elements using @Cascade?
  61         public void saveFeatureDataAll(Collection<VersionableEntity> featureData);
  62         public Map<UUID, FeatureTree> saveFeatureTreeAll(Collection<FeatureTree> trees);
  63         public Map<UUID, FeatureNode> saveFeatureNodeAll(Collection<FeatureNode> nodes);
  64
  65         /**
  66          * Gets a FeatureTree instance matching the supplied uuid
  67          *
  68          * @param uuid the uuid of the FeatureTree of interest
  69          * @return a FeatureTree, or null if the FeatureTree does not exist
  70          */
  71         public FeatureTree getFeatureTreeByUuid(UUID uuid);
  72
  73         public List<FeatureTree> getFeatureTreesAll();
  74         public List<FeatureNode> getFeatureNodesAll();
  75         public List<Feature> getFeaturesAll();
  76
  77         public List<FeatureTree> getFeatureTreesAll(List<String> propertyPaths);
  78         public List<FeatureNode> getFeatureNodesAll(List<String> propertyPaths);
  79         public List<Feature> getFeaturesAll(List<String> propertyPaths);
  80
  81
  82         public TermVocabulary<Feature> getDefaultFeatureVocabulary();
  83         //public TermVocabulary<Feature> getFeatureVocabulary();
  84         public TermVocabulary<Feature> getFeatureVocabulary(UUID uuid);
  85
  86         /**
  87          * Gets a DescriptionElementBase instance matching the supplied uuid
  88          *
  89          * @param uuid the uuid of the DescriptionElement of interest
  90          * @return a DescriptionElement, or null if the DescriptionElement does not exist
  91          */
  92         public DescriptionElementBase getDescriptionElementByUuid(UUID uuid);
  93
  94         /**
  95          * List the descriptions of type <TYPE>, filtered using the following parameters
  96          *
  97          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
  98          * @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)
  99          * @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)
 100          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 101          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 102          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 103          * @return a Pager containing DescriptionBase instances
 104          */
 105         public <TYPE extends DescriptionBase> Pager<TYPE> listDescriptions(Class<TYPE> type, Boolean hasMedia, Boolean hasText, Set<Feature> feature, Integer pageSize, Integer pageNumber);
 106
 107         /**
 108          * Count the descriptions of type <TYPE>, filtered using the following parameters
 109          *
 110          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 111          * @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)
 112          * @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)
 113          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 114          * @return a count of DescriptionBase instances
 115          */
 116         public <TYPE extends DescriptionBase> int countDescriptions(Class<TYPE> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);
 117
 118         /**
 119          * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
 120          *
 121          * @param description The description which these description elements belong to (can be null to count all description elements)
 122          * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
 123          * @param type The type of description
 124          * @param pageSize The maximum number of description elements returned (can be null for all description elements)
 125          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 126          * @return a Pager containing DescriptionElementBase instances
 127          */
 128         public <TYPE extends DescriptionElementBase> Pager<TYPE> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<TYPE> type, Integer pageSize, Integer pageNumber);
 129
 130         /**
 131          * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 132          *
 133          * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 134          * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 135          * @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)
 136          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 137          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 138          * @return a Pager containing TaxonDescription instances
 139          */
 140         public Pager<TaxonDescription> getTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber);
 141
 142         /**
 143          * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 144          *
 145          * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 146          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 147          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 148          * @return a Pager containing TaxonNameBase instances
 149          */
 150         public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber);
 151
 152         /**
 153          * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 154          * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 155          *
 156          * @param namedAreas The set of NamedArea instances
 157          * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 158          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 159          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 160          * @return a Pager containing TaxonDescription instances
 161          */
 162         public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber);
 163
 164         /**
 165      * Returns a List of TextData elements that match a given queryString provided.
 166          *
 167          * @param queryString
 168          * @param pageSize
 169          * @param pageNumber
 170          * @return
 171          * @throws QueryParseException
 172          */
 173         public Pager<TextData> searchTextData(String queryString, Integer pageSize, Integer pageNumber);
 174
 175         /**
 176      * Returns a List of Media that are associated with a given description element
 177      *
 178          * @param descriptionElement the description element associated with these media
 179          * @param pageSize The maximum number of media returned (can be null for all related media)
 180          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 181      * @return a Pager containing media instances
 182      */
 183     public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber);
 184
 185 }