X-Git-Url: https://dev.e-taxonomy.eu/gitweb/cdmlib.git/blobdiff_plain/89ee59eeb6ab0f82da16f952ae108b2ce4026c0f..45546a913cf144912d383d54758aa51c81367ec9:/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IDescriptionService.java diff --git a/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IDescriptionService.java b/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IDescriptionService.java index a9b8e00616..00390d74b7 100644 --- a/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IDescriptionService.java +++ b/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IDescriptionService.java @@ -1,184 +1,605 @@ -// $Id$ -/** -* Copyright (C) 2007 EDIT -* European Distributed Institute of Taxonomy -* http://www.e-taxonomy.eu -* -* The contents of this file are subject to the Mozilla Public License Version 1.1 -* See LICENSE.TXT at the top of this package for the full license terms. -*/ - -package eu.etaxonomy.cdm.api.service; - -import java.util.Collection; -import java.util.List; -import java.util.Map; -import java.util.Set; -import java.util.UUID; - -import eu.etaxonomy.cdm.api.service.pager.Pager; -import eu.etaxonomy.cdm.model.common.TermVocabulary; -import eu.etaxonomy.cdm.model.common.VersionableEntity; -import eu.etaxonomy.cdm.model.description.DescriptionBase; -import eu.etaxonomy.cdm.model.description.DescriptionElementBase; -import eu.etaxonomy.cdm.model.description.Feature; -import eu.etaxonomy.cdm.model.description.FeatureNode; -import eu.etaxonomy.cdm.model.description.FeatureTree; -import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase; -import eu.etaxonomy.cdm.model.description.Scope; -import eu.etaxonomy.cdm.model.description.TaxonDescription; -import eu.etaxonomy.cdm.model.description.TaxonNameDescription; -import eu.etaxonomy.cdm.model.description.TextData; -import eu.etaxonomy.cdm.model.location.NamedArea; -import eu.etaxonomy.cdm.model.media.Media; -import eu.etaxonomy.cdm.model.name.TaxonNameBase; -import eu.etaxonomy.cdm.model.taxon.Taxon; - -public interface IDescriptionService extends IIdentifiableEntityService { - - /** - * @param uuid - * @return - */ - // FIXME candidate for harmonization? findByUuid - public DescriptionBase getDescriptionBaseByUuid(UUID uuid); - - /** - * Persists a Description - * @param description - * @return - */ - // FIXME candidate for harmonization? save - public UUID saveDescription(DescriptionBase description); - - /** - * Persists a FeatureTree - * @param tree - * @return - */ - public UUID saveFeatureTree(FeatureTree tree); - // FIXME could you handle the feature data elements using @Cascade? - public void saveFeatureDataAll(Collection featureData); - public Map saveFeatureTreeAll(Collection trees); - public Map saveFeatureNodeAll(Collection nodes); - - /** - * Gets a FeatureTree instance matching the supplied uuid - * - * @param uuid the uuid of the FeatureTree of interest - * @return a FeatureTree, or null if the FeatureTree does not exist - */ - public FeatureTree getFeatureTreeByUuid(UUID uuid); - - public List getFeatureTreesAll(); - public List getFeatureNodesAll(); - public List getFeaturesAll(); - - public List getFeatureTreesAll(List propertyPaths); - public List getFeatureNodesAll(List propertyPaths); - public List getFeaturesAll(List propertyPaths); - - - public TermVocabulary getDefaultFeatureVocabulary(); - //public TermVocabulary getFeatureVocabulary(); - public TermVocabulary getFeatureVocabulary(UUID uuid); - - /** - * Gets a DescriptionElementBase instance matching the supplied uuid - * - * @param uuid the uuid of the DescriptionElement of interest - * @return a DescriptionElement, or null if the DescriptionElement does not exist - */ - public DescriptionElementBase getDescriptionElementByUuid(UUID uuid); - - /** - * List the descriptions of type , filtered using the following parameters - * - * @param type The type of description returned (Taxon, TaxonName, or Specimen) - * @param hasMedia Restrict the description to those that do (true) or don't (false) contain elements that have one or more media (can be null) - * @param hasText Restrict the description to those that do (true) or don't (false) contain TextData elements that have some textual content (can be null) - * @param feature Restrict the description to those elements which are scoped by one of the Features passed (can be null or empty) - * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) - * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) - * @return a Pager containing DescriptionBase instances - */ - public Pager listDescriptions(Class type, Boolean hasMedia, Boolean hasText, Set feature, Integer pageSize, Integer pageNumber); - - /** - * Count the descriptions of type , filtered using the following parameters - * - * @param type The type of description returned (Taxon, TaxonName, or Specimen) - * @param hasMedia Restrict the description to those that do (true) or don't (false) contain elements that have one or more media (can be null) - * @param hasText Restrict the description to those that do (true) or don't (false) contain TextData elements that have some textual content (can be null) - * @param feature Restrict the description to those elements which are scoped by one of the Features passed (can be null or empty) - * @return a count of DescriptionBase instances - */ - public int countDescriptions(Class type, Boolean hasImages, Boolean hasText, Set feature); - - /** - * Returns description elements of type , belonging to a given description, optionally filtered by one or more features - * - * @param description The description which these description elements belong to (can be null to count all description elements) - * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty) - * @param type The type of description - * @param pageSize The maximum number of description elements returned (can be null for all description elements) - * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) - * @return a Pager containing DescriptionElementBase instances - */ - public Pager getDescriptionElements(DescriptionBase description,Set features, Class type, Integer pageSize, Integer pageNumber); - - /** - * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method - * - * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances) - * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty) - * @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) - * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) - * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) - * @return a Pager containing TaxonDescription instances - */ - public Pager getTaxonDescriptions(Taxon taxon, Set scopes, Set geographicalScope, Integer pageSize, Integer pageNumber); - - /** - * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to - * - * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances) - * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) - * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) - * @return a Pager containing TaxonNameBase instances - */ - public Pager getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber); - - /** - * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally - * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc) - * - * @param namedAreas The set of NamedArea instances - * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null) - * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) - * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) - * @return a Pager containing TaxonDescription instances - */ - public Pager searchDescriptionByDistribution(Set namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber); - - /** - * Returns a List of TextData elements that match a given queryString provided. - * - * @param queryString - * @param pageSize - * @param pageNumber - * @return - * @throws QueryParseException - */ - public Pager searchTextData(String queryString, Integer pageSize, Integer pageNumber); - - /** - * Returns a List of Media that are associated with a given description element - * - * @param descriptionElement the description element associated with these media - * @param pageSize The maximum number of media returned (can be null for all related media) - * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) - * @return a Pager containing media instances - */ - public Pager getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber); +// $Id$ +/** +* Copyright (C) 2007 EDIT +* European Distributed Institute of Taxonomy +* http://www.e-taxonomy.eu +* +* The contents of this file are subject to the Mozilla Public License Version 1.1 +* See LICENSE.TXT at the top of this package for the full license terms. +*/ + +package eu.etaxonomy.cdm.api.service; + +import java.util.Collection; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.UUID; + +import eu.etaxonomy.cdm.api.service.pager.Pager; +import eu.etaxonomy.cdm.api.utility.DescriptionUtility; +import eu.etaxonomy.cdm.model.common.Annotation; +import eu.etaxonomy.cdm.model.common.DefinedTerm; +import eu.etaxonomy.cdm.model.common.Language; +import eu.etaxonomy.cdm.model.common.Marker; +import eu.etaxonomy.cdm.model.common.MarkerType; +import eu.etaxonomy.cdm.model.common.TermVocabulary; +import eu.etaxonomy.cdm.model.description.DescriptionBase; +import eu.etaxonomy.cdm.model.description.DescriptionElementBase; +import eu.etaxonomy.cdm.model.description.Distribution; +import eu.etaxonomy.cdm.model.description.Feature; +import eu.etaxonomy.cdm.model.description.FeatureTree; +import eu.etaxonomy.cdm.model.description.PresenceAbsenceTerm; +import eu.etaxonomy.cdm.model.description.TaxonDescription; +import eu.etaxonomy.cdm.model.description.TaxonNameDescription; +import eu.etaxonomy.cdm.model.location.NamedArea; +import eu.etaxonomy.cdm.model.location.NamedAreaLevel; +import eu.etaxonomy.cdm.model.media.Media; +import eu.etaxonomy.cdm.model.name.TaxonNameBase; +import eu.etaxonomy.cdm.model.taxon.Taxon; +import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer; +import eu.etaxonomy.cdm.persistence.dto.TermDto; +import eu.etaxonomy.cdm.persistence.query.OrderHint; + +public interface IDescriptionService extends IIdentifiableEntityService { + + /** + * + * @return + * @deprecated use TermService#getVocabulary(VocabularyType) instead + */ + @Deprecated + public TermVocabulary getDefaultFeatureVocabulary(); + + /** + * @deprecated use TermService#getVocabulary(VocabularyType) instead + */ + @Deprecated + public TermVocabulary getFeatureVocabulary(UUID uuid); + + /** + * Gets a DescriptionElementBase instance matching the supplied uuid + * + * @param uuid the uuid of the DescriptionElement of interest + * @return a DescriptionElement, or null if the DescriptionElement does not exist + */ + public DescriptionElementBase getDescriptionElementByUuid(UUID uuid); + + /** + * Loads and existing DescriptionElementBase instance matching the supplied uuid, + * and recursively initializes all bean properties given in the + * propertyPaths parameter. + *

