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