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 /**
  43  * @author n.hoffmann
  44  * @since Apr 9, 2010
  45  */
  46 public interface ITaxonNodeService extends IAnnotatableService<TaxonNode>{
  47
  48         /**
  49          * returns the childnodes of the taxonNode, if recursive is true it returns all descendants, if sort is true the nodes are sorted
  50          *
  51          * @param taxonNode
  52          * @param propertyPaths
  53          * @param recursive
  54          * @return List<TaxonNode>
  55          */
  56         public List<TaxonNode> loadChildNodesOfTaxonNode(TaxonNode taxonNode, List<String> propertyPaths, boolean recursive,  boolean includeUnpublished, NodeSortMode sortMode);
  57
  58         /**
  59          * Lists all direct child nodes of the given {@link UuidAndTitleCache} which
  60          * represents the parent {@link TaxonNode}
  61          * @param parent a UuidAndTitleCache object which represents a parent {@link TaxonNode}
  62          * @return a list of UuidAndTitleCache objects that represent children of the
  63          * parent
  64          */
  65         public List<UuidAndTitleCache<TaxonNode>> listChildNodesAsUuidAndTitleCache(UuidAndTitleCache<TaxonNode> parent);
  66
  67     public List<TaxonNode> listChildrenOf(TaxonNode node, Integer pageSize, Integer pageIndex,
  68             boolean recursive, boolean includeUnpublished, List<String> propertyPaths);
  69
  70         /**
  71      * Retrieves a list of {@link UuidAndTitleCache} objects that have a matchin titleCache
  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<UuidAndTitleCache<TaxonNode>> getUuidAndTitleCache(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 UuidAndTitleCache<TaxonNode> 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 UuidAndTitleCache<TaxonNode> getParentUuidAndTitleCache(UuidAndTitleCache<TaxonNode> 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          * @param oldTaxonNode
 124          * @param newAcceptedTaxonNode
 125          * @param synonymType
 126          * @param citation
 127          * @param citationMicroReference
 128          * @param setNameInSource
 129          * @return
 130          *
 131          */
 132         public DeleteResult makeTaxonNodeASynonymOfAnotherTaxonNode(TaxonNode oldTaxonNode, TaxonNode newAcceptedTaxonNode, SynonymType synonymType, Reference citation, String citationMicroReference, boolean setNameInSource) ;
 133
 134         /**
 135          * Changes the taxa associated with the given taxon nodes into synonyms of the new accepted taxon node.
 136          * All data associated with the former taxa are moved to the newly accepted taxon.
 137          *
 138          * @param oldTaxonNodes
 139          * @param newAcceptedTaxonNode
 140          * @param synonymType
 141          * @param citation
 142          * @param citationMicroReference
 143          * @param setNameInSource
 144          * @return
 145          *
 146          */
 147         UpdateResult makeTaxonNodeSynonymsOfAnotherTaxonNode(Set<UUID> oldTaxonNodeUuids, UUID newAcceptedTaxonNodeUUIDs,
 148                         SynonymType synonymType, Reference citation, String citationMicroReference, boolean setNameInSource);
 149
 150
 151         public UpdateResult makeTaxonNodeASynonymOfAnotherTaxonNode(UUID oldTaxonNodeUuid,
 152                 UUID newAcceptedTaxonNodeUUID,
 153                 SynonymType synonymType,
 154                 Reference citation,
 155                 String citationMicroReference,
 156                 boolean setNameInSource) ;
 157
 158
 159     /**
 160      * @param nodeUuids
 161      * @param config
 162      * @return
 163      */
 164     public DeleteResult deleteTaxonNodes(Collection<UUID> nodeUuids, TaxonDeletionConfigurator config);
 165
 166         /**
 167          * deletes the given taxon node the configurator defines whether the children will be deleted too or not
 168          *
 169          * @param node
 170          * @param conf
 171          * @return
 172          *
 173          */
 174         public DeleteResult deleteTaxonNode(TaxonNode node, TaxonDeletionConfigurator config);
 175         /**
 176          * Returns a List of all TaxonNodes of a given Classification.
 177          *
 178          * @param classification - according to the given classification the TaxonNodes are filtered.
 179          * @param start -  beginning of wanted row set, i.e. 0 if one want to start from the beginning.
 180          * @param end  - limit of how many rows are to be pulled from the database, i.e. 1000 rows.
 181          * @return filtered List of TaxonNode according to the classification provided
 182          */
 183
 184     /**
 185      * @param nodeUuid
 186      * @param config
 187      * @return
 188      */
 189     public DeleteResult deleteTaxonNode(UUID nodeUuid, TaxonDeletionConfigurator config);
 190
 191         public List<TaxonNode> listAllNodesForClassification(Classification classification, Integer start, Integer end);
 192
 193         /**
 194          * Counts all TaxonNodes for a given Classification
 195          *
 196          * @param classification - according to the given classification the TaxonNodes are filtered.
 197          * @return
 198          */
 199         public int countAllNodesForClassification(Classification classification);
 200
 201
 202     /**
 203      * @param taxonNodeUuid
 204      * @param newParentTaxonNodeUuid
 205      * @return
 206      */
 207     public UpdateResult moveTaxonNode(UUID taxonNodeUuid, UUID newParentTaxonNodeUuid, int movingType);
 208
 209
 210
 211
 212
 213     /**
 214      * @param taxonNode
 215      * @param newParent
 216      * @param parent
 217      * @return
 218      */
 219     UpdateResult moveTaxonNode(TaxonNode taxonNode, TaxonNode newParent, int movingType);
 220
 221     /**
 222      * deletes the given taxon nodes
 223      *
 224      * @param nodes
 225      * @param config
 226      * @return
 227      *
 228      */
 229     public DeleteResult deleteTaxonNodes(List<TaxonNode> list, TaxonDeletionConfigurator config);
 230
 231     /**
 232      * Returns the of TaxonNodeAgentRelation entities which are associated with the TaxonNode for the
 233      * given TaxonUuid in the specified Classification.
 234      *
 235      * @param taxonUuid
 236      * @param agentUuid TODO
 237      * @param rankUuid TODO
 238      * @param relTypeUuid TODO
 239      * @param classification
 240      * @return
 241      */
 242     public Pager<TaxonNodeAgentRelation> pageTaxonNodeAgentRelations(UUID taxonUuid, UUID classificationUuid,
 243             UUID agentUuid, UUID rankUuid, UUID relTypeUuid, Integer pageSize, Integer pageIndex, List<String> propertyPaths);
 244
 245     /**
 246      * @param parentNodeUuid
 247      * @param newTaxon
 248      * @param ref
 249      * @param microref
 250      * @return
 251      */
 252    public UpdateResult createNewTaxonNode(UUID parentNodeUuid, Taxon newTaxon, Reference ref, String microref);
 253
 254     /**
 255      * @param taxonNodeUUID
 256      * @param agentUUID
 257      * @param relationshipType
 258      * @return
 259      */
 260     public UpdateResult addTaxonNodeAgentRelation(UUID taxonNodeUUID, UUID agentUUID, DefinedTerm relationshipType);
 261
 262     /**
 263      * @param parentNodeUuid
 264      * @param taxonUuid
 265      * @param ref
 266      * @param microref
 267      * @return
 268      */
 269     public UpdateResult createNewTaxonNode(UUID parentNodeUuid, UUID taxonUuid, Reference ref, String microref);
 270
 271     /**
 272      * Sets the secundum reference for all taxa of the given subtree.
 273      * Depending on the configuration, also synonym secundum will be set.
 274      * See {@link SetSecundumForSubtreeConfigurator} for further configuration
 275      * options.
 276      * @param b
 277      * @param configurator
 278      * @return UpdateResult
 279      */
 280     public UpdateResult setSecundumForSubtree(SecundumForSubtreeConfigurator config);
 281
 282
 283     /**
 284      * Sets the publish flag for all taxa and/or synonyms of the subtree.
 285      * @param configurator
 286      * @return
 287      */
 288     public UpdateResult setPublishForSubtree(PublishForSubtreeConfigurator configurator);
 289
 290
 291     /**
 292      * Returns a list of taxon node {@link UUID uuids} according to the given filter.
 293      * @param filter
 294      * @return
 295      */
 296     public long count(TaxonNodeFilter filter);
 297
 298     /**
 299      * Returns a list of taxon node {@link UUID uuids} according to the given filter.
 300      * @param filter
 301      * @return
 302      */
 303     public List<UUID> uuidList(TaxonNodeFilter filter);
 304
 305     /**
 306      * Returns a list of taxon node IDs according to the given filter.
 307      * @param filter
 308      * @return
 309      */
 310     public List<Integer> idList(TaxonNodeFilter filter);
 311
 312 //    /**
 313 //     * @param configurator
 314 //     * @return
 315 //     */
 316 //    UUID monitSetSecundum(SecundumForSubtreeConfigurator configurator);
 317
 318
 319     /**
 320      * @param parent
 321      * @return
 322      */
 323     List<TaxonNodeDto> listChildNodesAsTaxonNodeDto(UuidAndTitleCache<TaxonNode> parent);
 324
 325     /**
 326      * @param parent
 327      * @return
 328      */
 329     List<TaxonNodeDto> listChildNodesAsTaxonNodeDto(ITaxonTreeNode parent);
 330
 331     /**
 332      * @param taxonNodeUuids
 333      * @param newParentNodeUuid
 334      * @param movingType
 335      * @param monitor
 336      * @return
 337      */
 338     UpdateResult moveTaxonNodes(Set<UUID> taxonNodeUuids, UUID newParentNodeUuid, int movingType,
 339             IProgressMonitor monitor);
 340
 341     /**
 342      * Retrieves the first taxon node that is direct or indirect parent
 343      * to all nodes of the given list of nodes. This can also return
 344      * the root node of a classification<br>
 345      * If no common parent node could be found <code>null</code> is returned.
 346      * @param nodes the direct/indirect child taxon nodes for which the common
 347      * parent should be retrieved
 348      * @return the common direct/indirect parent of all nodes
 349      */
 350     public TaxonNodeDto findCommonParentDto(Collection<TaxonNodeDto> nodes);
 351
 352     /**
 353      * @param taxonNodeUuid
 354      * @return
 355      */
 356     TaxonNodeDto dto(UUID taxonNodeUuid);
 357
 358     /**
 359      * @param parentNodeUuid
 360      * @param areas
 361      * @param authentication
 362      * @return
 363      */
 364     List<TaxonDistributionDTO> getTaxonDistributionDTOForSubtree(UUID parentNodeUuid, List<String> propertyPaths, Authentication authentication);
 365
 366     /**
 367      * @param parentNodeUuid
 368      * @param areas
 369      * @return
 370      */
 371     List<TaxonDistributionDTO> getTaxonDistributionDTOForSubtree(UUID parentNodeUuid, List<String> propertyPaths);
 372
 373     /**
 374      * @param parentNodeUuid
 375      * @param newTaxonNode
 376      * @return
 377      */
 378     UpdateResult saveNewTaxonNode(TaxonNode newTaxonNode);
 379
 380     /**
 381      * @param clazz
 382      * @param restrictions
 383      * @param pageSize
 384      * @param pageIndex
 385      * @param orderHints
 386      * @param propertyPaths
 387      * @param includeUnpublished
 388      * @return
 389      */
 390     public <S extends TaxonNode> Pager<S> page(Class<S> clazz, List<Restriction<?>> restrictions, Integer pageSize, Integer pageIndex,
 391             List<OrderHint> orderHints, List<String> propertyPaths, boolean includeUnpublished);
 392
 393     /**
 394     * @param classification
 395     * @param rank
 396     * @return
 397     */
 398         public TaxonNodeDto taxonNodeDtoParentRank(Classification classification, Rank rank, TaxonName name);
 399
 400
 401
 402
 403 }