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