cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IClassificationService.java

   1 /**
   2 * Copyright (C) 2007 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9
  10 package eu.etaxonomy.cdm.api.service;
  11
  12 import java.util.Collection;
  13 import java.util.List;
  14 import java.util.Map;
  15 import java.util.UUID;
  16
  17 import eu.etaxonomy.cdm.api.service.config.CreateHierarchyForClassificationConfigurator;
  18 import eu.etaxonomy.cdm.api.service.config.TaxonDeletionConfigurator;
  19 import eu.etaxonomy.cdm.api.service.dto.GroupedTaxonDTO;
  20 import eu.etaxonomy.cdm.api.service.dto.TaxonInContextDTO;
  21 import eu.etaxonomy.cdm.api.service.pager.Pager;
  22 import eu.etaxonomy.cdm.exception.FilterException;
  23 import eu.etaxonomy.cdm.exception.UnpublishedException;
  24 import eu.etaxonomy.cdm.model.common.MarkerType;
  25 import eu.etaxonomy.cdm.model.media.MediaRepresentation;
  26 import eu.etaxonomy.cdm.model.name.Rank;
  27 import eu.etaxonomy.cdm.model.reference.Reference;
  28 import eu.etaxonomy.cdm.model.taxon.Classification;
  29 import eu.etaxonomy.cdm.model.taxon.ITaxonTreeNode;
  30 import eu.etaxonomy.cdm.model.taxon.Taxon;
  31 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  32 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  33 import eu.etaxonomy.cdm.persistence.dto.ClassificationLookupDTO;
  34 import eu.etaxonomy.cdm.persistence.dto.TaxonNodeDto;
  35 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  36 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  37
  38
  39 /**
  40  * @author n.hoffmann
  41  * @since Sep 21, 2009
  42  */
  43 public interface IClassificationService extends IIdentifiableEntityService<Classification> {
  44
  45     /**
  46      *
  47      * @param uuid
  48      * @return
  49      */
  50     public ITaxonTreeNode getTreeNodeByUuid(UUID uuid);
  51
  52     /**
  53      *
  54      * Returns the root node of the the given classification (specified by its UUID)
  55      * @param classificationUuid the uuid of the classification
  56      * @return the root node of the classification
  57      */
  58     public TaxonNode getRootNode(UUID classificationUuid);
  59
  60     public UUID getTaxonNodeUuidByTaxonUuid(UUID classificationUuid, UUID taxonUuid);
  61
  62     /**
  63      * Clones an existing classification including all taxa and taxon nodes.
  64      * @param name
  65      * @param sec
  66      * @param relationshipType
  67      * @return
  68      */
  69     public UpdateResult cloneClassification(UUID classificationUuid, String name, Reference sec, TaxonRelationshipType relationshipType);
  70
  71     /**
  72      *
  73      * @param limit
  74      * @param start
  75      * @param orderHints
  76      * @param propertyPaths
  77      * @return
  78      */
  79     public List<Classification> listClassifications(Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  80
  81     /**
  82      *
  83      * @param taxon
  84      * @param classificationUuid
  85      * @param propertyPaths
  86      * @return
  87      * @deprecated use loadTaxonNode(TaxonNode taxonNode, ...) instead
  88      * if you have a classification and a taxon that is in it, you should also have the according taxonNode
  89      */
  90     @Deprecated
  91     public TaxonNode loadTaxonNodeByTaxon(Taxon taxon, UUID classificationUuid, List<String> propertyPaths);
  92
  93     /**
  94      * Loads all TaxonNodes of the specified classification for a given Rank or lower.
  95      * If a branch of the classification tree is not containing a TaxonNode with a Taxon at the given
  96      * Rank the according node associated with the next lower Rank is taken as root node in this case.
  97      * So the nodes returned may reference Taxa with different Ranks.
  98      *
  99      * If the <code>rank</code> is null the absolute root nodes will be returned.
 100
 101      * @param classification may be null for all classifications
 102      * @param subtree filter on a taxonomic subtree
 103      * @param rank the set to null for to get the root nodes of classifications
 104      * @param includeUnpublished if <code>true</code> unpublished taxa are also exported
 105      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 106      * @param pageIndex The offset (in pageSize chunks) from the start of the result set (0 - based)
 107      * @param propertyPaths
 108      * @return
 109      * @see #pageRankSpecificRootNodes(Classification, TaxonNode, Rank, boolean, Integer, Integer, List)
 110      * @deprecated use according DTO method instead
 111      */
 112     @Deprecated
 113     public List<TaxonNode> listRankSpecificRootNodes(Classification classification, TaxonNode subtree,
 114             Rank rank, boolean includeUnpublished, Integer pageSize, Integer pageIndex,
 115             List<String> propertyPaths);
 116
 117     /**
 118      * Loads all TaxonNodes of the specified classification for a given Rank or lower.
 119      * If a branch of the classification tree is not containing a TaxonNode with a Taxon at the given
 120      * Rank the according node associated with the next lower Rank is taken as root node in this case.
 121      * So the nodes returned may reference Taxa with different Ranks.
 122      *
 123      * If the <code>rank</code> is null the absolute root nodes will be returned.
 124
 125      * @param classification may be null for all classifications
 126      * @param subtree filter on a taxonomic subtree
 127      * @param rank the set to null for to get the root nodes of classifications
 128      * @param includeUnpublished if <code>true</code> unpublished taxa are also exported
 129      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 130      * @param pageIndex The offset (in pageSize chunks) from the start of the result set (0 - based)
 131      * @param propertyPaths
 132      * @return
 133      * @see #pageRankSpecificRootNodes(Classification, TaxonNode, Rank, boolean, Integer, Integer, List)
 134      *
 135      */
 136     public List<TaxonNodeDto> listRankSpecificRootNodeDtos(Classification classification, TaxonNode subtree,
 137             Rank rank, boolean includeUnpublished, Integer pageSize, Integer pageIndex, TaxonNodeDtoSortMode sortMode,
 138             List<String> propertyPaths);
 139
 140
 141     /**
 142      * Loads all TaxonNodes of the specified classification for a given Rank or lower.
 143      * If a branch of the classification tree is not containing a TaxonNode with a Taxon at the given
 144      * Rank the according node associated with the next lower Rank is taken as root node in this case.
 145      * So the nodes returned may reference Taxa with different Ranks.
 146      *
 147      * If the <code>rank</code> is null the absolute root nodes will be returned.
 148      *
 149      * @param classification may be null for all classifications
 150      * @param subtree the taxonomic subtree filter
 151      * @param rank the set to null for to get the root nodes of classifications
 152      * @param includeUnpublished if <code>true</code> unpublished taxa are also exported
 153      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 154      * @param pageIndex The offset (in pageSize chunks) from the start of the result set (0 - based)
 155      * @param propertyPaths
 156      * @return
 157      *
 158      * @see #listRankSpecificRootNodes(Classification, TaxonNode, Rank, boolean, Integer, Integer, List)
 159      */
 160     public Pager<TaxonNode> pageRankSpecificRootNodes(Classification classification, TaxonNode subtree,
 161             Rank rank, boolean includeUnpublished, Integer pageSize, Integer pageIndex,
 162             List<String> propertyPaths);
 163     /**
 164      * @see #pageRankSpecificRootNodes(Classification, TaxonNode, Rank, boolean, Integer, Integer, List)
 165      * @deprecated keep this for compatibility to older versions, might be removed in versions >5.3
 166      */
 167     @Deprecated
 168     public Pager<TaxonNode> pageRankSpecificRootNodes(Classification classification,
 169             Rank rank, boolean includeUnpublished, Integer pageSize, Integer pageIndex,
 170             List<String> propertyPaths);
 171
 172     /**
 173      * @param taxonNode
 174      * @param baseRank
 175      *            specifies the root level of the classification, may be null.
 176      *            Nodes of this rank or in case this rank does not exist in the
 177      *            current branch the next lower rank is taken as root node for
 178      *            this rank henceforth called the <b>base node</b>.
 179      * @param propertyPaths
 180      *            the initialization strategy for the returned TaxonNode
 181      *            instances.
 182      * @param includeUnpublished
 183      *            if <code>true</code> no {@link UnpublishedException}
 184      *            is thrown if any of the taxa in the branch are unpublished
 185      * @return the path of nodes from the <b>base node</b> to the node of the
 186      *            specified taxon.
 187      * @throws UnpublishedException
 188      *            if any of the taxa in the path is unpublished an {@link UnpublishedException} is thrown.
 189      */
 190     public List<TaxonNode> loadTreeBranch(TaxonNode taxonNode, TaxonNode subtree, Rank baseRank, boolean includeUnpublished,
 191             List<String> propertyPaths) throws UnpublishedException;
 192     public List<TaxonNode> loadTreeBranch(TaxonNode taxonNode, Rank baseRank, boolean includeUnpublished,
 193             List<String> propertyPaths) throws UnpublishedException;
 194
 195     /**
 196      * Although this method seems to be a redundant alternative to {@link #loadChildNodesOfTaxonNode(TaxonNode, List)} it is an important
 197      * alternative from which web services benefit. Without this method the web service controller method, which operates outside of the
 198      * transaction, would have to initialize the full taxon tree with all nodes of the taxon.
 199      * This would be rather slow compared to using this method.
 200      * @param taxon
 201      * @param classification
 202      *            the classification to be used
 203      * @param baseRank
 204      *            specifies the root level of the classification, may be null.
 205      *            Nodes of this rank or in case this rank does not exist in the
 206      *            current branch the next lower rank is taken as as root node for
 207      *            this rank henceforth called the <b>base node</b>.
 208      * @param includeUnpublished
 209      *            if <code>true</code> no {@link UnpublishedException}
 210      *            is thrown if any of the taxa in the branch are unpublished
 211      * @param propertyPaths
 212      *            the initialization strategy for the returned TaxonNode
 213      *            instances.
 214      * @return the path of nodes from the <b>base node</b> to the node of the specified
 215      *            taxon.
 216      * @throws UnpublishedException
 217      *            if any of the taxa in the path is unpublished an {@link UnpublishedException} is thrown
 218      */
 219     public List<TaxonNode> loadTreeBranchToTaxon(Taxon taxon, Classification classification,
 220             TaxonNode subtree, Rank baseRank,
 221             boolean includeUnpublished, List<String> propertyPaths) throws UnpublishedException;
 222
 223     /**
 224      * Although this method seems to be a redundant alternative to {@link #loadChildNodesOfTaxonNode(TaxonNode, List)} it is an important
 225      * alternative from which web services benefit. Without this method the web service controller method, which operates outside of the
 226      * transaction, would have to initialize the full taxon tree with all nodes of the taxon.
 227      * This would be rather slow compared to using this method.
 228      * @param taxon
 229      * @param classification
 230      *            the classification to be used
 231      * @param baseRank
 232      *            specifies the root level of the classification, may be null.
 233      *            Nodes of this rank or in case this rank does not exist in the
 234      *            current branch the next lower rank is taken as as root node for
 235      *            this rank henceforth called the <b>base node</b>.
 236      * @param includeUnpublished
 237      *            if <code>true</code> no {@link UnpublishedException}
 238      *            is thrown if any of the taxa in the branch are unpublished
 239      * @param propertyPaths
 240      *            the initialization strategy for the returned TaxonNode
 241      *            instances.
 242      * @return the path of nodes from the <b>base node</b> to the node of the specified
 243      *            taxon.
 244      * @throws UnpublishedException
 245      *            if any of the taxa in the path is unpublished an {@link UnpublishedException} is thrown
 246      */
 247     public List<TaxonNodeDto> loadTreeBranchDTOsToTaxon(Taxon taxon, Classification classification,
 248             TaxonNode subtree, Rank baseRank,
 249             boolean includeUnpublished, List<String> propertyPaths) throws UnpublishedException;
 250
 251     public List<TaxonNode> loadTreeBranchToTaxon(Taxon taxon, Classification classification,
 252             Rank baseRank,
 253             boolean includeUnpublished, List<String> propertyPaths) throws UnpublishedException;
 254
 255     public List<TaxonNode> listChildNodesOfTaxon(UUID taxonUuid, UUID classificationUuid, boolean includeUnpublished,
 256             Integer pageSize, Integer pageIndex, List<String> propertyPaths);
 257
 258     public List<TaxonNode> listChildNodesOfTaxon(UUID taxonUuid, UUID classificationUuid, UUID subtreeUuid, boolean includeUnpublished,
 259             Integer pageSize, Integer pageIndex, List<String> propertyPaths) throws FilterException;
 260
 261     public List<TaxonNodeDto> listChildNodeDtosOfTaxon(UUID taxonUuid, UUID classificationUuid, UUID subtreeUuid, boolean includeUnpublished,
 262             Integer pageSize, Integer pageIndex, TaxonNodeDtoSortMode comparator, List<String> propertyPaths) throws FilterException;
 263
 264     /**
 265      * @param taxonNode
 266      * @param propertyPaths
 267      * @deprecated move to TaxonNodeService
 268      * @return
 269      */
 270     @Deprecated
 271     public List<TaxonNode> loadChildNodesOfTaxonNode(TaxonNode taxonNode, List<String> propertyPaths);
 272
 273     /**
 274      *
 275      * @param classification
 276      * @return
 277      */
 278     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(Classification classification);
 279
 280     public Map<UUID, List<MediaRepresentation>> getAllMediaForChildNodes(TaxonNode taxonNode, List<String> propertyPaths, int size, int height, int widthOrDuration, String[] mimeTypes);
 281
 282     /**
 283      *
 284      * @param taxonNode
 285      * @return
 286      * @deprecated use TaxonNodeService instead
 287      */
 288     @Deprecated
 289     public UUID removeTaxonNode(TaxonNode taxonNode);
 290
 291     /**
 292      *
 293      * @param taxonNode
 294      * @return
 295      * @deprecated use TaxonNodeService instead
 296      */
 297     @Deprecated
 298     public UUID saveTaxonNode(TaxonNode taxonNode);
 299
 300     /**
 301      *
 302      * @param taxonNodeCollection
 303      * @return
 304      * @deprecated use TaxonNodeService instead
 305      */
 306     @Deprecated
 307     public Map<UUID, TaxonNode> saveTaxonNodeAll(Collection<TaxonNode> taxonNodeCollection);
 308
 309     public UUID removeTreeNode(ITaxonTreeNode treeNode);
 310
 311     public UUID saveTreeNode(ITaxonTreeNode treeNode);
 312
 313     public List<TaxonNode> getAllNodes();
 314
 315         public UpdateResult createHierarchyInClassification(Classification classification, CreateHierarchyForClassificationConfigurator configurator);
 316
 317     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(UUID classificationUuid);
 318
 319     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(
 320             UUID classificationUuid, Integer limit, String pattern);
 321
 322     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(
 323             Classification classification, Integer limit, String pattern);
 324
 325     public List<TaxonNode> listSiblingsOfTaxon(UUID taxonUuid, UUID classificationUuid, boolean includeUnpublished,
 326             Integer pageSize, Integer pageIndex, List<String> propertyPaths);
 327
 328     public Pager<TaxonNode> pageSiblingsOfTaxon(UUID taxonUuid, UUID classificationUuid, boolean includeUnpublished, Integer pageSize, Integer pageIndex,
 329             List<String> propertyPaths);
 330
 331     public ClassificationLookupDTO classificationLookup(Classification classification);
 332
 333     public DeleteResult delete(UUID classificationUuid, TaxonDeletionConfigurator config);
 334
 335     /**
 336      * Returns the higher taxon id for each taxon in taxonUuids.
 337      * The highter taxon is defined by rank where the lowest rank equal or above minRank
 338      * is taken. If maxRank <> null and no taxon exists with minRank <= rank <= maxRank
 339      * no higher taxon is returned for this taxon.
 340      *
 341      * @param taxonUuids
 342      * @param minRank
 343      * @param maxRank
 344      * @return
 345      */
 346     public List<GroupedTaxonDTO> groupTaxaByHigherTaxon(List<UUID> taxonUuids, UUID classificationUuid, Rank minRank, Rank maxRank);
 347
 348     /**
 349      * @param taxonUuids
 350      * @param classificationUuid
 351      * @param markerType
 352      * @param value
 353      * @return
 354      */
 355     public List<GroupedTaxonDTO> groupTaxaByMarkedParents(List<UUID> taxonUuids, UUID classificationUuid,
 356             MarkerType markerType, Boolean value);
 357
 358
 359     /**
 360      * Returns the most relevant data of a taxon/taxon node, including children, synonyms
 361      * and certain ancestors if required.
 362      * @param classificationUuid
 363      * @param taxonUuid
 364      * @param doSynonyms
 365      * @param includeUnpublished
 366      * @param ancestorMarkers
 367      * @return
 368      */
 369     public TaxonInContextDTO getTaxonInContext(UUID classificationUuid, UUID taxonUuid,
 370             Boolean doChildren, Boolean doSynonyms, boolean includeUnpublished, List<UUID> ancestorMarkers,
 371             TaxonNodeSortMode sortMode);
 372
 373     /**
 374      * @param classification
 375      * @return
 376      */
 377     public UUID saveClassification(Classification classification);
 378
 379     /**
 380      * @param classificationUuid
 381      * @param limit
 382      * @param pattern
 383      * @param searchForClassifications
 384      * @return
 385      */
 386     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(
 387             UUID classificationUuid, Integer limit, String pattern, boolean searchForClassifications);
 388
 389     /**
 390      * @param classification
 391      * @param limit
 392      * @param pattern
 393      * @param searchForClassifications
 394      * @return
 395      */
 396     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(
 397             Classification classification, Integer limit, String pattern, boolean searchForClassifications);
 398
 399     /**
 400      * @param classificationUuid
 401      * @param searchForClassifications
 402      * @return
 403      */
 404     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(
 405             UUID classificationUuid, boolean searchForClassifications);
 406
 407     /**
 408      * @param classification
 409      * @param searchForClassifications
 410      * @return
 411      */
 412     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(
 413             Classification classification, boolean searchForClassifications);
 414
 415     /**
 416      * @param classificationUuid
 417      * @param limit
 418      * @param pattern
 419      * @param searchForClassifications
 420      * @param includeDoubtful
 421      * @return
 422      */
 423     List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(
 424             UUID classificationUuid, Integer limit, String pattern, boolean searchForClassifications,
 425             boolean includeDoubtful);
 426
 427 }