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.Annotation;
  21 import eu.etaxonomy.cdm.model.common.MarkerType;
  22 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  23 import eu.etaxonomy.cdm.model.common.VersionableEntity;
  24 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  25 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  26 import eu.etaxonomy.cdm.model.description.Distribution;
  27 import eu.etaxonomy.cdm.model.description.Feature;
  28 import eu.etaxonomy.cdm.model.description.FeatureNode;
  29 import eu.etaxonomy.cdm.model.description.FeatureTree;
  30 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase;
  31 import eu.etaxonomy.cdm.model.description.Scope;
  32 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  33 import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
  34 import eu.etaxonomy.cdm.model.location.NamedArea;
  35 import eu.etaxonomy.cdm.model.location.NamedAreaLevel;
  36 import eu.etaxonomy.cdm.model.media.Media;
  37 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  38 import eu.etaxonomy.cdm.model.taxon.Taxon;
  39 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  40 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  41
  42 public interface IDescriptionService extends IIdentifiableEntityService<DescriptionBase> {
  43
  44         /**
  45          *
  46          * @return
  47          * @deprecated use TermService#getVocabulary(VocabularyType) instead
  48          */
  49         public TermVocabulary<Feature> getDefaultFeatureVocabulary();
  50
  51         /**
  52          * @deprecated use TermService#getVocabulary(VocabularyType) instead
  53          */
  54         public TermVocabulary<Feature> getFeatureVocabulary(UUID uuid);
  55
  56         /**
  57          * Gets a DescriptionElementBase instance matching the supplied uuid
  58          *
  59          * @param uuid the uuid of the DescriptionElement of interest
  60          * @return a DescriptionElement, or null if the DescriptionElement does not exist
  61          */
  62         public DescriptionElementBase getDescriptionElementByUuid(UUID uuid);
  63
  64         /**
  65          * Loads and existing DescriptionElementBase instance matching the supplied uuid,
  66          * and recursively initializes all bean properties given in the
  67          * <code>propertyPaths</code> parameter.
  68          * <p>
  69          * For detailed description and examples <b>please refer to:</b>
  70          * {@link BeanInitializer#initialize(Object, List)}
  71          *
  72          * @param uuid the uuid of the DescriptionElement of interest
  73          * @return a DescriptionElement, or null if the DescriptionElement does not exist
  74          */
  75         public DescriptionElementBase loadDescriptionElement(UUID uuid,List<String> propertyPaths);
  76
  77         /**
  78          * Persists a <code>DescriptionElementBase</code>
  79          * @param descriptionElement
  80          * @return
  81          */
  82         public UUID saveDescriptionElement(DescriptionElementBase descriptionElement);
  83
  84         /**
  85          * Persists a collection of <code>DescriptionElementBase</code>
  86          * @param descriptionElements
  87          * @return
  88          */
  89         public Map<UUID, DescriptionElementBase> saveDescriptionElement(Collection<DescriptionElementBase> descriptionElements);
  90
  91         /**
  92          * Delete an existing description element
  93          *
  94          * @param descriptionElement the description element to be deleted
  95          * @return the unique identifier of the deleted entity
  96          */
  97         public UUID deleteDescriptionElement(DescriptionElementBase descriptionElement);
  98
  99         /**
 100          * List the descriptions of type <T>, filtered using the following parameters
 101          *
 102          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 103          * @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)
 104          * @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)
 105          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 106          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 107          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 108          * @param orderHints may be null
 109          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 110          * @return a Pager containing DescriptionBase instances
 111          */
 112         public Pager<DescriptionBase> page(Class<? extends DescriptionBase> type, Boolean hasMedia, Boolean hasText, Set<Feature> feature, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 113
 114         /**
 115          * Count the descriptions of type <TYPE>, filtered using the following parameters
 116          *
 117          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 118          * @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)
 119          * @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)
 120          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 121          * @return a count of DescriptionBase instances
 122          */
 123         public int count(Class<? extends DescriptionBase> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);
 124
 125         /**
 126          * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
 127          *
 128          * @param description The description which these description elements belong to (can be null to count all description elements)
 129          * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
 130          * @param type The type of description
 131          * @param class
 132          * @param pageSize The maximum number of description elements returned (can be null for all description elements)
 133          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 134          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 135          * @return a Pager containing DescriptionElementBase instances
 136          */
 137         public Pager<DescriptionElementBase> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 138
 139         /**
 140          *
 141          * @param taxonDescriptions
 142          * @param omitLevels
 143          * @return
 144          */
 145         public NamedAreaTree getOrderedDistributions(Set<TaxonDescription> taxonDescriptions,
 146                                                                                                  Set<NamedAreaLevel> omitLevels);
 147
 148
 149         /**
 150          * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
 151          *
 152          * @param description The description which these description elements belong to (can be null to count all description elements)
 153          * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
 154          * @param type The type of description
 155          * @param class
 156          * @param pageSize The maximum number of description elements returned (can be null for all description elements)
 157          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 158          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 159          * @return a List containing DescriptionElementBase instances
 160          */
 161         public List<DescriptionElementBase> listDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 162
 163         /**
 164          * Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType
 165      * @param annotatedObj The object that "owns" the annotations returned
 166          * @param status Only return annotations which are marked with a Marker of this type (can be null to return all annotations)
 167          * @param pageSize The maximum number of terms returned (can be null for all annotations)
 168          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 169          * @param orderHints may be null
 170          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 171          * @return a Pager of Annotation entities
 172          */
 173         public Pager<Annotation> getDescriptionElementAnnotations(DescriptionElementBase annotatedObj, MarkerType status, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 174
 175
 176         /**
 177          * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 178          *
 179          * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 180          * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 181          * @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)
 182          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 183          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 184          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 185          * @return a Pager containing TaxonDescription instances
 186          */
 187         public Pager<TaxonDescription> getTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 188
 189         /**
 190          * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 191          *
 192          * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 193          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 194          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 195          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 196          * @return a Pager containing TaxonNameBase instances
 197          */
 198         public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 199
 200         /**
 201          * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 202          * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 203          *
 204          * @param namedAreas The set of NamedArea instances
 205          * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 206          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 207          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 208          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 209          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 210          * @return a Pager containing TaxonDescription instances
 211          */
 212         public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 213
 214         /**
 215          * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 216          *
 217          * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
 218          * @param queryString
 219          * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
 220          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 221          * @param orderHints
 222          *            Supports path like <code>orderHints.propertyNames</code> which
 223          *            include *-to-one properties like createdBy.username or
 224          *            authorTeam.persistentTitleCache
 225          * @param propertyPaths properties to be initialized
 226          * @return a Pager DescriptionElementBase instances
 227          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 228          */
 229         public Pager<DescriptionElementBase> searchElements(Class<? extends DescriptionElementBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 230
 231         /**
 232      * Returns a List of Media that are associated with a given description element
 233      *
 234          * @param descriptionElement the description element associated with these media
 235          * @param pageSize The maximum number of media returned (can be null for all related media)
 236          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 237          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 238      * @return a Pager containing media instances
 239      */
 240     public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 241
 242     public List<DescriptionElementBase> getDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 243
 244         public DistributionTree getOrderedDistributionsB(Set<TaxonDescription> taxonDescriptions, Set<NamedAreaLevel> levels);
 245
 246 }