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.IBeanInitializer;
  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     @Deprecated
  48     public TermVocabulary<Feature> getDefaultFeatureVocabulary();
  49
  50     /**
  51      * @deprecated use TermService#getVocabulary(VocabularyType) instead
  52      */
  53     @Deprecated
  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 IBeanInitializer#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 IBeanInitializer#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 IBeanInitializer#initialize(Object, List)}
 135      * @return a Pager containing DescriptionElementBase instances
 136      *
 137      * FIXME candidate for harmonization - rename to pageDescriptionElements
 138      */
 139     public Pager<DescriptionElementBase> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 140
 141     /**
 142      * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
 143      *
 144      * @param description The description which these description elements belong to (can be null to count all description elements)
 145      * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
 146      * @param type The type of description
 147      * @param class
 148      * @param pageSize The maximum number of description elements returned (can be null for all description elements)
 149      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 150      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 151      * @return a List containing DescriptionElementBase instances
 152      */
 153     public List<DescriptionElementBase> listDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 154
 155     /**
 156      * Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType
 157      * @param annotatedObj The object that "owns" the annotations returned
 158      * @param status Only return annotations which are marked with a Marker of this type (can be null to return all annotations)
 159      * @param pageSize The maximum number of terms returned (can be null for all annotations)
 160      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 161      * @param orderHints may be null
 162      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 163      * @return a Pager of Annotation entities
 164      */
 165     public Pager<Annotation> getDescriptionElementAnnotations(DescriptionElementBase annotatedObj, MarkerType status, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 166
 167
 168     /**
 169      * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 170      *
 171      * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 172      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 173      * @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)
 174      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 175      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 176      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 177      * @return a Pager containing TaxonDescription instances
 178      *
 179      * @see #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)
 180      */
 181     public Pager<TaxonDescription> pageTaxonDescriptions(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 IBeanInitializer#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 #pageTaxonDescriptions(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      * Returns all {@link Media} attached to a taxon via TaxonDescription.elements.media.
 227      * @param taxonUuid the taxons uuid, if null media for all taxa are returned
 228      * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
 229      * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
 230      * @param pageSize
 231      * @param pageNumber
 232      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 233      * @return
 234      */
 235     public List<Media> listTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 236
 237     /**
 238      * Returns count for all {@link Media} attached to a taxon via TaxonDescription.elements.media.
 239      * @param taxonUuid the taxons uuid, if null media for all taxa are returned
 240      * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
 241      * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
 242      * @return
 243      */
 244     public int countTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes);
 245
 246
 247
 248     /**
 249      * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 250      *
 251      * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 252      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 253      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 254      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 255      * @return a Pager containing TaxonNameBase instances
 256      *
 257      * FIXME candidate for harmonization - rename to pageTaxonNameDescriptions
 258      */
 259     public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 260
 261
 262     /**
 263      * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 264      * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 265      *
 266      * @param namedAreas The set of NamedArea instances
 267      * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 268      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 269      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 270      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 271      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 272      * @return a Pager containing TaxonDescription instances
 273      */
 274     public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 275
 276     /**
 277      * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 278      *
 279      * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
 280      * @param queryString
 281      * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
 282      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 283      * @param orderHints
 284      *            Supports path like <code>orderHints.propertyNames</code> which
 285      *            include *-to-one properties like createdBy.username or
 286      *            authorTeam.persistentTitleCache
 287      * @param propertyPaths properties to be initialized
 288      * @return a Pager DescriptionElementBase instances
 289      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 290      */
 291     public Pager<DescriptionElementBase> searchElements(Class<? extends DescriptionElementBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 292
 293     /**
 294      * Returns a List of Media that are associated with a given description element
 295      *
 296      * @param descriptionElement the description element associated with these media
 297      * @param pageSize The maximum number of media returned (can be null for all related media)
 298      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 299      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 300      * @return a Pager containing media instances
 301      *
 302      * FIXME candidate for harmonization - rename to pageMedia
 303      */
 304     public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 305
 306     public <T extends DescriptionElementBase> List<T>  getDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 307
 308     public DistributionTree getOrderedDistributions(Set<TaxonDescription> taxonDescriptions, Set<NamedAreaLevel> levels, List<String> propertyPaths);
 309
 310     /**
 311       * Generate a string representation of the structured <code>description</code> supplied in natural language
 312       * The <code>featureTree</code> will be used to structure the NaturalLanguageDescription.
 313       * This method does not require a initialization strategy so there is no <code>propertyPaths</code> parameter.
 314       * @param featureTree
 315       * @param description
 316       * @param preferredLanguages
 317       * @param separator
 318       * @return
 319       */
 320     public String generateNaturalLanguageDescription(FeatureTree featureTree,TaxonDescription description, List<Language> preferredLanguages, String separator);
 321
 322     /**
 323      * Preliminary method to test whether a description contains structured data.
 324      * @deprecated The means of determining this fact may change soon, so this method is
 325                     annotated as being deprecated.
 326      * @param description
 327      * @return
 328      */
 329     @Deprecated
 330     public boolean hasStructuredData(DescriptionBase<?> description);
 331
 332     /**
 333      * Add the collection of {@link DescriptionElementBase description elements} to the <code>targetDescription</code>.
 334      * Remove the description elements from the description they are currently associated with.
 335      *
 336      * @param descriptionElements
 337      * @param targetDescription
 338      * @param isPaste if true, the elements are only copied (cloned) and not removed from the
 339      *  old description
 340      */
 341     public void moveDescriptionElementsToDescription(Collection<DescriptionElementBase> descriptionElements, DescriptionBase targetDescription, boolean isPaste);
 342
 343 }