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.DefinedTerm;
  22 import eu.etaxonomy.cdm.model.common.Language;
  23 import eu.etaxonomy.cdm.model.common.MarkerType;
  24 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  25 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  26 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  27 import eu.etaxonomy.cdm.model.description.Feature;
  28 import eu.etaxonomy.cdm.model.description.FeatureTree;
  29 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase;
  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
 127      * description, optionally filtered by one or more features
 128      *
 129      * @param description
 130      *            The description which these description elements belong to
 131      *            (can be null to count all description elements)
 132      * @param descriptionType
 133      *            A filter DescriptionElements which belong to of a specific
 134      *            class of Descriptions
 135      * @param features
 136      *            Restrict the results to those description elements which are
 137      *            scoped by one of the Features passed (can be null or empty)
 138      * @param type
 139      *            A filter for DescriptionElements of a specific class
 140      * @param pageSize
 141      *            The maximum number of description elements returned (can be
 142      *            null for all description elements)
 143      * @param pageNumber
 144      *            The offset (in pageSize chunks) from the start of the result
 145      *            set (0 - based)
 146      * @param propertyPaths
 147      *            Properties to initialize in the returned entities, following
 148      *            the syntax described in
 149      *            {@link IBeanInitializer#initialize(Object, List)}
 150      * @return a Pager containing DescriptionElementBase instances
 151
 152      * @deprecated use
 153      *             {@link #pageDescriptionElements(DescriptionBase, Set, Class, Integer, Integer, List)}
 154      *             instead
 155      */
 156     @Deprecated
 157     public Pager<DescriptionElementBase> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 158
 159
 160     /**
 161      * Returns description elements of type <TYPE>, belonging to a given
 162      * description, optionally filtered by one or more features
 163      *
 164      * @param description
 165      *            The description which these description elements belong to
 166      *            (can be null to count all description elements)
 167      * @param descriptionType
 168      *            A filter DescriptionElements which belong to of a specific
 169      *            class of Descriptions
 170      * @param features
 171      *            Restrict the results to those description elements which are
 172      *            scoped by one of the Features passed (can be null or empty)
 173      * @param type
 174      *            A filter for DescriptionElements of a specific class
 175      * @param pageSize
 176      *            The maximum number of description elements returned (can be
 177      *            null for all description elements)
 178      * @param pageNumber
 179      *            The offset (in pageSize chunks) from the start of the result
 180      *            set (0 - based)
 181      * @param propertyPaths
 182      *            Properties to initialize in the returned entities, following
 183      *            the syntax described in
 184      *            {@link IBeanInitializer#initialize(Object, List)}
 185      *
 186      * @return a Pager containing DescriptionElementBase instances
 187      */
 188     public Pager<DescriptionElementBase> pageDescriptionElements(DescriptionBase description, Class<? extends DescriptionBase> descriptionType, Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 189
 190     /**
 191      * Returns description elements of type <TYPE>, belonging to a given
 192      * description, optionally filtered by one or more features
 193      *
 194      * @param description
 195      *            The description which these description elements belong to
 196      *            (can be null to count all description elements)
 197      * @param features
 198      *            Restrict the results to those description elements which are
 199      *            scoped by one of the Features passed (can be null or empty)
 200      * @param type
 201      *            A filter for DescriptionElements of a specific class
 202      * @param pageSize
 203      *            The maximum number of description elements returned (can be
 204      *            null for all description elements)
 205      * @param pageNumber
 206      *            The offset (in pageSize chunks) from the start of the result
 207      *            set (0 - based)
 208      * @param propertyPaths
 209      *            Properties to initialize in the returned entities, following
 210      *            the syntax described in
 211      *            {@link IBeanInitializer#initialize(Object, List)}
 212      * @return a List of DescriptionElementBase instances
 213      * @deprecated use {@link #listDescriptionElements(DescriptionBase, Class, Set, Class, Integer, Integer, List)} instead
 214      */
 215     @Deprecated
 216     public List<DescriptionElementBase> listDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 217
 218     /**
 219      * Returns description elements of type <TYPE>, belonging to a given
 220      * description, optionally filtered by one or more features
 221      *
 222      * @param description
 223      *            The description which these description elements belong to
 224      *            (can be null to count all description elements)
 225      * @param features
 226      *            Restrict the results to those description elements which are
 227      *            scoped by one of the Features passed (can be null or empty)
 228      * @param type
 229      *            A filter DescriptionElements of a for specific class
 230      * @param pageSize
 231      *            The maximum number of description elements returned (can be
 232      *            null for all description elements)
 233      * @param pageNumber
 234      *            The offset (in pageSize chunks) from the start of the result
 235      *            set (0 - based)
 236      * @param propertyPaths
 237      *            Properties to initialize in the returned entities, following
 238      *            the syntax described in
 239      *            {@link IBeanInitializer#initialize(Object, List)}
 240      * @return a List of DescriptionElementBase instances
 241      */
 242     public List<DescriptionElementBase> listDescriptionElements(DescriptionBase description, Class<? extends DescriptionBase> descriptionType, Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 243
 244     /**
 245      * Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType
 246      * @param annotatedObj The object that "owns" the annotations returned
 247      * @param status Only return annotations which are marked with a Marker of this type (can be null to return all annotations)
 248      * @param pageSize The maximum number of terms returned (can be null for all annotations)
 249      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 250      * @param orderHints may be null
 251      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 252      * @return a Pager of Annotation entities
 253      */
 254     public Pager<Annotation> getDescriptionElementAnnotations(DescriptionElementBase annotatedObj, MarkerType status, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 255
 256
 257     /**
 258      * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 259      *
 260      * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 261      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 262      * @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)
 263      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 264      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 265      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 266      * @return a Pager containing TaxonDescription instances
 267      *
 268      * @see #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)
 269      */
 270     public Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 271
 272     /**
 273      * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 274      *
 275      * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 276      * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 277      * @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)
 278      * @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)
 279      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 280      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 281      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 282      * @return a Pager containing TaxonDescription instances
 283      */
 284     public Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 285
 286     /**
 287      * @see {@link #pageTaxonDescriptions(Taxon, Set, Set, Integer, Integer, List)}
 288      *
 289      * @param taxon
 290      * @param scopes
 291      * @param geographicalScope
 292      * @param pageSize
 293      * @param pageNumber
 294      * @param propertyPaths
 295      * @return
 296      */
 297     public List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 298
 299
 300
 301     /**
 302      * @see {@link #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)}
 303      *
 304      * @param taxon
 305      * @param scopes
 306      * @param geographicalScope
 307      * @param pageSize
 308      * @param pageNumber
 309      * @param propertyPaths
 310      * @return
 311      */
 312     public List<TaxonDescription> listTaxonDescriptions(Taxon taxon, Set<DefinedTerm> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 313
 314     /**
 315      * Returns all {@link Media} attached to a taxon via TaxonDescription.elements.media.
 316      * @param taxonUuid the taxons uuid, if null media for all taxa are returned
 317      * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
 318      * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
 319      * @param pageSize
 320      * @param pageNumber
 321      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 322      * @return
 323      */
 324     public List<Media> listTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 325
 326     /**
 327      * Returns count for all {@link Media} attached to a taxon via TaxonDescription.elements.media.
 328      * @param taxonUuid the taxons uuid, if null media for all taxa are returned
 329      * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
 330      * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
 331      * @return
 332      */
 333     public int countTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes);
 334
 335
 336
 337     /**
 338      * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 339      *
 340      * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 341      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 342      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 343      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 344      * @return a Pager containing TaxonNameBase instances
 345      *
 346      * FIXME candidate for harmonization - rename to pageTaxonNameDescriptions
 347      */
 348     public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 349
 350
 351     /**
 352      * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 353      * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 354      *
 355      * @param namedAreas The set of NamedArea instances
 356      * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 357      * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 358      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 359      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 360      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 361      * @return a Pager containing TaxonDescription instances
 362      */
 363     public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 364
 365     /**
 366      * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 367      *
 368      * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
 369      * @param queryString
 370      * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
 371      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 372      * @param orderHints
 373      *            Supports path like <code>orderHints.propertyNames</code> which
 374      *            include *-to-one properties like createdBy.username or
 375      *            authorTeam.persistentTitleCache
 376      * @param propertyPaths properties to be initialized
 377      * @return a Pager DescriptionElementBase instances
 378      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 379      */
 380     public Pager<DescriptionElementBase> searchElements(Class<? extends DescriptionElementBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 381
 382     /**
 383      * Returns a List of Media that are associated with a given description element
 384      *
 385      * @param descriptionElement the description element associated with these media
 386      * @param pageSize The maximum number of media returned (can be null for all related media)
 387      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 388      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 389      * @return a Pager containing media instances
 390      *
 391      * FIXME candidate for harmonization - rename to pageMedia
 392      */
 393     public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 394
 395     /**
 396      * Provides access to all DescriptionElements associated with the given Taxon
 397      * via a TaxonDescrition.
 398      *
 399      * @param taxon
 400      *            The Taxon to return Description elements for
 401      * @param features
 402      *            Restrict the results to those description elements which are
 403      *            scoped by one of the Features passed (can be null or empty)
 404      * @param type
 405      *            A filter for DescriptionElements of a specific class
 406      * @param pageSize
 407      *            The maximum number of description elements returned (can be
 408      *            null for all description elements)
 409      * @param pageNumber
 410      *            The offset (in pageSize chunks) from the start of the result
 411      *            set (0 - based)
 412      * @param propertyPaths
 413      *            Properties to initialize in the returned entities, following
 414      *            the syntax described in
 415      *            {@link IBeanInitializer#initialize(Object, List)}
 416      * @return a List containing all matching DescriptionElementBase instances
 417      *
 418      * @deprecated use {@link #listDescriptionElementsForTaxon(Taxon, Set, Class, Integer, Integer, List)} instead
 419      */
 420     @Deprecated
 421     public <T extends DescriptionElementBase> List<T>  getDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 422
 423     /**
 424      * Provides access to all DescriptionElements associated with the given Taxon
 425      * via a TaxonDescrition.
 426      *
 427      * @param taxon
 428      *            The Taxon to return Description elements for
 429      * @param features
 430      *            Restrict the results to those description elements which are
 431      *            scoped by one of the Features passed (can be null or empty)
 432      * @param type
 433      *            A filter for DescriptionElements of a specific class
 434      * @param pageSize
 435      *            The maximum number of description elements returned (can be
 436      *            null for all description elements)
 437      * @param pageNumber
 438      *            The offset (in pageSize chunks) from the start of the result
 439      *            set (0 - based)
 440      * @param propertyPaths
 441      *            Properties to initialize in the returned entities, following
 442      *            the syntax described in
 443      *            {@link IBeanInitializer#initialize(Object, List)}
 444      * @return a List containing all matching DescriptionElementBase instances
 445      *
 446      */
 447     public <T extends DescriptionElementBase> List<T>  listDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 448
 449     /**
 450      * Provides access to all DescriptionElements associated with the given Taxon
 451      * via a TaxonDescrition.
 452      *
 453      * @param taxon
 454      *            The Taxon to return Description elements for
 455      * @param features
 456      *            Restrict the results to those description elements which are
 457      *            scoped by one of the Features passed (can be null or empty)
 458      * @param type
 459      *            A filter for DescriptionElements of a specific class
 460      * @param pageSize
 461      *            The maximum number of description elements returned
 462      * @param pageNumber
 463      *            The offset (in pageSize chunks) from the start of the result
 464      *            set (0 - based)
 465      * @param propertyPaths
 466      *            Properties to initialize in the returned entities, following
 467      *            the syntax described in
 468      *            {@link IBeanInitializer#initialize(Object, List)}
 469      * @return a Pager for all matching DescriptionElementBase instances
 470      *
 471      */
 472     public <T extends DescriptionElementBase> Pager<T>  pageDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 473
 474
 475     public DistributionTree getOrderedDistributions(Set<TaxonDescription> taxonDescriptions, Set<NamedAreaLevel> levels, List<String> propertyPaths);
 476
 477     /**
 478       * Generate a string representation of the structured <code>description</code> supplied in natural language
 479       * The <code>featureTree</code> will be used to structure the NaturalLanguageDescription.
 480       * This method does not require a initialization strategy so there is no <code>propertyPaths</code> parameter.
 481       * @param featureTree
 482       * @param description
 483       * @param preferredLanguages
 484       * @param separator
 485       * @return
 486       */
 487     public String generateNaturalLanguageDescription(FeatureTree featureTree,TaxonDescription description, List<Language> preferredLanguages, String separator);
 488
 489     /**
 490      * Preliminary method to test whether a description contains structured data.
 491      * @deprecated The means of determining this fact may change soon, so this method is
 492                     annotated as being deprecated.
 493      * @param description
 494      * @return
 495      */
 496     @Deprecated
 497     public boolean hasStructuredData(DescriptionBase<?> description);
 498
 499     /**
 500      * Add the collection of {@link DescriptionElementBase description elements} to the <code>targetDescription</code>.
 501      * Remove the description elements from the description they are currently associated with.
 502      *
 503      * @param descriptionElements
 504      * @param targetDescription
 505      * @param isPaste if true, the elements are only copied (cloned) and not removed from the
 506      *  old description
 507      */
 508     public void moveDescriptionElementsToDescription(Collection<DescriptionElementBase> descriptionElements, DescriptionBase targetDescription, boolean isPaste);
 509
 510 }