eu.etaxonomy.cdm.api.service
Interface IDescriptionService

All Superinterfaces:

IAnnotatableService<DescriptionBase>, IIdentifiableEntityService<DescriptionBase>, IService<DescriptionBase>, IVersionableService<DescriptionBase>

All Known Implementing Classes:

DescriptionServiceImpl

public interface IDescriptionService
extends IIdentifiableEntityService<DescriptionBase>

Method Summary

int	count(Class<? extends DescriptionBase> type, Boolean hasImages, Boolean hasText, Set<Feature> feature) Count the descriptions of type , filtered using the following parameters
int	countTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes) Returns count for all Media attached to a taxon via TaxonDescription.elements.media.
UUID	deleteDescriptionElement(DescriptionElementBase descriptionElement) Delete an existing description element
String	generateNaturalLanguageDescription(FeatureTree featureTree, TaxonDescription description, List<Language> preferredLanguages, String separator) Generate a string representation of the structured description supplied in natural language The featureTree will be used to structure the NaturalLanguageDescription.
TermVocabulary<Feature>	getDefaultFeatureVocabulary() Deprecated. use TermService#getVocabulary(VocabularyType) instead
Pager<Annotation>	getDescriptionElementAnnotations(DescriptionElementBase annotatedObj, MarkerType status, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType
DescriptionElementBase	getDescriptionElementByUuid(UUID uuid) Gets a DescriptionElementBase instance matching the supplied uuid
Pager<DescriptionElementBase>	getDescriptionElements(DescriptionBase description, Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths) Returns description elements of type , belonging to a given description, optionally filtered by one or more features
<T extends DescriptionElementBase> List<T>	getDescriptionElementsForTaxon(Taxon taxon, Set<Feature> features, Class<T> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths)
TermVocabulary<Feature>	getFeatureVocabulary(UUID uuid) Deprecated. use TermService#getVocabulary(VocabularyType) instead
Pager<Media>	getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths) Returns a List of Media that are associated with a given description element
DistributionTree	getOrderedDistributions(Set<TaxonDescription> taxonDescriptions, Set<NamedAreaLevel> levels, List<String> propertyPaths)
Pager<TaxonNameDescription>	getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths) Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
boolean	hasStructuredData(DescriptionBase<?> description) Deprecated. The means of determining this fact may change soon, so this method is annotated as being deprecated.
List<DescriptionElementBase>	listDescriptionElements(DescriptionBase description, Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths) Returns description elements of type , belonging to a given description, optionally filtered by one or more features
List<Media>	listTaxonDescriptionMedia(UUID taxonUuid, boolean limitToGalleries, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths) Returns all Media attached to a taxon via TaxonDescription.elements.media.
List<TaxonDescription>	listTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths)
List<TaxonDescription>	listTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths)
DescriptionElementBase	loadDescriptionElement(UUID uuid, List<String> propertyPaths) Loads and existing DescriptionElementBase instance matching the supplied uuid, and recursively initializes all bean properties given in the propertyPaths parameter.
void	moveDescriptionElementsToDescription(Collection<DescriptionElementBase> descriptionElements, DescriptionBase targetDescription, boolean isPaste) Add the collection of description elements to the targetDescription.
Pager<DescriptionBase>	page(Class<? extends DescriptionBase> type, Boolean hasMedia, Boolean hasText, Set<Feature> feature, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) List the descriptions of type , filtered using the following parameters
Pager<TaxonDescription>	pageTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths) Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
Pager<TaxonDescription>	pageTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Set<MarkerType> markerTypes, Integer pageSize, Integer pageNumber, List<String> propertyPaths) Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
Map<UUID,DescriptionElementBase>	saveDescriptionElement(Collection<DescriptionElementBase> descriptionElements) Persists a collection of DescriptionElementBase
UUID	saveDescriptionElement(DescriptionElementBase descriptionElement) Persists a DescriptionElementBase
Pager<TaxonDescription>	searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> 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.
Pager<DescriptionElementBase>	searchElements(Class<? extends DescriptionElementBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)

Methods inherited from interface eu.etaxonomy.cdm.api.service.IIdentifiableEntityService

countByTitle, countByTitle, deduplicate, find, findByTitle, findByTitle, findTitleCache, getRights, getSourcedObjectByIdInSource, getSources, getUuidAndTitleCache, listByReferenceTitle, listByTitle, replace, search, updateTitleCache, updateTitleCache

Methods inherited from interface eu.etaxonomy.cdm.api.service.IAnnotatableService

countMarkers, getAnnotations, getMarkers, groupMarkers

