cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IDescriptionService.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 package eu.etaxonomy.cdm.api.service;
  10
  11 import java.util.Collection;
  12 import java.util.List;
  13 import java.util.Set;
  14 import java.util.UUID;
  15
  16 import eu.etaxonomy.cdm.api.service.dto.TaxonDistributionDTO;
  17 import eu.etaxonomy.cdm.api.service.pager.Pager;
  18 import eu.etaxonomy.cdm.model.common.Language;
  19 import eu.etaxonomy.cdm.model.common.MarkerType;
  20 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  21 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  22 import eu.etaxonomy.cdm.model.description.DescriptionType;
  23 import eu.etaxonomy.cdm.model.description.Distribution;
  24 import eu.etaxonomy.cdm.model.description.Feature;
  25 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  26 import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
  27 import eu.etaxonomy.cdm.model.location.NamedArea;
  28 import eu.etaxonomy.cdm.model.media.Media;
  29 import eu.etaxonomy.cdm.model.name.TaxonName;
  30 import eu.etaxonomy.cdm.model.taxon.Taxon;
  31 import eu.etaxonomy.cdm.model.term.DefinedTerm;
  32 import eu.etaxonomy.cdm.model.term.TermTree;
  33 import eu.etaxonomy.cdm.model.term.TermVocabulary;
  34 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  35 import eu.etaxonomy.cdm.persistence.dto.DescriptionBaseDto;
  36 import eu.etaxonomy.cdm.persistence.dto.MergeResult;
  37 import eu.etaxonomy.cdm.persistence.dto.TaxonNodeDto;
  38 import eu.etaxonomy.cdm.persistence.dto.TermDto;
  39 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  40
  41 public interface IDescriptionService extends IIdentifiableEntityService<DescriptionBase> {
  42
  43     /**
  44      * @return
  45      * @deprecated use TermService#getVocabulary(VocabularyType) instead
  46      */
  47     @Deprecated
  48     public TermVocabulary<Feature> getDefaultFeatureVocabulary();
  49
  50     /**
  51      * List the descriptions of type <T>, filtered using the following parameters
  52      *
  53      * @param type The type of description returned (Taxon, TaxonName, or Specimen)
  54      * @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)
  55      * @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)
  56      * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
  57      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
  58      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  59      * @param orderHints may be null
  60      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  61      * @return a Pager containing DescriptionBase instances
  62      */
  63     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);
  64
  65     /**
  66      * Count the descriptions of type <TYPE>, filtered using the following parameters
  67      *
  68      * @param type The type of description returned (Taxon, TaxonName, or Specimen)
  69      * @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)
  70      * @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)
  71      * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
  72      * @return a count of DescriptionBase instances
  73      */
  74     public long count(Class<? extends DescriptionBase> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);
  75
  76     /**
  77      * Returns description elements of type <TYPE>, belonging to a given
  78      * description, optionally filtered by one or more features
  79      *
  80      * @param description
  81      *            The description which these description elements belong to
  82      *            (can be null to count all description elements)
  83      * @param descriptionType
  84      *            A filter DescriptionElements which belong to of a specific
  85      *            class of Descriptions
  86      * @param features
  87      *            Restrict the results to those description elements which are
  88      *            scoped by one of the Features passed (can be null or empty)
  89      * @param type
  90      *            A filter for DescriptionElements of a specific class
  91      * @param pageSize
  92      *            The maximum number of description elements returned (can be
  93      *            null for all description elements)
  94      * @param pageNumber
  95      *            The offset (in pageSize chunks) from the start of the result
  96      *            set (0 - based)
  97      * @param propertyPaths
  98      *            Properties to initialize in the returned entities, following
  99      *            the syntax described in
 100      *            {@link IBeanInitializer#initialize(Object, List)}
 101      *
 102      * @return a Pager containing DescriptionElementBase instances
 103      */
 104     public <T extends DescriptionElementBase> Pager<T> pageDescriptionElements(
 105             DescriptionBase description, Class<? extends DescriptionBase> descriptionType,
 106             Set<Feature> features, Class<T> type, boolean includeUnpublished,
 107             Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 108
 109     /**
 110      * Returns description elements of type <TYPE>, belonging to a given
 111      * description, optionally filtered by one or more features
 112      *
 113      * @param description
 114      *            The description which these description elements belong to
 115      *            (can be null to count all description elements)
 116      * @param features
 117      *            Restrict the results to those description elements which are
 118      *            scoped by one of the Features passed (can be null or empty)
 119      * @param type
 120      *            A filter DescriptionElements of a specific class
 121      * @param pageSize
 122      *            The maximum number of description elements returned (can be
 123      *            null for all description elements)
 124      * @param pageNumber
 125      *            The offset (in pageSize chunks) from the start of the result
 126      *            set (0 - based)
 127      * @param propertyPaths
 128      *            Properties to initialize in the returned entities, following
 129      *            the syntax described in
 130      *            {@link IBeanInitializer#initialize(Object, List)}
 131      * @return a List of DescriptionElementBase instances
 132      */
 133     public <T extends DescriptionElementBase> List<T> listDescriptionElements(
 134             DescriptionBase description, Class<? extends DescriptionBase> descriptionType,
 135             Set<Feature> features, Class<T> type, boolean includeUnpublished,
 136             Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 137
 138
 139     /**
 140      * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 141      *
 142      * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 143      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 144      * @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)
 145      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 146      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 147      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 148      * @return a Pager containing TaxonDescription instances
 149      *
 150      * @see #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)
 151      */
 152     public Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 153
 154     /**
 155      * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 156      *
 157      * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 158      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 159      * @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)
 160      * @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)
 161      * @param descriptionTypes Restrict the results to those descriptions of the given types (can be null or empty)
 162      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 163      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 164      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 165      * @return a Pager containing TaxonDescription instances
 166      */
 167     public Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Set<DescriptionType> descriptionTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 168
 169
 170     /**
 171      * @see {@link #pageTaxonDescriptions(Taxon, Set, Set, Integer, Integer, List)}
 172      *
 173      * @param taxon
 174      * @param scopes
 175      * @param geographicalScope
 176      * @param pageSize
 177      * @param pageNumber
 178      * @param propertyPaths
 179      * @return
 180      */
 181     public List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 182
 183
 184
 185     /**
 186      * @see {@link #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)}
 187      *
 188      * @param taxon
 189      * @param scopes
 190      * @param geographicalScope
 191      * @param pageSize
 192      * @param pageNumber
 193      * @param propertyPaths
 194      * @return
 195      */
 196     public List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Set<DescriptionType> descriptionTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 197
 198     /**
 199      * Returns all {@link Media} attached to a taxon via TaxonDescription.elements.media.
 200      * @param taxonUuid the taxons uuid, if null media for all taxa are returned
 201      * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
 202      * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
 203      * @param pageSize
 204      * @param pageNumber
 205      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 206      * @return
 207      */
 208     public List<Media> listTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 209
 210     /**
 211      * Returns count for all {@link Media} attached to a taxon via TaxonDescription.elements.media.
 212      * @param taxonUuid the taxons uuid, if null media for all taxa are returned
 213      * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
 214      * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
 215      * @return
 216      */
 217     public int countTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes);
 218
 219
 220
 221     /**
 222      * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 223      *
 224      * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 225      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 226      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 227      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 228      * @return a Pager containing TaxonName instances
 229      *
 230      * FIXME candidate for harmonization - rename to pageTaxonNameDescriptions
 231      */
 232     public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonName name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 233
 234     /**
 235      * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 236      *
 237      * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
 238      * @param queryString
 239      * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
 240      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 241      * @param orderHints
 242      *            Supports path like <code>orderHints.propertyNames</code> which
 243      *            include *-to-one properties like createdBy.username or
 244      *            authorTeam.persistentTitleCache
 245      * @param propertyPaths properties to be initialized
 246      * @return a Pager DescriptionElementBase instances
 247      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 248      */
 249     public <S extends DescriptionElementBase> Pager<S> searchElements(Class<S> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 250
 251     /**
 252      * Returns a List of Media that are associated with a given description element
 253      *
 254      * @param descriptionElement the description element associated with these media
 255      * @param pageSize The maximum number of media returned (can be null for all related media)
 256      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 257      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 258      * @return a Pager containing media instances
 259      *
 260      * FIXME candidate for harmonization - rename to pageMedia
 261      */
 262     public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 263
 264     /**
 265      * Provides access to all DescriptionElements associated with the given Taxon
 266      * via a TaxonDescrition.
 267      *
 268      * @param taxon
 269      *            The Taxon to return Description elements for
 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
 274      *            A filter for DescriptionElements of a specific class
 275      * @param pageSize
 276      *            The maximum number of description elements returned (can be
 277      *            null for all description elements)
 278      * @param pageNumber
 279      *            The offset (in pageSize chunks) from the start of the result
 280      *            set (0 - based)
 281      * @param propertyPaths
 282      *            Properties to initialize in the returned entities, following
 283      *            the syntax described in
 284      *            {@link IBeanInitializer#initialize(Object, List)}
 285      * @return a List containing all matching DescriptionElementBase instances
 286      *
 287      * @deprecated use {@link #listDescriptionElementsForTaxon(Taxon, Set, Class, Integer, Integer, List)} instead
 288      */
 289     @Deprecated
 290     public <T extends DescriptionElementBase> List<T>  getDescriptionElementsForTaxon(
 291             Taxon taxon, Set<Feature> features, Class<T> type, boolean includeUnpublished,
 292             Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 293
 294     /**
 295      * Provides access to all DescriptionElements associated with the given Taxon
 296      * via a TaxonDescrition.
 297      *
 298      * @param taxon
 299      *            The Taxon to return Description elements for
 300      * @param features
 301      *            Restrict the results to those description elements which are
 302      *            scoped by one of the Features passed (can be null or empty)
 303      * @param type
 304      *            A filter for DescriptionElements of a specific class
 305      * @param includeUnpublished
 306      *            If true factual data in a description not being published
 307      *            is included.
 308      * @param pageSize
 309      *            The maximum number of description elements returned (can be
 310      *            null for all description elements)
 311      * @param pageNumber
 312      *            The offset (in pageSize chunks) from the start of the result
 313      *            set (0 - based)
 314      * @param propertyPaths
 315      *            Properties to initialize in the returned entities, following
 316      *            the syntax described in
 317      *            {@link IBeanInitializer#initialize(Object, List)}
 318      * @return a List containing all matching DescriptionElementBase instances
 319      *
 320      */
 321     public <T extends DescriptionElementBase> List<T>  listDescriptionElementsForTaxon(
 322             Taxon taxon, Set<Feature> features, Class<T> type, boolean includePublished,
 323             Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 324
 325     /**
 326      * Provides access to all DescriptionElements associated with the given Taxon
 327      * via a TaxonDescrition.
 328      *
 329      * @param taxon
 330      *            The Taxon to return Description elements for
 331      * @param features
 332      *            Restrict the results to those description elements which are
 333      *            scoped by one of the Features passed (can be null or empty)
 334      * @param type
 335      *            A filter for DescriptionElements of a specific class
 336      * @param includeUnpublished
 337      *            If true factual data in a description not being published
 338      *            is included.
 339      * @param pageSize
 340      *            The maximum number of description elements returned
 341      * @param pageNumber
 342      *            The offset (in pageSize chunks) from the start of the result
 343      *            set (0 - based)
 344      * @param propertyPaths
 345      *            Properties to initialize in the returned entities, following
 346      *            the syntax described in
 347      *            {@link IBeanInitializer#initialize(Object, List)}
 348      * @return a Pager for all matching DescriptionElementBase instances
 349      *
 350      */
 351     public <T extends DescriptionElementBase> Pager<T>  pageDescriptionElementsForTaxon(
 352             Taxon taxon, Set<Feature> features, Class<T> type, boolean includeUnpublished,
 353             Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 354
 355     /**
 356       * Generate a string representation of the structured <code>description</code> supplied in natural language
 357       * The <code>featureTree</code> will be used to structure the NaturalLanguageDescription.
 358       * This method does not require a initialization strategy so there is no <code>propertyPaths</code> parameter.
 359       */
 360     public String generateNaturalLanguageDescription(TermTree featureTree,TaxonDescription description, List<Language> preferredLanguages, String separator);
 361
 362     /**
 363      * Preliminary method to test whether a description contains structured data.
 364      * @deprecated The means of determining this fact may change soon, so this method is
 365                     annotated as being deprecated.
 366      * @param description
 367      */
 368     @Deprecated
 369     public boolean hasStructuredData(DescriptionBase<?> description);
 370
 371     /**
 372      * Add the collection of {@link DescriptionElementBase description elements} to the <code>targetDescription</code>.
 373      * Remove the description elements from the description they are currently associated with.
 374      *
 375      * @param descriptionElements
 376      * @param targetDescription
 377      * @param isPaste if true, the elements are only copied (cloned) and not removed from the
 378      *  old description
 379      * @return
 380      */
 381     public UpdateResult moveDescriptionElementsToDescription(Collection<DescriptionElementBase> descriptionElements, DescriptionBase targetDescription, boolean isPaste, boolean setNameInSource);
 382
 383     /**
 384      * Pager method to get all {@link NamedAreas} instances which are currently used
 385      * by {@link Distribution} elements.
 386      *
 387      * @param pageSize
 388      *            The maximum number of description elements returned
 389      * @param pageNumber
 390      *            The offset (in pageSize chunks) from the start of the result
 391      *            set (0 - based)
 392      * @param propertyPaths
 393      *            Properties to initialize in the returned entities, following
 394      *            the syntax described in
 395      *            {@link IBeanInitializer#initialize(Object, List)}
 396      * @return a Pager for all NamedAreas instances which are currently in use.
 397      *
 398      */
 399     public Pager<TermDto> pageNamedAreasInUse(boolean includeAllParents, Integer pageSize,
 400             Integer pageNumber);
 401
 402         /**
 403          * Deletes the description and prior removes it from taxon, specimen or descriptive dataset.
 404          */
 405         public DeleteResult deleteDescription(DescriptionBase<?> description);
 406
 407         public DeleteResult deleteDescription(UUID descriptionUuid);
 408
 409     public UpdateResult moveTaxonDescriptions(Taxon sourceTaxon, Taxon targetTaxon, boolean setNameInSource);
 410
 411     public UpdateResult moveTaxonDescriptions(UUID sourceTaxonUuid, UUID targetTaxonUuid, boolean setNameInSource);
 412
 413     public UpdateResult moveDescriptionElementsToDescription(Set<UUID> descriptionElementUUIDs, UUID targetDescriptionUuid,
 414             boolean isCopy, boolean setNameInSource);
 415
 416     public UpdateResult moveDescriptionElementsToDescription(Set<UUID> descriptionElementUUIDs, UUID targetTaxonUuid,
 417             String moveMessage, boolean isCopy, boolean setNameInSource, boolean useDefaultDescription, boolean createNewCurrentDeterminations);
 418
 419     public UpdateResult moveTaxonDescription(UUID descriptionUuid, UUID targetTaxonUuid, boolean setNameInSource);
 420
 421     public List<MergeResult<DescriptionBase>> mergeDescriptionElements(Collection<TaxonDistributionDTO> descriptionElements,
 422             boolean returnTransientEntity);
 423
 424     public UpdateResult mergeDescriptions(Collection<DescriptionBaseDto> descriptions, UUID descriptiveDataSetUuid);
 425
 426     public UpdateResult moveDescriptionElementsToDescription(Set<UUID> descriptionElementUUIDs,
 427             DescriptionBase targetDescription, boolean isCopy, boolean setNameInSource);
 428
 429     public DeleteResult isDeletable(UUID descriptionUuid);
 430
 431     public DescriptionBaseDto loadDto(UUID descriptionUuid);
 432     public List<DescriptionBaseDto> loadDtos(Set<UUID> descriptionUuid);
 433
 434     public List<DescriptionBaseDto> loadDtosForTaxon(UUID taxonUuid);
 435
 436     /**
 437      * Find the taxon node for the taxon associated to the specimen in classification with classificationUuid
 438      */
 439     public TaxonNodeDto findTaxonNodeDtoForIndividualAssociation(UUID specimenUuid, UUID classificationUuid);
 440
 441 }