cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/ITaxonNodeService.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.Set;
  15 import java.util.UUID;
  16
  17 import org.springframework.security.core.Authentication;
  18
  19 import eu.etaxonomy.cdm.api.service.config.PublishForSubtreeConfigurator;
  20 import eu.etaxonomy.cdm.api.service.config.SecundumForSubtreeConfigurator;
  21 import eu.etaxonomy.cdm.api.service.config.TaxonDeletionConfigurator;
  22 import eu.etaxonomy.cdm.api.service.dto.TaxonDistributionDTO;
  23 import eu.etaxonomy.cdm.api.service.pager.Pager;
  24 import eu.etaxonomy.cdm.common.monitor.IProgressMonitor;
  25 import eu.etaxonomy.cdm.filter.TaxonNodeFilter;
  26 import eu.etaxonomy.cdm.model.name.Rank;
  27 import eu.etaxonomy.cdm.model.name.TaxonName;
  28 import eu.etaxonomy.cdm.model.reference.Reference;
  29 import eu.etaxonomy.cdm.model.taxon.Classification;
  30 import eu.etaxonomy.cdm.model.taxon.ITaxonTreeNode;
  31 import eu.etaxonomy.cdm.model.taxon.SynonymType;
  32 import eu.etaxonomy.cdm.model.taxon.Taxon;
  33 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  34 import eu.etaxonomy.cdm.model.taxon.TaxonNodeAgentRelation;
  35 import eu.etaxonomy.cdm.model.term.DefinedTerm;
  36 import eu.etaxonomy.cdm.persistence.dao.common.Restriction;
  37 import eu.etaxonomy.cdm.persistence.dto.TaxonNodeDto;
  38 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  39 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  40
  41 /**
  42  * @author n.hoffmann
  43  * @since Apr 9, 2010
  44  */
  45 public interface ITaxonNodeService extends IAnnotatableService<TaxonNode>{
  46
  47         /**
  48          * returns the childnodes of the taxonNode, if recursive is true it returns all descendants, if sort is true the nodes are sorted
  49          *
  50          * @param taxonNode
  51          * @param propertyPaths
  52          * @param recursive
  53          * @return List<TaxonNode>
  54          */
  55         public List<TaxonNode> loadChildNodesOfTaxonNode(TaxonNode taxonNode, List<String> propertyPaths, boolean recursive,  boolean includeUnpublished, NodeSortMode sortMode);
  56
  57         /**
  58          * Lists all direct child nodes of the given {@link UuidAndTitleCache} which
  59          * represents the parent {@link TaxonNode}
  60          * @param parent a UuidAndTitleCache object which represents a parent {@link TaxonNode}
  61          * @return a list of UuidAndTitleCache objects that represent children of the
  62          * parent
  63          */
  64 //      public List<UuidAndTitleCache<TaxonNode>> listChildNodesAsUuidAndTitleCache(UuidAndTitleCache<TaxonNode> parent);
  65
  66     public List<TaxonNode> listChildrenOf(TaxonNode node, Integer pageSize, Integer pageIndex,
  67             boolean recursive, boolean includeUnpublished, List<String> propertyPaths);
  68
  69         /**
  70      * Retrieves a list of {@link UuidAndTitleCache} objects that have a matchin titleCache
  71      *
  72      * @param limit the maximum results
  73      * @param pattern the titleCache that is searched for
  74      * @param classificationUuid if specified only nodes of this classification are retrieved
  75      * @return a list of matches
  76      */
  77         public List<TaxonNodeDto> getTaxonNodeDto(Integer limit, String pattern, UUID classificationUuid);
  78
  79     /**
  80      * Retrieves the parent node of the child {@link TaxonNode}
  81      * @param child the child for which the parent should be retrieved
  82      * @return the parent taxon node
  83      */
  84         public TaxonNodeDto getParentUuidAndTitleCache(ITaxonTreeNode child);
  85
  86         /**
  87      * Retrieves the parent node of the {@link TaxonNode} represented by the given {@link UuidAndTitleCache}.
  88      * @param child the child for which the parent should be retrieved
  89      * @return an UuidAndTitleCache object representing the parent node
  90      */
  91         public TaxonNodeDto getParentUuidAndTitleCache(TaxonNodeDto child);
  92
  93 //      /**
  94 //     * Lists all direct child nodes of the given {@link ITaxonTreeNode}
  95 //     * @param parent the parent ITaxonTreeNode
  96 //     * @return a list of UuidAndTitleCache objects that represent children of the
  97 //     * parent
  98 //     */
  99 //      public List<UuidAndTitleCache<TaxonNode>> listChildNodesAsUuidAndTitleCache(ITaxonTreeNode parent);
 100
 101         /**
 102      *Returns the childnodes of the taxonNode, if recursive is true it returns all descendants, if sort is true the nodes are sorted
 103      *
 104      * @param taxonNode
 105      * @param recursive
 106      * @param doSynonyms if true also synonyms are returned as children
 107      * @param sortMode
 108      * @param pageSize
 109      * @param pageIndex
 110      *
 111      * @return List<TaxonNodeDto>
 112      */
 113     public Pager<TaxonNodeDto> pageChildNodesDTOs(UUID taxonNodeUuid, boolean recursive, boolean includeUnpublished,
 114             boolean doSynonyms, NodeSortMode sortMode,
 115             Integer pageSize, Integer pageIndex);
 116
 117     public TaxonNodeDto parentDto(UUID taxonNodeUuid);
 118
 119         /**
 120          * Changes the taxon associated with the given taxon node into a synonym of the new accepted taxon node.
 121          * All data associated with the former taxon are moved to the newly accepted taxon.
 122          */
 123         public DeleteResult makeTaxonNodeASynonymOfAnotherTaxonNode(TaxonNode oldTaxonNode, TaxonNode newAcceptedTaxonNode, SynonymType synonymType, Reference citation, String citationMicroReference, boolean setNameInSource) ;
 124
 125         /**
 126          * Changes the taxa associated with the given taxon nodes into synonyms of the new accepted taxon node.
 127          * All data associated with the former taxa are moved to the newly accepted taxon.
 128          */
 129         public UpdateResult makeTaxonNodeSynonymsOfAnotherTaxonNode(Set<UUID> oldTaxonNodeUuids, UUID newAcceptedTaxonNodeUUIDs,
 130                         SynonymType synonymType, Reference citation, String citationMicroReference, boolean setNameInSource);
 131
 132         public UpdateResult makeTaxonNodeASynonymOfAnotherTaxonNode(UUID oldTaxonNodeUuid,
 133                 UUID newAcceptedTaxonNodeUUID,
 134                 SynonymType synonymType,
 135                 Reference citation,
 136                 String citationMicroReference,
 137                 boolean setNameInSource) ;
 138
 139     public DeleteResult deleteTaxonNodes(Collection<UUID> nodeUuids, TaxonDeletionConfigurator config);
 140
 141         /**
 142          * deletes the given taxon node the configurator defines whether the children will be deleted too or not
 143          */
 144         public DeleteResult deleteTaxonNode(TaxonNode node, TaxonDeletionConfigurator config);
 145
 146         /**
 147          * Returns a List of all TaxonNodes of a given Classification.
 148          *
 149          * @param classification - according to the given classification the TaxonNodes are filtered.
 150          * @param start -  beginning of wanted row set, i.e. 0 if one want to start from the beginning.
 151          * @param end  - limit of how many rows are to be pulled from the database, i.e. 1000 rows.
 152          * @return filtered List of TaxonNode according to the classification provided
 153          */
 154
 155     /**
 156      * @param nodeUuid
 157      * @param config
 158      * @return
 159      */
 160     public DeleteResult deleteTaxonNode(UUID nodeUuid, TaxonDeletionConfigurator config);
 161
 162         public List<TaxonNode> listAllNodesForClassification(Classification classification, Integer start, Integer end);
 163
 164         /**
 165          * Counts all TaxonNodes for a given Classification
 166          *
 167          * @param classification - according to the given classification the TaxonNodes are filtered.
 168          * @return the count result
 169          */
 170         public int countAllNodesForClassification(Classification classification);
 171
 172     public UpdateResult moveTaxonNode(UUID taxonNodeUuid, UUID newParentTaxonNodeUuid, int movingType);
 173
 174     public UpdateResult moveTaxonNode(TaxonNode taxonNode, TaxonNode newParent, int movingType);
 175
 176     /**
 177      * deletes the given taxon nodes
 178      */
 179     public DeleteResult deleteTaxonNodes(List<TaxonNode> list, TaxonDeletionConfigurator config);
 180
 181     /**
 182      * Returns the of TaxonNodeAgentRelation entities which are associated with the TaxonNode for the
 183      * given TaxonUuid in the specified Classification.
 184      *
 185      * @param taxonUuid
 186      * @param agentUuid TODO
 187      * @param rankUuid TODO
 188      * @param relTypeUuid TODO
 189      * @param classification
 190      * @return
 191      */
 192     public Pager<TaxonNodeAgentRelation> pageTaxonNodeAgentRelations(UUID taxonUuid, UUID classificationUuid,
 193             UUID agentUuid, UUID rankUuid, UUID relTypeUuid, Integer pageSize, Integer pageIndex, List<String> propertyPaths);
 194
 195     public UpdateResult createNewTaxonNode(UUID parentNodeUuid, Taxon newTaxon, Reference ref, String microref);
 196
 197     public UpdateResult addTaxonNodeAgentRelation(UUID taxonNodeUUID, UUID agentUUID, DefinedTerm relationshipType);
 198
 199     /**
 200      * @param parentNodeUuid
 201      * @param taxonUuid
 202      * @param ref
 203      * @param microref
 204      * @return
 205      */
 206     public UpdateResult createNewTaxonNode(UUID parentNodeUuid, UUID taxonUuid, Reference ref, String microref);
 207
 208     /**
 209      * Sets the secundum reference for all taxa of the given subtree.
 210      * Depending on the configuration, also synonym secundum will be set.
 211      * See {@link SetSecundumForSubtreeConfigurator} for further configuration
 212      * options.
 213      * @return UpdateResult
 214      */
 215     public UpdateResult setSecundumForSubtree(SecundumForSubtreeConfigurator config);
 216
 217
 218     /**
 219      * Sets the publish flag for all taxa and/or synonyms of the subtree.
 220      */
 221     public UpdateResult setPublishForSubtree(PublishForSubtreeConfigurator configurator);
 222
 223     /**
 224      * Returns a list of taxon node {@link UUID uuids} according to the given filter.
 225      */
 226     public long count(TaxonNodeFilter filter);
 227
 228     /**
 229      * Returns a list of taxon node {@link UUID uuids} according to the given filter.
 230      */
 231     public List<UUID> uuidList(TaxonNodeFilter filter);
 232
 233     /**
 234      * Returns a list of taxon node IDs according to the given filter.
 235      */
 236     public List<Integer> idList(TaxonNodeFilter filter);
 237
 238     List<TaxonNodeDto> listChildNodesAsTaxonNodeDto(TaxonNodeDto parent);
 239
 240
 241     List<TaxonNodeDto> listChildNodesAsTaxonNodeDto(ITaxonTreeNode parent);
 242
 243     /**
 244      * @param taxonNodeUuids
 245      * @param newParentNodeUuid
 246      * @param movingType
 247      * @param monitor
 248      * @return
 249      */
 250     UpdateResult moveTaxonNodes(Set<UUID> taxonNodeUuids, UUID newParentNodeUuid, int movingType,
 251             IProgressMonitor monitor);
 252
 253     /**
 254      * Retrieves the first taxon node that is direct or indirect parent
 255      * to all nodes of the given list of nodes. This can also return
 256      * the root node of a classification<br>
 257      * If no common parent node could be found <code>null</code> is returned.
 258      * @param nodes the direct/indirect child taxon nodes for which the common
 259      * parent should be retrieved
 260      * @return the common direct/indirect parent of all nodes
 261      */
 262     public TaxonNodeDto findCommonParentDto(Collection<TaxonNodeDto> nodes);
 263
 264     public TaxonNodeDto dto(UUID taxonNodeUuid);
 265
 266     public List<TaxonDistributionDTO> getTaxonDistributionDTOForSubtree(UUID parentNodeUuid, List<String> propertyPaths, Authentication authentication);
 267
 268     public List<TaxonDistributionDTO> getTaxonDistributionDTOForSubtree(UUID parentNodeUuid, List<String> propertyPaths);
 269
 270     public UpdateResult saveNewTaxonNode(TaxonNode newTaxonNode);
 271
 272     public <S extends TaxonNode> Pager<S> page(Class<S> clazz, List<Restriction<?>> restrictions, Integer pageSize, Integer pageIndex,
 273             List<OrderHint> orderHints, List<String> propertyPaths, boolean includeUnpublished);
 274
 275         public TaxonNodeDto taxonNodeDtoParentRank(Classification classification, Rank rank, TaxonName name);
 276
 277     /**
 278      * Lists all direct child nodes of the given {@link ITaxonTreeNode}
 279      * @param parent the parent ITaxonTreeNode
 280      * @return a list of UuidAndTitleCache objects that represent children of the
 281      * parent
 282      */
 283          public List<UuidAndTitleCache<TaxonNode>> listChildNodesAsUuidAndTitleCache(ITaxonTreeNode parent);
 284          public List<UuidAndTitleCache> getUuidAndTitleCache(Integer limit, String pattern, UUID classificationUuid);
 285          public List<UuidAndTitleCache<TaxonNode>> listChildNodesAsUuidAndTitleCache(UuidAndTitleCache<TaxonNode> parent);
 286
 287 }