Methods inherited from interface eu.etaxonomy.cdm.api.service.IVersionableService

getNextAuditEvent, getPreviousAuditEvent, pageAuditEvents, pageAuditEvents

Methods inherited from interface eu.etaxonomy.cdm.api.service.IService

clear, count, delete, exists, find, find, find, findById, getSession, group, list, list, load, load, lock, merge, page, refresh, refresh, rows, save, save, saveOrUpdate, saveOrUpdate, update

Method Detail

getDefaultFeatureVocabulary

@Deprecated
TermVocabulary<Feature> getDefaultFeatureVocabulary()

Deprecated. use TermService#getVocabulary(VocabularyType) instead

Returns:

getFeatureVocabulary

@Deprecated
TermVocabulary<Feature> getFeatureVocabulary(UUID uuid)

Deprecated. use TermService#getVocabulary(VocabularyType) instead

getDescriptionElementByUuid

DescriptionElementBase getDescriptionElementByUuid(UUID uuid)

Gets a DescriptionElementBase instance matching the supplied uuid

Parameters:

uuid - the uuid of the DescriptionElement of interest

Returns:

a DescriptionElement, or null if the DescriptionElement does not exist

loadDescriptionElement

DescriptionElementBase loadDescriptionElement(UUID uuid,
                                              List<String> propertyPaths)

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: IBeanInitializer.initialize(Object, List)

Parameters:

uuid - the uuid of the DescriptionElement of interest

Returns:

a DescriptionElement, or null if the DescriptionElement does not exist

saveDescriptionElement

UUID saveDescriptionElement(DescriptionElementBase descriptionElement)

Persists a DescriptionElementBase

Parameters:

descriptionElement -

Returns:

saveDescriptionElement

Map<UUID,DescriptionElementBase> saveDescriptionElement(Collection<DescriptionElementBase> descriptionElements)

Persists a collection of DescriptionElementBase

Parameters:

descriptionElements -

Returns:

deleteDescriptionElement

UUID deleteDescriptionElement(DescriptionElementBase descriptionElement)

Delete an existing description element

Parameters:

descriptionElement - the description element to be deleted

Returns:

the unique identifier of the deleted entity

page

Pager<DescriptionBase> page(Class<? extends DescriptionBase> type,
                            Boolean hasMedia,
                            Boolean hasText,
                            Set<Feature> feature,
                            Integer pageSize,
                            Integer pageNumber,
                            List<OrderHint> orderHints,
                            List<String> propertyPaths)

List the descriptions of type , filtered using the following parameters

Parameters:

type - The type of description returned (Taxon, TaxonName, or Specimen)

hasMedia - Restrict the description to those that do (true) or don't (false) contain elements that have one or more media (can be null)

hasText - Restrict the description to those that do (true) or don't (false) contain TextData elements that have some textual content (can be null)

feature - Restrict the description to those elements which are scoped by one of the Features passed (can be null or empty)

pageSize - The maximum number of descriptions returned (can be null for all descriptions)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

orderHints - may be null

propertyPaths - properties to initialize - see IBeanInitializer.initialize(Object, List)

Returns:

a Pager containing DescriptionBase instances

count

int count(Class<? extends DescriptionBase> type,
          Boolean hasImages,
          Boolean hasText,
          Set<Feature> feature)

Count the descriptions of type , filtered using the following parameters

Parameters:

type - The type of description returned (Taxon, TaxonName, or Specimen)

hasMedia - Restrict the description to those that do (true) or don't (false) contain elements that have one or more media (can be null)

hasText - Restrict the description to those that do (true) or don't (false) contain TextData elements that have some textual content (can be null)

feature - Restrict the description to those elements which are scoped by one of the Features passed (can be null or empty)

Returns:

a count of DescriptionBase instances

getDescriptionElements

Pager<DescriptionElementBase> getDescriptionElements(DescriptionBase description,
                                                     Set<Feature> features,
                                                     Class<? extends DescriptionElementBase> type,
                                                     Integer pageSize,
                                                     Integer pageNumber,
                                                     List<String> propertyPaths)

Returns description elements of type , belonging to a given description, optionally filtered by one or more features

Parameters:

description - The description which these description elements belong to (can be null to count all description elements)

features - Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)

type - The type of description

class -

pageSize - The maximum number of description elements returned (can be null for all description elements)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

propertyPaths - Properties to initialize in the returned entities, following the syntax described in IBeanInitializer.initialize(Object, List)

Returns:

a Pager containing DescriptionElementBase instances FIXME candidate for harmonization - rename to pageDescriptionElements

listDescriptionElements

