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