X-Git-Url: https://dev.e-taxonomy.eu/gitweb/cdmlib.git/blobdiff_plain/34d30384cf4127c0f0c6ec2fbbae9e4e0efd7c81..80f4156015214f4f25fe82f2c373a8d1011caa74:/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 196da82b83..aee1ee08e2 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,58 +1,287 @@ -/** -* 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.model.common.TermVocabulary; -import eu.etaxonomy.cdm.model.common.VersionableEntity; -import eu.etaxonomy.cdm.model.description.DescriptionBase; -import eu.etaxonomy.cdm.model.description.Distribution; -import eu.etaxonomy.cdm.model.description.Feature; -import eu.etaxonomy.cdm.model.description.FeatureNode; -import eu.etaxonomy.cdm.model.description.FeatureTree; - -public interface IDescriptionService extends IIdentifiableEntityService { - - /** - * @param uuid - * @return - */ - public abstract DescriptionBase getDescriptionBaseByUuid(UUID uuid); - - /** - * Persists a Description - * @param description - * @return - */ - public abstract UUID saveDescription(DescriptionBase description); - - /** - * Persists a FeatureTree - * @param tree - * @return - */ - public abstract UUID saveFeatureTree(FeatureTree tree); - public abstract void saveFeatureDataAll(Collection featureData); - public abstract Map saveFeatureTreeAll(Collection trees); - public abstract Map saveFeatureNodeAll(Collection nodes); - - public abstract List getFeatureTreesAll(); - public abstract List getFeatureNodesAll(); - - public abstract TermVocabulary getDefaultFeatureVocabulary(); - public abstract TermVocabulary getFeatureVocabulary(UUID uuid); - - public abstract String getWebServiceUrl(Set distributions, String webServiceUrl); +// $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.Annotation; +import eu.etaxonomy.cdm.model.common.Language; +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.Feature; +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.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.BeanInitializer; +import eu.etaxonomy.cdm.persistence.query.OrderHint; + +public interface IDescriptionService extends IIdentifiableEntityService { + + /** + * + * @return + * @deprecated use TermService#getVocabulary(VocabularyType) instead + */ + public TermVocabulary getDefaultFeatureVocabulary(); + + /** + * @deprecated use TermService#getVocabulary(VocabularyType) instead + */ + 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 BeanInitializer#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); + + /** + * 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 BeanInitializer#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 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 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 BeanInitializer#initialize(Object, List)} + * @return a Pager containing DescriptionElementBase instances + * + * FIXME candidate for harmonization - rename to pageDescriptionElements + */ + 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 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 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 BeanInitializer#initialize(Object, List)} + * @return a List containing DescriptionElementBase instances + */ + public List listDescriptionElements(DescriptionBase description,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 BeanInitializer#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 BeanInitializer#initialize(Object, List)} + * @return a Pager containing TaxonDescription instances + * + * FIXME candidate for harmonization - rename to pageTaxonDescriptions + */ + public Pager getTaxonDescriptions(Taxon taxon, Set scopes, Set geographicalScope, Integer pageSize, Integer pageNumber, List propertyPaths); + + /** + * @see {@link #getTaxonDescriptions(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); + + /** + * 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 BeanInitializer#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 BeanInitializer#initialize(Object, List)} + * @return a Pager containing TaxonDescription instances + */ + public Pager searchDescriptionByDistribution(Set namedAreas, PresenceAbsenceTermBase 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 BeanInitializer#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); + + public List getDescriptionElementsForTaxon(Taxon taxon, Set features, Class type, Integer pageSize, Integer pageNumber, List propertyPaths); + + public DistributionTree getOrderedDistributions(Set taxonDescriptions, Set levels, 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 + */ + public void moveDescriptionElementsToDescription(Collection descriptionElements, DescriptionBase targetDescription, boolean isPaste); } \ No newline at end of file