List<DescriptionElementBase> listDescriptionElements(DescriptionBase description,
                                                     Set<Feature> features,
                                                     Class<? extends DescriptionElementBase> type,
                                                     Integer pageSize,
                                                     Integer pageNumber,
                                                     List<String> propertyPaths)

Returns description elements of type , belonging to a given description, optionally filtered by one or more features

Parameters:

description - The description which these description elements belong to (can be null to count all description elements)

features - Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)

type - The type of description

class -

pageSize - The maximum number of description elements returned (can be null for all description elements)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

propertyPaths - Properties to initialize in the returned entities, following the syntax described in IBeanInitializer.initialize(Object, List)

Returns:

a List containing DescriptionElementBase instances

getDescriptionElementAnnotations

Pager<Annotation> getDescriptionElementAnnotations(DescriptionElementBase annotatedObj,
                                                   MarkerType status,
                                                   Integer pageSize,
                                                   Integer pageNumber,
                                                   List<OrderHint> orderHints,
                                                   List<String> propertyPaths)

Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType

Parameters:

annotatedObj - The object that "owns" the annotations returned

status - Only return annotations which are marked with a Marker of this type (can be null to return all annotations)

pageSize - The maximum number of terms returned (can be null for all annotations)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

orderHints - may be null

propertyPaths - properties to initialize - see IBeanInitializer.initialize(Object, List)

Returns:

a Pager of Annotation entities

pageTaxonDescriptions

Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon,
                                              Set<Scope> scopes,
                                              Set<NamedArea> geographicalScope,
                                              Integer pageSize,
                                              Integer pageNumber,
                                              List<String> propertyPaths)

Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method

Parameters:

taxon - The taxon which the description refers to (can be null for all TaxonDescription instances)

scopes - Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)

geographicalScope - Restrict the results to those descriptions which have a geographical scope that overlaps with the NamedArea instances passed (can be null or empty)

pageSize - The maximum number of descriptions returned (can be null for all descriptions)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

propertyPaths - Properties to initialize in the returned entities, following the syntax described in IBeanInitializer.initialize(Object, List)

Returns:

a Pager containing TaxonDescription instances

See Also:

#pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)

pageTaxonDescriptions

Pager<TaxonDescription> pageTaxonDescriptions(Taxon taxon,
                                              Set<Scope> scopes,
                                              Set<NamedArea> geographicalScope,
                                              Set<MarkerType> markerTypes,
                                              Integer pageSize,
                                              Integer pageNumber,
                                              List<String> propertyPaths)

Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method

Parameters:

taxon - The taxon which the description refers to (can be null for all TaxonDescription instances)

scopes - Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)

geographicalScope - Restrict the results to those descriptions which have a geographical scope that overlaps with the NamedArea instances passed (can be null or empty)

markerType - Restrict the results to those descriptions which are marked as true by one of the given marker types (can be null or empty)

pageSize - The maximum number of descriptions returned (can be null for all descriptions)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

propertyPaths - Properties to initialize in the returned entities, following the syntax described in IBeanInitializer.initialize(Object, List)

Returns:

a Pager containing TaxonDescription instances

listTaxonDescriptions

List<TaxonDescription> listTaxonDescriptions(Taxon taxon,
                                             Set<Scope> scopes,
                                             Set<NamedArea> geographicalScope,
                                             Integer pageSize,
                                             Integer pageNumber,
                                             List<String> propertyPaths)

Parameters:

taxon -

scopes -

geographicalScope -

pageSize -

pageNumber -

propertyPaths -

Returns:

See Also:

#pageTaxonDescriptions(Taxon, Set, Set, Integer, Integer, List)}

listTaxonDescriptions

List<TaxonDescription> listTaxonDescriptions(Taxon taxon,
                                             Set<Scope> scopes,
                                             Set<NamedArea> geographicalScope,
                                             Set<MarkerType> markerTypes,
                                             Integer pageSize,
                                             Integer pageNumber,
                                             List<String> propertyPaths)

Parameters:

taxon -

scopes -

geographicalScope -

pageSize -

pageNumber -

propertyPaths -

Returns:

See Also:

#pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)}

listTaxonDescriptionMedia

List<Media> listTaxonDescriptionMedia(UUID taxonUuid,
                                      boolean limitToGalleries,
                                      Set<MarkerType> markerTypes,
                                      Integer pageSize,
                                      Integer pageNumber,
                                      List<String> propertyPaths)

Returns all Media attached to a taxon via TaxonDescription.elements.media.

Parameters:

taxonUuid - the taxons uuid, if null media for all taxa are returned

limitToGalleries - if true only media in TaxonDescriptions with imageGallery flag=true are returned

markerTypes - only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient

pageSize -

