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.Language;
  22 import eu.etaxonomy.cdm.model.common.MarkerType;
  23 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  24 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  25 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  26 import eu.etaxonomy.cdm.model.description.Feature;
  27 import eu.etaxonomy.cdm.model.description.FeatureTree;
  28 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase;
  29 import eu.etaxonomy.cdm.model.description.Scope;
  30 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  31 import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
  32 import eu.etaxonomy.cdm.model.location.NamedArea;
  33 import eu.etaxonomy.cdm.model.location.NamedAreaLevel;
  34 import eu.etaxonomy.cdm.model.media.Media;
  35 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  36 import eu.etaxonomy.cdm.model.taxon.Taxon;
  37 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  38 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  39
  40 public interface IDescriptionService extends IIdentifiableEntityService<DescriptionBase> {
  41
  42         /**
  43          *
  44          * @return
  45          * @deprecated use TermService#getVocabulary(VocabularyType) instead
  46          */
  47         public TermVocabulary<Feature> getDefaultFeatureVocabulary();
  48
  49         /**
  50          * @deprecated use TermService#getVocabulary(VocabularyType) instead
  51          */
  52         public TermVocabulary<Feature> getFeatureVocabulary(UUID uuid);
  53
  54         /**
  55          * Gets a DescriptionElementBase instance matching the supplied uuid
  56          *
  57          * @param uuid the uuid of the DescriptionElement of interest
  58          * @return a DescriptionElement, or null if the DescriptionElement does not exist
  59          */
  60         public DescriptionElementBase getDescriptionElementByUuid(UUID uuid);
  61
  62         /**
  63          * Loads and existing DescriptionElementBase instance matching the supplied uuid,
  64          * and recursively initializes all bean properties given in the
  65          * <code>propertyPaths</code> parameter.
  66          * <p>
  67          * For detailed description and examples <b>please refer to:</b>
  68          * {@link BeanInitializer#initialize(Object, List)}
  69          *
  70          * @param uuid the uuid of the DescriptionElement of interest
  71          * @return a DescriptionElement, or null if the DescriptionElement does not exist
  72          */
  73         public DescriptionElementBase loadDescriptionElement(UUID uuid,List<String> propertyPaths);
  74
  75         /**
  76          * Persists a <code>DescriptionElementBase</code>
  77          * @param descriptionElement
  78          * @return
  79          */
  80         public UUID saveDescriptionElement(DescriptionElementBase descriptionElement);
  81
  82         /**
  83          * Persists a collection of <code>DescriptionElementBase</code>
  84          * @param descriptionElements
  85          * @return
  86          */
  87         public Map<UUID, DescriptionElementBase> saveDescriptionElement(Collection<DescriptionElementBase> descriptionElements);
  88
  89         /**
  90          * Delete an existing description element
  91          *
  92          * @param descriptionElement the description element to be deleted
  93          * @return the unique identifier of the deleted entity
  94          */
  95         public UUID deleteDescriptionElement(DescriptionElementBase descriptionElement);
  96
  97         /**
  98          * List the descriptions of type <T>, filtered using the following parameters
  99          *
 100          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 101          * @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)
 102          * @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)
 103          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 104          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 105          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 106          * @param orderHints may be null
 107          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 108          * @return a Pager containing DescriptionBase instances
 109          */
 110         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);
 111
 112         /**
 113          * Count the descriptions of type <TYPE>, filtered using the following parameters
 114          *
 115          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 116          * @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)
 117          * @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)
 118          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 119          * @return a count of DescriptionBase instances
 120          */
 121         public int count(Class<? extends DescriptionBase> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);
 122
 123         /**
 124          * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
 125          *
 126          * @param description The description which these description elements belong to (can be null to count all description elements)
 127          * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
 128          * @param type The type of description
 129          * @param class
 130          * @param pageSize The maximum number of description elements returned (can be null for all description elements)
 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 Pager containing DescriptionElementBase instances
 134          *
 135          * FIXME candidate for harmonization - rename to pageDescriptionElements
 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          * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
 141          *
 142          * @param description The description which these description elements belong to (can be null to count all description elements)
 143          * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
 144          * @param type The type of description
 145          * @param class
 146          * @param pageSize The maximum number of description elements returned (can be null for all description elements)
 147          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 148          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 149          * @return a List containing DescriptionElementBase instances
 150          */
 151         public List<DescriptionElementBase> listDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 152
 153         /**
 154          * Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType
 155      * @param annotatedObj The object that "owns" the annotations returned
 156          * @param status Only return annotations which are marked with a Marker of this type (can be null to return all annotations)
 157          * @param pageSize The maximum number of terms returned (can be null for all annotations)
 158          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 159          * @param orderHints may be null
 160          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 161          * @return a Pager of Annotation entities
 162          */
 163         public Pager<Annotation> getDescriptionElementAnnotations(DescriptionElementBase annotatedObj, MarkerType status, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 164
 165
 166         /**
 167          * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 168          *
 169          * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 170          * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 171          * @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)
 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 BeanInitializer#initialize(Object, List)}
 175          * @return a Pager containing TaxonDescription instances
 176          *
 177          * FIXME candidate for harmonization - rename to pageTaxonDescriptions
 178          *
 179          * @see #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)
 180          */
 181         public Pager<TaxonDescription> getTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 182
 183         /**
 184          * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 185          *
 186          * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 187          * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 188          * @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)
 189          * @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)
 190          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 191          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 192          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 193          * @return a Pager containing TaxonDescription instances
 194          */
 195         public Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 196
 197         /**
 198          * @see {@link #getTaxonDescriptions(Taxon, Set, Set, Integer, Integer, List)}
 199          *
 200          * @param taxon
 201          * @param scopes
 202          * @param geographicalScope
 203          * @param pageSize
 204          * @param pageNumber
 205          * @param propertyPaths
 206          * @return
 207          */
 208         public List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 209
 210
 211
 212         /**
 213          * @see {@link #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)}
 214          *
 215          * @param taxon
 216          * @param scopes
 217          * @param geographicalScope
 218          * @param pageSize
 219          * @param pageNumber
 220          * @param propertyPaths
 221          * @return
 222          */
 223         public List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 224
 225
 226         /**
 227          * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 228          *
 229          * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 230          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 231          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 232          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 233          * @return a Pager containing TaxonNameBase instances
 234          *
 235          * FIXME candidate for harmonization - rename to pageTaxonNameDescriptions
 236          */
 237         public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 238
 239         /**
 240          * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 241          * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 242          *
 243          * @param namedAreas The set of NamedArea instances
 244          * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 245          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 246          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 247          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 248          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 249          * @return a Pager containing TaxonDescription instances
 250          */
 251         public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 252
 253         /**
 254          * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 255          *
 256          * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
 257          * @param queryString
 258          * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
 259          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 260          * @param orderHints
 261          *            Supports path like <code>orderHints.propertyNames</code> which
 262          *            include *-to-one properties like createdBy.username or
 263          *            authorTeam.persistentTitleCache
 264          * @param propertyPaths properties to be initialized
 265          * @return a Pager DescriptionElementBase instances
 266          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 267          */
 268         public Pager<DescriptionElementBase> searchElements(Class<? extends DescriptionElementBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 269
 270         /**
 271      * Returns a List of Media that are associated with a given description element
 272      *
 273          * @param descriptionElement the description element associated with these media
 274          * @param pageSize The maximum number of media returned (can be null for all related media)
 275          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 276          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 277      * @return a Pager containing media instances
 278      *
 279      * FIXME candidate for harmonization - rename to pageMedia
 280      */
 281     public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 282
 283     public <T extends DescriptionElementBase> List<T>  getDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<? extends T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 284
 285         public DistributionTree getOrderedDistributions(Set<TaxonDescription> taxonDescriptions, Set<NamedAreaLevel> levels, List<String> propertyPaths);
 286
 287         /**
 288           * Generate a string representation of the structured <code>description</code> supplied in natural language
 289           * The <code>featureTree</code> will be used to structure the NaturalLanguageDescription.
 290           * This method does not require a initialization strategy so there is no <code>propertyPaths</code> parameter.
 291           * @param featureTree
 292           * @param description
 293           * @param preferredLanguages
 294           * @param separator
 295           * @return
 296           */
 297         public String generateNaturalLanguageDescription(FeatureTree featureTree,TaxonDescription description, List<Language> preferredLanguages, String separator);
 298
 299         /**
 300          * Preliminary method to test whether a description contains structured data.
 301          * @deprecated The means of determining this fact may change soon, so this method is
 302                                         annotated as being deprecated.
 303          * @param description
 304          * @return
 305          */
 306         @Deprecated
 307         public boolean hasStructuredData(DescriptionBase<?> description);
 308
 309         /**
 310          * Add the collection of {@link DescriptionElementBase description elements} to the <code>targetDescription</code>.
 311          * Remove the description elements from the description they are currently associated with.
 312          *
 313          * @param descriptionElements
 314          * @param targetDescription
 315          * @param isPaste if true, the elements are only copied (cloned) and not removed from the
 316          *      old description
 317          */
 318         public void moveDescriptionElementsToDescription(Collection<DescriptionElementBase> descriptionElements, DescriptionBase targetDescription, boolean isPaste);
 319
 320 }