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