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