+ * For detailed description and examples please refer to: + * {@link IBeanInitializer#initialize(Object, List)} + * + * @param uuid the uuid of the DescriptionElement of interest + * @return a DescriptionElement, or null if the DescriptionElement does not exist + */ + public DescriptionElementBase loadDescriptionElement(UUID uuid,List propertyPaths); + + /** + * Persists a DescriptionElementBase + * @param descriptionElement + * @return + */ + public UUID saveDescriptionElement(DescriptionElementBase descriptionElement); + + /** + * Persists a collection of DescriptionElementBase + * @param descriptionElements + * @return + */ + public Map saveDescriptionElement(Collection descriptionElements); + + /** + * Delete an existing description element + * + * @param descriptionElement the description element to be deleted + * @return the unique identifier of the deleted entity + */ + public UUID deleteDescriptionElement(DescriptionElementBase descriptionElement); + + public UUID deleteDescriptionElement(UUID descriptionElementUuid); + + /** + * List the descriptions of type , filtered using the following parameters + * + * @param type The type of description returned (Taxon, TaxonName, or Specimen) + * @param hasMedia Restrict the description to those that do (true) or don't (false) contain elements that have one or more media (can be null) + * @param hasText Restrict the description to those that do (true) or don't (false) contain TextData elements that have some textual content (can be null) + * @param feature Restrict the description to those elements which are scoped by one of the Features passed (can be null or empty) + * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param orderHints may be null + * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager containing DescriptionBase instances + */ + public Pager page(Class type, Boolean hasMedia, Boolean hasText, Set feature, Integer pageSize, Integer pageNumber, List orderHints, List propertyPaths); + + /** + * Count the descriptions of type , filtered using the following parameters + * + * @param type The type of description returned (Taxon, TaxonName, or Specimen) + * @param hasMedia Restrict the description to those that do (true) or don't (false) contain elements that have one or more media (can be null) + * @param hasText Restrict the description to those that do (true) or don't (false) contain TextData elements that have some textual content (can be null) + * @param feature Restrict the description to those elements which are scoped by one of the Features passed (can be null or empty) + * @return a count of DescriptionBase instances + */ + public int count(Class type, Boolean hasImages, Boolean hasText, Set feature); + + /** + * Returns description elements of type , belonging to a given + * description, optionally filtered by one or more features + * + * @param description + * The description which these description elements belong to + * (can be null to count all description elements) + * @param descriptionType + * A filter DescriptionElements which belong to of a specific + * class of Descriptions + * @param features + * Restrict the results to those description elements which are + * scoped by one of the Features passed (can be null or empty) + * @param type + * A filter for DescriptionElements of a specific class + * @param pageSize + * The maximum number of description elements returned (can be + * null for all description elements) + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based) + * @param propertyPaths + * Properties to initialize in the returned entities, following + * the syntax described in + * {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager containing DescriptionElementBase instances + + * @deprecated use + * {@link #pageDescriptionElements(DescriptionBase, Set, Class, Integer, Integer, List)} + * instead + */ + @Deprecated + public Pager getDescriptionElements(DescriptionBase description,Set features, Class type, Integer pageSize, Integer pageNumber, List propertyPaths); + + + /** + * Returns description elements of type , belonging to a given + * description, optionally filtered by one or more features + * + * @param description + * The description which these description elements belong to + * (can be null to count all description elements) + * @param descriptionType + * A filter DescriptionElements which belong to of a specific + * class of Descriptions + * @param features + * Restrict the results to those description elements which are + * scoped by one of the Features passed (can be null or empty) + * @param type + * A filter for DescriptionElements of a specific class + * @param pageSize + * The maximum number of description elements returned (can be + * null for all description elements) + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based) + * @param propertyPaths + * Properties to initialize in the returned entities, following + * the syntax described in + * {@link IBeanInitializer#initialize(Object, List)} + * + * @return a Pager containing DescriptionElementBase instances + */ + public Pager pageDescriptionElements(DescriptionBase description, Class descriptionType, Set features, Class type, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Returns description elements of type , belonging to a given + * description, optionally filtered by one or more features + * + * @param description + * The description which these description elements belong to + * (can be null to count all description elements) + * @param features + * Restrict the results to those description elements which are + * scoped by one of the Features passed (can be null or empty) + * @param type + * A filter for DescriptionElements of a specific class + * @param pageSize + * The maximum number of description elements returned (can be + * null for all description elements) + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based) + * @param propertyPaths + * Properties to initialize in the returned entities, following + * the syntax described in + * {@link IBeanInitializer#initialize(Object, List)} + * @return a List of DescriptionElementBase instances + * @deprecated use {@link #listDescriptionElements(DescriptionBase, Class, Set, Class, Integer, Integer, List)} instead + */ + @Deprecated + public List listDescriptionElements(DescriptionBase description,Set features, Class type, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Returns description elements of type , belonging to a given + * description, optionally filtered by one or more features + * + * @param description + * The description which these description elements belong to + * (can be null to count all description elements) + * @param features + * Restrict the results to those description elements which are + * scoped by one of the Features passed (can be null or empty) + * @param type + * A filter DescriptionElements of a for specific class + * @param pageSize + * The maximum number of description elements returned (can be + * null for all description elements) + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based) + * @param propertyPaths + * Properties to initialize in the returned entities, following + * the syntax described in + * {@link IBeanInitializer#initialize(Object, List)} + * @return a List of DescriptionElementBase instances + */ + public List listDescriptionElements(DescriptionBase description, Class descriptionType, Set features, Class type, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType + * @param annotatedObj The object that "owns" the annotations returned + * @param status Only return annotations which are marked with a Marker of this type (can be null to return all annotations) + * @param pageSize The maximum number of terms returned (can be null for all annotations) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param orderHints may be null + * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager of Annotation entities + */ + public Pager getDescriptionElementAnnotations(DescriptionElementBase annotatedObj, MarkerType status, Integer pageSize, Integer pageNumber, List orderHints, List propertyPaths); + + + /** + * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method + * + * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances) + * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty) + * @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) + * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager containing TaxonDescription instances + * + * @see #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List) + */ + public Pager pageTaxonDescriptions(Taxon taxon, Set scopes, Set geographicalScope, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method + * + * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances) + * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty) + * @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) + * @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) + * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager containing TaxonDescription instances + */ + public Pager pageTaxonDescriptions(Taxon taxon, Set scopes, Set geographicalScope, Set markerTypes, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * @see {@link #pageTaxonDescriptions(Taxon, Set, Set, Integer, Integer, List)} + * + * @param taxon + * @param scopes + * @param geographicalScope + * @param pageSize + * @param pageNumber + * @param propertyPaths + * @return + */ + public List listTaxonDescriptions(Taxon taxon, Set scopes, Set geographicalScope, Integer pageSize, Integer pageNumber, List propertyPaths); + + + + /** + * @see {@link #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)} + * + * @param taxon + * @param scopes + * @param geographicalScope + * @param pageSize + * @param pageNumber + * @param propertyPaths + * @return + */ + public List listTaxonDescriptions(Taxon taxon, Set scopes, Set geographicalScope, Set markerTypes, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Returns all {@link Media} attached to a taxon via TaxonDescription.elements.media. + * @param taxonUuid the taxons uuid, if null media for all taxa are returned + * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned + * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient + * @param pageSize + * @param pageNumber + * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)} + * @return + */ + public List listTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set markerTypes, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Returns count for all {@link Media} attached to a taxon via TaxonDescription.elements.media. + * @param taxonUuid the taxons uuid, if null media for all taxa are returned + * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned + * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient + * @return + */ + public int countTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set markerTypes); + + + + /** + * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to + * + * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances) + * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager containing TaxonNameBase instances + * + * FIXME candidate for harmonization - rename to pageTaxonNameDescriptions + */ + public Pager getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List propertyPaths); + + + /** + * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally + * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc) + * + * @param namedAreas The set of NamedArea instances + * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null) + * @param pageSize The maximum number of descriptions returned (can be null for all descriptions) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager containing TaxonDescription instances + */ + public Pager searchDescriptionByDistribution(Set namedAreas, PresenceAbsenceTerm presence, Integer pageSize, Integer pageNumber, List orderHints, List propertyPaths); + + /** + * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser) + * + * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances) + * @param queryString + * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param orderHints + * Supports path like orderHints.propertyNames which + * include *-to-one properties like createdBy.username or + * authorTeam.persistentTitleCache + * @param propertyPaths properties to be initialized + * @return a Pager DescriptionElementBase instances + * @see Apache Lucene - Query Parser Syntax + */ + public Pager searchElements(Class clazz, String queryString, Integer pageSize, Integer pageNumber, List orderHints, List propertyPaths); + + /** + * Returns a List of Media that are associated with a given description element + * + * @param descriptionElement the description element associated with these media + * @param pageSize The maximum number of media returned (can be null for all related media) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager containing media instances + * + * FIXME candidate for harmonization - rename to pageMedia + */ + public Pager getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Provides access to all DescriptionElements associated with the given Taxon + * via a TaxonDescrition. + * + * @param taxon + * The Taxon to return Description elements for + * @param features + * Restrict the results to those description elements which are + * scoped by one of the Features passed (can be null or empty) + * @param type + * A filter for DescriptionElements of a specific class + * @param pageSize + * The maximum number of description elements returned (can be + * null for all description elements) + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based) + * @param propertyPaths + * Properties to initialize in the returned entities, following + * the syntax described in + * {@link IBeanInitializer#initialize(Object, List)} + * @return a List containing all matching DescriptionElementBase instances + * + * @deprecated use {@link #listDescriptionElementsForTaxon(Taxon, Set, Class, Integer, Integer, List)} instead + */ + @Deprecated + public List getDescriptionElementsForTaxon(Taxon taxon, Set features, Class type, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Provides access to all DescriptionElements associated with the given Taxon + * via a TaxonDescrition. + * + * @param taxon + * The Taxon to return Description elements for + * @param features + * Restrict the results to those description elements which are + * scoped by one of the Features passed (can be null or empty) + * @param type + * A filter for DescriptionElements of a specific class + * @param pageSize + * The maximum number of description elements returned (can be + * null for all description elements) + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based) + * @param propertyPaths + * Properties to initialize in the returned entities, following + * the syntax described in + * {@link IBeanInitializer#initialize(Object, List)} + * @return a List containing all matching DescriptionElementBase instances + * + */ + public List listDescriptionElementsForTaxon(Taxon taxon, Set features, Class type, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * Provides access to all DescriptionElements associated with the given Taxon + * via a TaxonDescrition. + * + * @param taxon + * The Taxon to return Description elements for + * @param features + * Restrict the results to those description elements which are + * scoped by one of the Features passed (can be null or empty) + * @param type + * A filter for DescriptionElements of a specific class + * @param pageSize + * The maximum number of description elements returned + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based) + * @param propertyPaths + * Properties to initialize in the returned entities, following + * the syntax described in + * {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager for all matching DescriptionElementBase instances + * + */ + public Pager pageDescriptionElementsForTaxon(Taxon taxon, Set features, Class type, Integer pageSize, Integer pageNumber, List propertyPaths); + + + /** + * @param taxonDescriptions + * @param subAreaPreference + * enables the Sub area preference rule if set to true, + * see {@link DescriptionUtility#filterDistributions(Collection, + * boolean, boolean} + + * @param statusOrderPreference + * enables the Status order preference rule if set to + * true, see {@link + * DescriptionUtility#filterDistributions(Collection, boolean, + * boolean} + * @param hideMarkedAreas + * distributions where the area has a {@link Marker} with one of + * the specified {@link MarkerType}s will be skipped, see + * {@link DescriptionUtility#filterDistributions(Collection, boolean, boolean, Set)} + * @param omitLevels + * A Set NamedArea levels to omit - optional + * @param propertyPaths + * the initialization strategy + * + * @return + * @deprecated use {@link IEditGeoService#composeDistributionInfoFor()} instead + */ + @Deprecated + public DistributionTree getOrderedDistributions( + Set taxonDescriptions, + boolean subAreaPreference, + boolean statusOrderPreference, + Set hideMarkedAreas, + Set omitLevels, List propertyPaths); + + /** + * Generate a string representation of the structured description supplied in natural language + * The featureTree will be used to structure the NaturalLanguageDescription. + * This method does not require a initialization strategy so there is no propertyPaths parameter. + * @param featureTree + * @param description + * @param preferredLanguages + * @param separator + * @return + */ + public String generateNaturalLanguageDescription(FeatureTree featureTree,TaxonDescription description, List preferredLanguages, String separator); + + /** + * Preliminary method to test whether a description contains structured data. + * @deprecated The means of determining this fact may change soon, so this method is + annotated as being deprecated. + * @param description + * @return + */ + @Deprecated + public boolean hasStructuredData(DescriptionBase description); + + /** + * Add the collection of {@link DescriptionElementBase description elements} to the targetDescription. + * Remove the description elements from the description they are currently associated with. + * + * @param descriptionElements + * @param targetDescription + * @param isPaste if true, the elements are only copied (cloned) and not removed from the + * old description + * @return + */ + public UpdateResult moveDescriptionElementsToDescription(Collection descriptionElements, DescriptionBase targetDescription, boolean isPaste); + + /** + * Pager method to get all {@link NamedAreas} instances which are currently used + * by {@link Distribution} elements. + * + * @param pageSize + * The maximum number of description elements returned + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based) + * @param propertyPaths + * Properties to initialize in the returned entities, following + * the syntax described in + * {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager for all NamedAreas instances which are currently in use. + * + */ + public Pager pageNamedAreasInUse(boolean includeAllParents, Integer pageSize, + Integer pageNumber); + + public DeleteResult deleteDescription(DescriptionBase description); + + public DeleteResult deleteDescription(UUID descriptionUuid); + + /** + * @param sourceTaxon + * @param targetTaxon + * @return + */ + public UpdateResult moveTaxonDescriptions(Taxon sourceTaxon, Taxon targetTaxon); + + /** + * @param sourceTaxonUuid + * @param targetTaxonUuid + * @return + */ + public UpdateResult moveTaxonDescriptions(UUID sourceTaxonUuid, UUID targetTaxonUuid); + + + /** + * @param descriptionElementUUIDs + * @param targetDescriptionUuid + * @param isCopy + * @return + */ + public UpdateResult moveDescriptionElementsToDescription(Set descriptionElementUUIDs, UUID targetDescriptionUuid, + boolean isCopy); + + /** + * @param descriptionElementUUIDs + * @param targetTaxonUuid + * @param moveMessage + * @param isCopy + * @return + */ + public UpdateResult moveDescriptionElementsToDescription(Set descriptionElementUUIDs, UUID targetTaxonUuid, + String moveMessage, boolean isCopy); + + } \ No newline at end of file