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.api.utility.DescriptionUtility;
  21 import eu.etaxonomy.cdm.model.common.Annotation;
  22 import eu.etaxonomy.cdm.model.common.DefinedTerm;
  23 import eu.etaxonomy.cdm.model.common.Language;
  24 import eu.etaxonomy.cdm.model.common.Marker;
  25 import eu.etaxonomy.cdm.model.common.MarkerType;
  26 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  27 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  28 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  29 import eu.etaxonomy.cdm.model.description.Distribution;
  30 import eu.etaxonomy.cdm.model.description.Feature;
  31 import eu.etaxonomy.cdm.model.description.FeatureTree;
  32 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTerm;
  33 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  34 import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
  35 import eu.etaxonomy.cdm.model.location.NamedArea;
  36 import eu.etaxonomy.cdm.model.location.NamedAreaLevel;
  37 import eu.etaxonomy.cdm.model.media.Media;
  38 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  39 import eu.etaxonomy.cdm.model.taxon.Taxon;
  40 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  41 import eu.etaxonomy.cdm.persistence.dto.TermDto;
  42 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  43
  44 public interface IDescriptionService extends IIdentifiableEntityService<DescriptionBase> {
  45
  46     /**
  47      *
  48      * @return
  49      * @deprecated use TermService#getVocabulary(VocabularyType) instead
  50      */
  51     @Deprecated
  52     public TermVocabulary<Feature> getDefaultFeatureVocabulary();
  53
  54     /**
  55      * @deprecated use TermService#getVocabulary(VocabularyType) instead
  56      */
  57     @Deprecated
  58     public TermVocabulary<Feature> getFeatureVocabulary(UUID uuid);
  59
  60     /**
  61      * Gets a DescriptionElementBase instance matching the supplied uuid
  62      *
  63      * @param uuid the uuid of the DescriptionElement of interest
  64      * @return a DescriptionElement, or null if the DescriptionElement does not exist
  65      */
  66     public DescriptionElementBase getDescriptionElementByUuid(UUID uuid);
  67
  68     /**
  69      * Loads and existing DescriptionElementBase instance matching the supplied uuid,
  70      * and recursively initializes all bean properties given in the
  71      * <code>propertyPaths</code> parameter.
  72      * <p>
  73      * For detailed description and examples <b>please refer to:</b>
  74      * {@link IBeanInitializer#initialize(Object, List)}
  75      *
  76      * @param uuid the uuid of the DescriptionElement of interest
  77      * @return a DescriptionElement, or null if the DescriptionElement does not exist
  78      */
  79     public DescriptionElementBase loadDescriptionElement(UUID uuid,List<String> propertyPaths);
  80
  81     /**
  82      * Persists a <code>DescriptionElementBase</code>
  83      * @param descriptionElement
  84      * @return
  85      */
  86     public UUID saveDescriptionElement(DescriptionElementBase descriptionElement);
  87
  88     /**
  89      * Persists a collection of <code>DescriptionElementBase</code>
  90      * @param descriptionElements
  91      * @return
  92      */
  93     public Map<UUID, DescriptionElementBase> saveDescriptionElement(Collection<DescriptionElementBase> descriptionElements);
  94
  95     /**
  96      * Delete an existing description element
  97      *
  98      * @param descriptionElement the description element to be deleted
  99      * @return the unique identifier of the deleted entity
 100      */
 101     public UUID deleteDescriptionElement(DescriptionElementBase descriptionElement);
 102
 103     public UUID deleteDescriptionElement(UUID descriptionElementUuid);
 104
 105     /**
 106      * List the descriptions of type <T>, filtered using the following parameters
 107      *
 108      * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 109      * @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)
 110      * @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)
 111      * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 112      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 113      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 114      * @param orderHints may be null
 115      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 116      * @return a Pager containing DescriptionBase instances
 117      */
 118     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);
 119
 120     /**
 121      * Count the descriptions of type <TYPE>, filtered using the following parameters
 122      *
 123      * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 124      * @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)
 125      * @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)
 126      * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 127      * @return a count of DescriptionBase instances
 128      */
 129     public int count(Class<? extends DescriptionBase> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);
 130
 131     /**
 132      * Returns description elements of type <TYPE>, belonging to a given
 133      * description, optionally filtered by one or more features
 134      *
 135      * @param description
 136      *            The description which these description elements belong to
 137      *            (can be null to count all description elements)
 138      * @param descriptionType
 139      *            A filter DescriptionElements which belong to of a specific
 140      *            class of Descriptions
 141      * @param features
 142      *            Restrict the results to those description elements which are
 143      *            scoped by one of the Features passed (can be null or empty)
 144      * @param type
 145      *            A filter for DescriptionElements of a specific class
 146      * @param pageSize
 147      *            The maximum number of description elements returned (can be
 148      *            null for all description elements)
 149      * @param pageNumber
 150      *            The offset (in pageSize chunks) from the start of the result
 151      *            set (0 - based)
 152      * @param propertyPaths
 153      *            Properties to initialize in the returned entities, following
 154      *            the syntax described in
 155      *            {@link IBeanInitializer#initialize(Object, List)}
 156      * @return a Pager containing DescriptionElementBase instances
 157
 158      * @deprecated use
 159      *             {@link #pageDescriptionElements(DescriptionBase, Set, Class, Integer, Integer, List)}
 160      *             instead
 161      */
 162     @Deprecated
 163     public Pager<DescriptionElementBase> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 164
 165
 166     /**
 167      * Returns description elements of type <TYPE>, belonging to a given
 168      * description, optionally filtered by one or more features
 169      *
 170      * @param description
 171      *            The description which these description elements belong to
 172      *            (can be null to count all description elements)
 173      * @param descriptionType
 174      *            A filter DescriptionElements which belong to of a specific
 175      *            class of Descriptions
 176      * @param features
 177      *            Restrict the results to those description elements which are
 178      *            scoped by one of the Features passed (can be null or empty)
 179      * @param type
 180      *            A filter for DescriptionElements of a specific class
 181      * @param pageSize
 182      *            The maximum number of description elements returned (can be
 183      *            null for all description elements)
 184      * @param pageNumber
 185      *            The offset (in pageSize chunks) from the start of the result
 186      *            set (0 - based)
 187      * @param propertyPaths
 188      *            Properties to initialize in the returned entities, following
 189      *            the syntax described in
 190      *            {@link IBeanInitializer#initialize(Object, List)}
 191      *
 192      * @return a Pager containing DescriptionElementBase instances
 193      */
 194     public Pager<DescriptionElementBase> pageDescriptionElements(DescriptionBase description, Class<? extends DescriptionBase> descriptionType, Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 195
 196     /**
 197      * Returns description elements of type <TYPE>, belonging to a given
 198      * description, optionally filtered by one or more features
 199      *
 200      * @param description
 201      *            The description which these description elements belong to
 202      *            (can be null to count all description elements)
 203      * @param features
 204      *            Restrict the results to those description elements which are
 205      *            scoped by one of the Features passed (can be null or empty)
 206      * @param type
 207      *            A filter for DescriptionElements of a specific class
 208      * @param pageSize
 209      *            The maximum number of description elements returned (can be
 210      *            null for all description elements)
 211      * @param pageNumber
 212      *            The offset (in pageSize chunks) from the start of the result
 213      *            set (0 - based)
 214      * @param propertyPaths
 215      *            Properties to initialize in the returned entities, following
 216      *            the syntax described in
 217      *            {@link IBeanInitializer#initialize(Object, List)}
 218      * @return a List of DescriptionElementBase instances
 219      * @deprecated use {@link #listDescriptionElements(DescriptionBase, Class, Set, Class, Integer, Integer, List)} instead
 220      */
 221     @Deprecated
 222     public List<DescriptionElementBase> listDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 223
 224     /**
 225      * Returns description elements of type <TYPE>, belonging to a given
 226      * description, optionally filtered by one or more features
 227      *
 228      * @param description
 229      *            The description which these description elements belong to
 230      *            (can be null to count all description elements)
 231      * @param features
 232      *            Restrict the results to those description elements which are
 233      *            scoped by one of the Features passed (can be null or empty)
 234      * @param type
 235      *            A filter DescriptionElements of a for specific class
 236      * @param pageSize
 237      *            The maximum number of description elements returned (can be
 238      *            null for all description elements)
 239      * @param pageNumber
 240      *            The offset (in pageSize chunks) from the start of the result
 241      *            set (0 - based)
 242      * @param propertyPaths
 243      *            Properties to initialize in the returned entities, following
 244      *            the syntax described in
 245      *            {@link IBeanInitializer#initialize(Object, List)}
 246      * @return a List of DescriptionElementBase instances
 247      */
 248     public List<DescriptionElementBase> listDescriptionElements(DescriptionBase description, Class<? extends DescriptionBase> descriptionType, Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 249
 250     /**
 251      * Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType
 252      * @param annotatedObj The object that "owns" the annotations returned
 253      * @param status Only return annotations which are marked with a Marker of this type (can be null to return all annotations)
 254      * @param pageSize The maximum number of terms returned (can be null for all annotations)
 255      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 256      * @param orderHints may be null
 257      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 258      * @return a Pager of Annotation entities
 259      */
 260     public Pager<Annotation> getDescriptionElementAnnotations(DescriptionElementBase annotatedObj, MarkerType status, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 261
 262
 263     /**
 264      * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 265      *
 266      * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 267      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 268      * @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)
 269      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 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      * @see #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)
 275      */
 276     public Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 277
 278     /**
 279      * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 280      *
 281      * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 282      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 283      * @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)
 284      * @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)
 285      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 286      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 287      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 288      * @return a Pager containing TaxonDescription instances
 289      */
 290     public Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 291
 292     /**
 293      * @see {@link #pageTaxonDescriptions(Taxon, Set, Set, Integer, Integer, List)}
 294      *
 295      * @param taxon
 296      * @param scopes
 297      * @param geographicalScope
 298      * @param pageSize
 299      * @param pageNumber
 300      * @param propertyPaths
 301      * @return
 302      */
 303     public List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 304
 305
 306
 307     /**
 308      * @see {@link #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)}
 309      *
 310      * @param taxon
 311      * @param scopes
 312      * @param geographicalScope
 313      * @param pageSize
 314      * @param pageNumber
 315      * @param propertyPaths
 316      * @return
 317      */
 318     public List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 319
 320     /**
 321      * Returns all {@link Media} attached to a taxon via TaxonDescription.elements.media.
 322      * @param taxonUuid the taxons uuid, if null media for all taxa are returned
 323      * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
 324      * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
 325      * @param pageSize
 326      * @param pageNumber
 327      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 328      * @return
 329      */
 330     public List<Media> listTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 331
 332     /**
 333      * Returns count for all {@link Media} attached to a taxon via TaxonDescription.elements.media.
 334      * @param taxonUuid the taxons uuid, if null media for all taxa are returned
 335      * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
 336      * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
 337      * @return
 338      */
 339     public int countTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes);
 340
 341
 342
 343     /**
 344      * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 345      *
 346      * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 347      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 348      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 349      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 350      * @return a Pager containing TaxonNameBase instances
 351      *
 352      * FIXME candidate for harmonization - rename to pageTaxonNameDescriptions
 353      */
 354     public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 355
 356
 357     /**
 358      * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 359      * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 360      *
 361      * @param namedAreas The set of NamedArea instances
 362      * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 363      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 364      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 365      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 366      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 367      * @return a Pager containing TaxonDescription instances
 368      */
 369     public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTerm presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 370
 371     /**
 372      * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 373      *
 374      * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
 375      * @param queryString
 376      * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
 377      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 378      * @param orderHints
 379      *            Supports path like <code>orderHints.propertyNames</code> which
 380      *            include *-to-one properties like createdBy.username or
 381      *            authorTeam.persistentTitleCache
 382      * @param propertyPaths properties to be initialized
 383      * @return a Pager DescriptionElementBase instances
 384      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 385      */
 386     public Pager<DescriptionElementBase> searchElements(Class<? extends DescriptionElementBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 387
 388     /**
 389      * Returns a List of Media that are associated with a given description element
 390      *
 391      * @param descriptionElement the description element associated with these media
 392      * @param pageSize The maximum number of media returned (can be null for all related media)
 393      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 394      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 395      * @return a Pager containing media instances
 396      *
 397      * FIXME candidate for harmonization - rename to pageMedia
 398      */
 399     public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 400
 401     /**
 402      * Provides access to all DescriptionElements associated with the given Taxon
 403      * via a TaxonDescrition.
 404      *
 405      * @param taxon
 406      *            The Taxon to return Description elements for
 407      * @param features
 408      *            Restrict the results to those description elements which are
 409      *            scoped by one of the Features passed (can be null or empty)
 410      * @param type
 411      *            A filter for DescriptionElements of a specific class
 412      * @param pageSize
 413      *            The maximum number of description elements returned (can be
 414      *            null for all description elements)
 415      * @param pageNumber
 416      *            The offset (in pageSize chunks) from the start of the result
 417      *            set (0 - based)
 418      * @param propertyPaths
 419      *            Properties to initialize in the returned entities, following
 420      *            the syntax described in
 421      *            {@link IBeanInitializer#initialize(Object, List)}
 422      * @return a List containing all matching DescriptionElementBase instances
 423      *
 424      * @deprecated use {@link #listDescriptionElementsForTaxon(Taxon, Set, Class, Integer, Integer, List)} instead
 425      */
 426     @Deprecated
 427     public <T extends DescriptionElementBase> List<T>  getDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 428
 429     /**
 430      * Provides access to all DescriptionElements associated with the given Taxon
 431      * via a TaxonDescrition.
 432      *
 433      * @param taxon
 434      *            The Taxon to return Description elements for
 435      * @param features
 436      *            Restrict the results to those description elements which are
 437      *            scoped by one of the Features passed (can be null or empty)
 438      * @param type
 439      *            A filter for DescriptionElements of a specific class
 440      * @param pageSize
 441      *            The maximum number of description elements returned (can be
 442      *            null for all description elements)
 443      * @param pageNumber
 444      *            The offset (in pageSize chunks) from the start of the result
 445      *            set (0 - based)
 446      * @param propertyPaths
 447      *            Properties to initialize in the returned entities, following
 448      *            the syntax described in
 449      *            {@link IBeanInitializer#initialize(Object, List)}
 450      * @return a List containing all matching DescriptionElementBase instances
 451      *
 452      */
 453     public <T extends DescriptionElementBase> List<T>  listDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 454
 455     /**
 456      * Provides access to all DescriptionElements associated with the given Taxon
 457      * via a TaxonDescrition.
 458      *
 459      * @param taxon
 460      *            The Taxon to return Description elements for
 461      * @param features
 462      *            Restrict the results to those description elements which are
 463      *            scoped by one of the Features passed (can be null or empty)
 464      * @param type
 465      *            A filter for DescriptionElements of a specific class
 466      * @param pageSize
 467      *            The maximum number of description elements returned
 468      * @param pageNumber
 469      *            The offset (in pageSize chunks) from the start of the result
 470      *            set (0 - based)
 471      * @param propertyPaths
 472      *            Properties to initialize in the returned entities, following
 473      *            the syntax described in
 474      *            {@link IBeanInitializer#initialize(Object, List)}
 475      * @return a Pager for all matching DescriptionElementBase instances
 476      *
 477      */
 478     public <T extends DescriptionElementBase> Pager<T>  pageDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 479
 480
 481     /**
 482      * @param taxonDescriptions
 483      * @param subAreaPreference
 484      *            enables the <b>Sub area preference rule</b> if set to true,
 485      *            see {@link DescriptionUtility#filterDistributions(Collection,
 486      *            boolean, boolean}
 487
 488      * @param statusOrderPreference
 489      *            enables the <b>Status order preference rule</b> if set to
 490      *            true, see {@link
 491      *            DescriptionUtility#filterDistributions(Collection, boolean,
 492      *            boolean}
 493      * @param hideMarkedAreas
 494      *            distributions where the area has a {@link Marker} with one of
 495      *            the specified {@link MarkerType}s will be skipped, see
 496      *            {@link DescriptionUtility#filterDistributions(Collection, boolean, boolean, Set)}
 497      * @param omitLevels
 498      *            A Set NamedArea levels to omit - optional
 499      * @param propertyPaths
 500      *            the initialization strategy
 501      *
 502      * @return
 503      * @deprecated use {@link IEditGeoService#composeDistributionInfoFor()} instead
 504      */
 505     @Deprecated
 506     public DistributionTree getOrderedDistributions(
 507             Set<TaxonDescription> taxonDescriptions,
 508             boolean subAreaPreference,
 509             boolean statusOrderPreference,
 510             Set<MarkerType> hideMarkedAreas,
 511             Set<NamedAreaLevel> omitLevels, List<String> propertyPaths);
 512
 513     /**
 514       * Generate a string representation of the structured <code>description</code> supplied in natural language
 515       * The <code>featureTree</code> will be used to structure the NaturalLanguageDescription.
 516       * This method does not require a initialization strategy so there is no <code>propertyPaths</code> parameter.
 517       * @param featureTree
 518       * @param description
 519       * @param preferredLanguages
 520       * @param separator
 521       * @return
 522       */
 523     public String generateNaturalLanguageDescription(FeatureTree featureTree,TaxonDescription description, List<Language> preferredLanguages, String separator);
 524
 525     /**
 526      * Preliminary method to test whether a description contains structured data.
 527      * @deprecated The means of determining this fact may change soon, so this method is
 528                     annotated as being deprecated.
 529      * @param description
 530      * @return
 531      */
 532     @Deprecated
 533     public boolean hasStructuredData(DescriptionBase<?> description);
 534
 535     /**
 536      * Add the collection of {@link DescriptionElementBase description elements} to the <code>targetDescription</code>.
 537      * Remove the description elements from the description they are currently associated with.
 538      *
 539      * @param descriptionElements
 540      * @param targetDescription
 541      * @param isPaste if true, the elements are only copied (cloned) and not removed from the
 542      *  old description
 543      */
 544     public void moveDescriptionElementsToDescription(Collection<DescriptionElementBase> descriptionElements, DescriptionBase targetDescription, boolean isPaste);
 545
 546     /**
 547      * Pager method to get all {@link NamedAreas} instances which are currently used
 548      * by {@link Distribution} elements.
 549      *
 550      * @param pageSize
 551      *            The maximum number of description elements returned
 552      * @param pageNumber
 553      *            The offset (in pageSize chunks) from the start of the result
 554      *            set (0 - based)
 555      * @param propertyPaths
 556      *            Properties to initialize in the returned entities, following
 557      *            the syntax described in
 558      *            {@link IBeanInitializer#initialize(Object, List)}
 559      * @return a Pager for all NamedAreas instances which are currently in use.
 560      *
 561      */
 562     public Pager<TermDto> pageNamedAreasInUse(boolean includeAllParents, Integer pageSize,
 563             Integer pageNumber);
 564
 565         public DeleteResult deleteDescription(DescriptionBase description);
 566
 567         public DeleteResult deleteDescription(UUID descriptionUuid);
 568
 569     /**
 570      * @param sourceTaxon
 571      * @param targetTaxon
 572      * @return
 573      */
 574     public UpdateResult moveTaxonDescriptions(Taxon sourceTaxon, Taxon targetTaxon);
 575
 576     /**
 577      * @param sourceTaxonUuid
 578      * @param targetTaxonUuid
 579      * @return
 580      */
 581     public UpdateResult moveTaxonDescriptions(UUID sourceTaxonUuid, UUID targetTaxonUuid);
 582
 583 }