pageNumber -

propertyPaths - Properties to initialize in the returned entities, following the syntax described in IBeanInitializer.initialize(Object, List)

Returns:

countTaxonDescriptionMedia

int countTaxonDescriptionMedia(UUID taxonUuid,
                               boolean limitToGalleries,
                               Set<MarkerType> markerTypes)

Returns count for all Media attached to a taxon via TaxonDescription.elements.media.

Parameters:

taxonUuid - the taxons uuid, if null media for all taxa are returned

limitToGalleries - if true only media in TaxonDescriptions with imageGallery flag=true are returned

markerTypes - only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient

Returns:

getTaxonNameDescriptions

Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name,
                                                     Integer pageSize,
                                                     Integer pageNumber,
                                                     List<String> propertyPaths)

Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to

Parameters:

name - Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)

pageSize - The maximum number of descriptions returned (can be null for all descriptions)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

propertyPaths - Properties to initialize in the returned entities, following the syntax described in IBeanInitializer.initialize(Object, List)

Returns:

a Pager containing TaxonNameBase instances FIXME candidate for harmonization - rename to pageTaxonNameDescriptions

searchDescriptionByDistribution

Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas,
                                                        PresenceAbsenceTermBase presence,
                                                        Integer pageSize,
                                                        Integer pageNumber,
                                                        List<OrderHint> orderHints,
                                                        List<String> 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)

Parameters:

namedAreas - The set of NamedArea instances

presence - Restrict the descriptions to those which have Distribution elements are of this status (can be null)

pageSize - The maximum number of descriptions returned (can be null for all descriptions)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

propertyPaths - Properties to initialize in the returned entities, following the syntax described in IBeanInitializer.initialize(Object, List)

Returns:

a Pager containing TaxonDescription instances

searchElements

Pager<DescriptionElementBase> searchElements(Class<? extends DescriptionElementBase> clazz,
                                             String queryString,
                                             Integer pageSize,
                                             Integer pageNumber,
                                             List<OrderHint> orderHints,
                                             List<String> propertyPaths)

Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)

Parameters:

clazz - filter the results by class (or pass null to return all DescriptionElementBase instances)

queryString -

pageSize - The maximum number of descriptionElements returned (can be null for all matching descriptionElements)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

orderHints - Supports path like orderHints.propertyNames which include *-to-one properties like createdBy.username or authorTeam.persistentTitleCache

propertyPaths - properties to be initialized

Returns:

a Pager DescriptionElementBase instances

See Also:

Apache Lucene - Query Parser Syntax

getMedia

Pager<Media> getMedia(DescriptionElementBase descriptionElement,
                      Integer pageSize,
                      Integer pageNumber,
                      List<String> propertyPaths)

Returns a List of Media that are associated with a given description element

Parameters:

descriptionElement - the description element associated with these media

pageSize - The maximum number of media returned (can be null for all related media)

pageNumber - The offset (in pageSize chunks) from the start of the result set (0 - based)

propertyPaths - properties to initialize - see IBeanInitializer.initialize(Object, List)

Returns:

a Pager containing media instances FIXME candidate for harmonization - rename to pageMedia

getDescriptionElementsForTaxon

<T extends DescriptionElementBase> List<T> getDescriptionElementsForTaxon(Taxon taxon,
                                                                          Set<Feature> features,
                                                                          Class<T> type,
                                                                          Integer pageSize,
                                                                          Integer pageNumber,
                                                                          List<String> propertyPaths)

getOrderedDistributions

DistributionTree getOrderedDistributions(Set<TaxonDescription> taxonDescriptions,
                                         Set<NamedAreaLevel> levels,
                                         List<String> propertyPaths)

generateNaturalLanguageDescription

String generateNaturalLanguageDescription(FeatureTree featureTree,
                                          TaxonDescription description,
                                          List<Language> preferredLanguages,
                                          String separator)

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.

Parameters:

featureTree -

description -

preferredLanguages -

separator -

Returns:

hasStructuredData

@Deprecated
boolean hasStructuredData(DescriptionBase<?> description)

Deprecated. The means of determining this fact may change soon, so this method is annotated as being deprecated.

Preliminary method to test whether a description contains structured data.

Parameters:

description -

Returns:

moveDescriptionElementsToDescription

void moveDescriptionElementsToDescription(Collection<DescriptionElementBase> descriptionElements,
                                          DescriptionBase targetDescription,
                                          boolean isPaste)

Add the collection of description elements to the targetDescription. Remove the description elements from the description they are currently associated with.

Parameters:

descriptionElements -

targetDescription -

isPaste - if true, the elements are only copied (cloned) and not removed from the old description