X-Git-Url: https://dev.e-taxonomy.eu/gitweb/cdmlib.git/blobdiff_plain/548e618eecb6d79074702b74a6ab9ccef53c841d..4c525123433fbc5a7d36e2445302650bddc39307:/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IClassificationService.java diff --git a/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IClassificationService.java b/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IClassificationService.java index 0bdc9d7c4a..2ce702aee9 100644 --- a/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IClassificationService.java +++ b/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IClassificationService.java @@ -1,4 +1,3 @@ -// $Id$ /** * Copyright (C) 2007 EDIT * European Distributed Institute of Taxonomy @@ -18,7 +17,12 @@ import java.util.UUID; import eu.etaxonomy.cdm.api.service.config.CreateHierarchyForClassificationConfigurator; import eu.etaxonomy.cdm.api.service.config.TaxonDeletionConfigurator; import eu.etaxonomy.cdm.api.service.dto.GroupedTaxonDTO; +import eu.etaxonomy.cdm.api.service.dto.TaxonInContextDTO; import eu.etaxonomy.cdm.api.service.pager.Pager; +import eu.etaxonomy.cdm.compare.taxon.TaxonNodeSortMode; +import eu.etaxonomy.cdm.exception.FilterException; +import eu.etaxonomy.cdm.exception.UnpublishedException; +import eu.etaxonomy.cdm.model.common.MarkerType; import eu.etaxonomy.cdm.model.media.MediaRepresentation; import eu.etaxonomy.cdm.model.name.Rank; import eu.etaxonomy.cdm.model.taxon.Classification; @@ -26,46 +30,28 @@ import eu.etaxonomy.cdm.model.taxon.ITaxonTreeNode; import eu.etaxonomy.cdm.model.taxon.Taxon; import eu.etaxonomy.cdm.model.taxon.TaxonNode; import eu.etaxonomy.cdm.persistence.dto.ClassificationLookupDTO; +import eu.etaxonomy.cdm.persistence.dto.TaxonNodeDto; import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache; import eu.etaxonomy.cdm.persistence.query.OrderHint; /** * @author n.hoffmann - * @created Sep 21, 2009 + * @since Sep 21, 2009 */ public interface IClassificationService extends IIdentifiableEntityService { - /** - * - * @param uuid - * @return - */ - public TaxonNode getTaxonNodeByUuid(UUID uuid); - - /** - * - * @param uuid - * @return - */ public ITaxonTreeNode getTreeNodeByUuid(UUID uuid); - + /** - * * Returns the root node of the the given classification (specified by its UUID) * @param classificationUuid the uuid of the classification * @return the root node of the classification */ public TaxonNode getRootNode(UUID classificationUuid); - /** - * - * @param limit - * @param start - * @param orderHints - * @param propertyPaths - * @return - */ + public UUID getTaxonNodeUuidByTaxonUuid(UUID classificationUuid, UUID taxonUuid); + public List listClassifications(Integer limit, Integer start, List orderHints, List propertyPaths); /** @@ -81,14 +67,28 @@ public interface IClassificationService extends IIdentifiableEntityService propertyPaths); /** + * Loads all TaxonNodes of the specified classification for a given Rank or lower. + * If a branch of the classification tree is not containing a TaxonNode with a Taxon at the given + * Rank the according node associated with the next lower Rank is taken as root node in this case. + * So the nodes returned may reference Taxa with different Ranks. * - * @param taxonNode + * If the rank is null the absolute root nodes will be returned. + + * @param classification may be null for all classifications + * @param subtree filter on a taxonomic subtree + * @param rank the set to null for to get the root nodes of classifications + * @param includeUnpublished if true unpublished taxa are also exported + * @param pageSize The maximum number of relationships returned (can be null for all relationships) + * @param pageIndex The offset (in pageSize chunks) from the start of the result set (0 - based) * @param propertyPaths * @return - * @deprecated use TaxonNodeService instead + * @see #pageRankSpecificRootNodes(Classification, TaxonNode, Rank, boolean, Integer, Integer, List) + * @deprecated use according DTO method instead */ @Deprecated - public TaxonNode loadTaxonNode(TaxonNode taxonNode, List propertyPaths); + public List listRankSpecificRootNodes(Classification classification, TaxonNode subtree, + Rank rank, boolean includeUnpublished, Integer pageSize, Integer pageIndex, + List propertyPaths); /** * Loads all TaxonNodes of the specified classification for a given Rank or lower. @@ -97,16 +97,21 @@ public interface IClassificationService extends IIdentifiableEntityServicerank is null the absolute root nodes will be returned. - * + * @param classification may be null for all classifications + * @param subtree filter on a taxonomic subtree * @param rank the set to null for to get the root nodes of classifications + * @param includeUnpublished if true unpublished taxa are also exported * @param pageSize The maximum number of relationships returned (can be null for all relationships) * @param pageIndex The offset (in pageSize chunks) from the start of the result set (0 - based) * @param propertyPaths * @return + * @see #pageRankSpecificRootNodes(Classification, TaxonNode, Rank, boolean, Integer, Integer, List) * */ - public List listRankSpecificRootNodes(Classification classification, Rank rank, Integer pageSize, Integer pageIndex, List propertyPaths); + public List listRankSpecificRootNodeDtos(Classification classification, TaxonNode subtree, + Rank rank, boolean includeUnpublished, Integer pageSize, Integer pageIndex, TaxonNodeDtoSortMode sortMode, + List propertyPaths); /** @@ -118,14 +123,27 @@ public interface IClassificationService extends IIdentifiableEntityServicerank is null the absolute root nodes will be returned. * * @param classification may be null for all classifications + * @param subtree the taxonomic subtree filter * @param rank the set to null for to get the root nodes of classifications + * @param includeUnpublished if true unpublished taxa are also exported * @param pageSize The maximum number of relationships returned (can be null for all relationships) * @param pageIndex The offset (in pageSize chunks) from the start of the result set (0 - based) * @param propertyPaths * @return * + * @see #listRankSpecificRootNodes(Classification, TaxonNode, Rank, boolean, Integer, Integer, List) */ - public Pager pageRankSpecificRootNodes(Classification classification, Rank rank, Integer pageSize, Integer pageIndex, List propertyPaths); + public Pager pageRankSpecificRootNodes(Classification classification, TaxonNode subtree, + Rank rank, boolean includeUnpublished, Integer pageSize, Integer pageIndex, + List propertyPaths); + /** + * @see #pageRankSpecificRootNodes(Classification, TaxonNode, Rank, boolean, Integer, Integer, List) + * @deprecated keep this for compatibility to older versions, might be removed in versions >5.3 + */ + @Deprecated + public Pager pageRankSpecificRootNodes(Classification classification, + Rank rank, boolean includeUnpublished, Integer pageSize, Integer pageIndex, + List propertyPaths); /** * @param taxonNode @@ -137,10 +155,18 @@ public interface IClassificationService extends IIdentifiableEntityServicetrue no {@link UnpublishedException} + * is thrown if any of the taxa in the branch are unpublished * @return the path of nodes from the base node to the node of the - * specified taxon. + * specified taxon. + * @throws UnpublishedException + * if any of the taxa in the path is unpublished an {@link UnpublishedException} is thrown. */ - public List loadTreeBranch(TaxonNode taxonNode, Rank baseRank, List propertyPaths); + public List loadTreeBranch(TaxonNode taxonNode, TaxonNode subtree, Rank baseRank, boolean includeUnpublished, + List propertyPaths) throws UnpublishedException; + public List loadTreeBranch(TaxonNode taxonNode, Rank baseRank, boolean includeUnpublished, + List propertyPaths) throws UnpublishedException; /** * Although this method seems to be a redundant alternative to {@link #loadChildNodesOfTaxonNode(TaxonNode, List)} it is an important @@ -155,23 +181,61 @@ public interface IClassificationService extends IIdentifiableEntityServicebase node. + * @param includeUnpublished + * if true no {@link UnpublishedException} + * is thrown if any of the taxa in the branch are unpublished * @param propertyPaths * the initialization strategy for the returned TaxonNode * instances. * @return the path of nodes from the base node to the node of the specified - * taxon. + * taxon. + * @throws UnpublishedException + * if any of the taxa in the path is unpublished an {@link UnpublishedException} is thrown */ - public List loadTreeBranchToTaxon(Taxon taxon, Classification classification, Rank baseRank, List propertyPaths); - - + public List loadTreeBranchToTaxon(Taxon taxon, Classification classification, + TaxonNode subtree, Rank baseRank, + boolean includeUnpublished, List propertyPaths) throws UnpublishedException; /** - * @param taxonUuid - * @param classificationUuid + * Although this method seems to be a redundant alternative to {@link #loadChildNodesOfTaxonNode(TaxonNode, List)} it is an important + * alternative from which web services benefit. Without this method the web service controller method, which operates outside of the + * transaction, would have to initialize the full taxon tree with all nodes of the taxon. + * This would be rather slow compared to using this method. + * @param taxon + * @param classification + * the classification to be used + * @param baseRank + * specifies the root level of the classification, may be null. + * Nodes of this rank or in case this rank does not exist in the + * current branch the next lower rank is taken as as root node for + * this rank henceforth called the base node. + * @param includeUnpublished + * if true no {@link UnpublishedException} + * is thrown if any of the taxa in the branch are unpublished * @param propertyPaths - * @return + * the initialization strategy for the returned TaxonNode + * instances. + * @return the path of nodes from the base node to the node of the specified + * taxon. + * @throws UnpublishedException + * if any of the taxa in the path is unpublished an {@link UnpublishedException} is thrown */ - public List listChildNodesOfTaxon(UUID taxonUuid, UUID classificationUuid, Integer pageSize, Integer pageIndex, List propertyPaths); + public List loadTreeBranchDTOsToTaxon(Taxon taxon, Classification classification, + TaxonNode subtree, Rank baseRank, + boolean includeUnpublished, List propertyPaths) throws UnpublishedException; + + public List loadTreeBranchToTaxon(Taxon taxon, Classification classification, + Rank baseRank, + boolean includeUnpublished, List propertyPaths) throws UnpublishedException; + + public List listChildNodesOfTaxon(UUID taxonUuid, UUID classificationUuid, boolean includeUnpublished, + Integer pageSize, Integer pageIndex, List propertyPaths); + + public List listChildNodesOfTaxon(UUID taxonUuid, UUID classificationUuid, UUID subtreeUuid, boolean includeUnpublished, + Integer pageSize, Integer pageIndex, List propertyPaths) throws FilterException; + + public List listChildNodeDtosOfTaxon(UUID taxonUuid, UUID classificationUuid, UUID subtreeUuid, boolean includeUnpublished, + Integer pageSize, Integer pageIndex, TaxonNodeDtoSortMode comparator) throws FilterException; /** * @param taxonNode @@ -182,61 +246,12 @@ public interface IClassificationService extends IIdentifiableEntityService loadChildNodesOfTaxonNode(TaxonNode taxonNode, List propertyPaths); - /** - * - * @param classification - * @return - */ - public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(Classification classification, List excludeTaxa); - - /** - * @param taxon - * @param taxTree - * @param propertyPaths - * @param size - * @param height - * @param widthOrDuration - * @param mimeTypes - * @return - * - * @deprecated use getAllMediaForChildNodes(TaxonNode taxonNode, ...) instead - * if you have a classification and a taxon that is in it, you should also have the according taxonNode - */ - @Deprecated - public Map> getAllMediaForChildNodes(Taxon taxon, Classification taxTree, List propertyPaths, int size, int height, int widthOrDuration, String[] mimeTypes); + public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(Classification classification); - /** - * - * @param taxonNode - * @param propertyPaths - * @param size - * @param height - * @param widthOrDuration - * @param mimeTypes - * @return - */ + //FIXME seems not to be used anymore public Map> getAllMediaForChildNodes(TaxonNode taxonNode, List propertyPaths, int size, int height, int widthOrDuration, String[] mimeTypes); /** - * - * @param taxonNode - * @return - * @deprecated use TaxonNodeService instead - */ - @Deprecated - public UUID removeTaxonNode(TaxonNode taxonNode); - - /** - * - * @param taxonNode - * @return - * @deprecated use TaxonNodeService instead - */ - @Deprecated - public UUID saveTaxonNode(TaxonNode taxonNode); - - /** - * * @param taxonNodeCollection * @return * @deprecated use TaxonNodeService instead @@ -244,95 +259,67 @@ public interface IClassificationService extends IIdentifiableEntityService saveTaxonNodeAll(Collection taxonNodeCollection); - /** - * - * @param treeNode - * @return - */ - public UUID removeTreeNode(ITaxonTreeNode treeNode); - /** - * - * @param treeNode - * @return - */ public UUID saveTreeNode(ITaxonTreeNode treeNode); - public List getAllNodes(); public UpdateResult createHierarchyInClassification(Classification classification, CreateHierarchyForClassificationConfigurator configurator); - /** - * @param classificationUuid - * @param excludeTaxa - * @return - */ - public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(UUID classificationUuid, List excludeTaxa); + public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(UUID classificationUuid); - /** - * @param classificationUuid - * @param excludeTaxa - * @param limit - * @param pattern - * @return - */ - List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( - UUID classificationUuid, List excludeTaxa, Integer limit, String pattern); + public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( + UUID classificationUuid, Integer limit, String pattern); - /** - * @param classification - * @param excludeTaxa - * @param limit - * @param pattern - * @return - */ - List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( - Classification classification, List excludeTaxa, Integer limit, String pattern); + public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( + Classification classification, Integer limit, String pattern); - /** - * @param taxonUuid - * @param classificationUuid - * @param pageSize - * @param pageIndex - * @param propertyPaths - * @return - */ - List listSiblingsOfTaxon(UUID taxonUuid, UUID classificationUuid, Integer pageSize, Integer pageIndex, - List propertyPaths); + public List listSiblingsOfTaxon(UUID taxonUuid, UUID classificationUuid, boolean includeUnpublished, + Integer pageSize, Integer pageIndex, List propertyPaths); - /** - * @param taxonUuid - * @param classificationUuid - * @param pageSize - * @param pageIndex - * @param propertyPaths - * @return - */ - Pager pageSiblingsOfTaxon(UUID taxonUuid, UUID classificationUuid, Integer pageSize, Integer pageIndex, + public Pager pageSiblingsOfTaxon(UUID taxonUuid, UUID classificationUuid, boolean includeUnpublished, Integer pageSize, Integer pageIndex, List propertyPaths); - /** - * @param classification - * @return - */ - ClassificationLookupDTO classificationLookup(Classification classification); + public ClassificationLookupDTO classificationLookup(Classification classification); - DeleteResult delete(UUID classificationUuid, TaxonDeletionConfigurator config); + public DeleteResult delete(UUID classificationUuid, TaxonDeletionConfigurator config); /** * Returns the higher taxon id for each taxon in taxonUuids. * The highter taxon is defined by rank where the lowest rank equal or above minRank * is taken. If maxRank <> null and no taxon exists with minRank <= rank <= maxRank * no higher taxon is returned for this taxon. - * - * @param taxonUuids - * @param minRank - * @param maxRank - * @return */ - List groupTaxaByHigherTaxon(List taxonUuids, UUID classificationUuid, Rank minRank, Rank maxRank); + public List groupTaxaByHigherTaxon(List taxonUuids, UUID classificationUuid, Rank minRank, Rank maxRank); + + public List groupTaxaByMarkedParents(List taxonUuids, UUID classificationUuid, + MarkerType markerType, Boolean value); + + /** + * Returns the most relevant data of a taxon/taxon node, including children, synonyms + * and certain ancestors if required. + */ + public TaxonInContextDTO getTaxonInContext(UUID classificationUuid, UUID taxonUuid, + Boolean doChildren, Boolean doSynonyms, boolean includeUnpublished, List ancestorMarkers, + TaxonNodeSortMode sortMode); + + public UUID saveClassification(Classification classification); + + public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( + UUID classificationUuid, Integer limit, String pattern, boolean searchForClassifications); + public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( + Classification classification, Integer limit, String pattern, boolean searchForClassifications); + + public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( + UUID classificationUuid, boolean searchForClassifications); + + public List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( + Classification classification, boolean searchForClassifications); + + List> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification( + UUID classificationUuid, Integer limit, String pattern, boolean searchForClassifications, + boolean includeDoubtful); }