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

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10
  11 package eu.etaxonomy.cdm.api.service;
  12
  13 import java.util.Collection;
  14 import java.util.List;
  15 import java.util.Map;
  16 import java.util.UUID;
  17
  18 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  19 import eu.etaxonomy.cdm.model.media.MediaRepresentation;
  20 import eu.etaxonomy.cdm.model.name.Rank;
  21 import eu.etaxonomy.cdm.model.taxon.ITreeNode;
  22 import eu.etaxonomy.cdm.model.taxon.Taxon;
  23 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  24 import eu.etaxonomy.cdm.model.taxon.TaxonomicTree;
  25 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  26
  27
  28 /**
  29  * @author n.hoffmann
  30  * @created Sep 21, 2009
  31  * @version 1.0
  32  */
  33 public interface ITaxonTreeService extends IIdentifiableEntityService<TaxonomicTree> {
  34
  35         /**
  36          *
  37          * @param uuid
  38          * @return
  39          */
  40         public TaxonNode getTaxonNodeByUuid(UUID uuid);
  41
  42         /**
  43          *
  44          * @param uuid
  45          * @return
  46          */
  47         public ITreeNode getTreeNodeByUuid(UUID uuid);
  48
  49         /**
  50          *
  51          * @param limit
  52          * @param start
  53          * @param orderHints
  54          * @param propertyPaths
  55          * @return
  56          */
  57         public List<TaxonomicTree> listTaxonomicTrees(Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  58
  59         /**
  60          *
  61          * @param uuid
  62          * @return
  63          */
  64         public TaxonomicTree getTaxonomicTreeByUuid(UUID uuid);
  65
  66         /**
  67          *
  68          * @param taxon
  69          * @param taxonomicTreeUuid
  70          * @param propertyPaths
  71          * @return
  72          * @deprecated use loadTaxonNode(TaxonNode taxonNode, ...) instead
  73          * if you have a taxonomicTree and a taxon that is in it, you should also have the according taxonNode
  74          */
  75         public TaxonNode loadTaxonNodeByTaxon(Taxon taxon, UUID taxonomicTreeUuid, List<String> propertyPaths);
  76
  77         /**
  78          *
  79          * @param taxonNode
  80          * @param propertyPaths
  81          * @return
  82          * @deprecated use TaxonNodeService instead
  83          */
  84         public TaxonNode loadTaxonNode(TaxonNode taxonNode, List<String> propertyPaths);
  85
  86         /**
  87          * Loads all TaxonNodes of the specified tree for a given Rank.
  88          * If a branch does not contain a TaxonNode with a TaxonName at the given
  89          * Rank the node associated with the next lower Rank is taken as root node.
  90          * If the <code>rank</code> is null the absolute root nodes will be returned.
  91          *
  92          * @param taxonomicTree
  93          * @param rank may be null
  94          * @param propertyPaths
  95          * @return
  96          */
  97         public List<TaxonNode> loadRankSpecificRootNodes(TaxonomicTree taxonomicTree, Rank rank, List<String> propertyPaths);
  98
  99         /**
 100          * @param taxonNode
 101          * @param baseRank
 102          *            specifies the root level of the taxonomic tree, may be null.
 103          *            Nodes of this rank or in case this rank does not exist in the
 104          *            current branch the next lower rank is taken as root node for
 105          *            this rank henceforth called the <b>base node</b>.
 106          * @param propertyPaths
 107          *            the initialization strategy for the returned TaxonNode
 108          *            instances.
 109          * @return the path of nodes from the <b>base node</b> to the node of the
 110          *         specified taxon.
 111          */
 112         public List<TaxonNode> loadTreeBranch(TaxonNode taxonNode, Rank baseRank, List<String> propertyPaths);
 113
 114         /**
 115          * Although this method seems to be a redundant alternative to {@link #loadChildNodesOfTaxonNode(TaxonNode, List)} it is an important
 116          * alternative from which web services benefit. Without this method the web service controller method, which operates outside of the
 117          * transaction, would have to initialize the full taxon tree with all nodes of the taxon.
 118          * This would be rather slow compared to using this method.
 119          * @param taxon
 120          * @param taxonomicTree
 121          *            the taxonomic tree to be used
 122          * @param baseRank
 123          *            specifies the root level of the taxonomic tree, may be null.
 124          *            Nodes of this rank or in case this rank does not exist in the
 125          *            current branch the next lower rank is taken as as root node for
 126          *            this rank henceforth called the <b>base node</b>.
 127          * @param propertyPaths
 128          *            the initialization strategy for the returned TaxonNode
 129          *            instances.
 130          * @return the path of nodes from the <b>base node</b> to the node of the specified
 131          *         taxon.
 132          */
 133         public List<TaxonNode> loadTreeBranchToTaxon(Taxon taxon, TaxonomicTree taxonomicTree, Rank baseRank, List<String> propertyPaths);
 134
 135
 136
 137         /**
 138          * Although this method seems to be a redundant alternative to {@link #loadChildNodesOfTaxonNode(TaxonNode, List)} it is an important
 139          * alternative from which web services benefit. Without this method the web service controller method, which operates outside of the
 140          * transaction, would have to initialize the full taxon tree with all nodes of the taxon.
 141          * This would be rather slow compared to using this method.
 142          * @param taxon
 143          * @param taxonomicTree
 144          * @param propertyPaths
 145          * @return
 146          */
 147         public List<TaxonNode> loadChildNodesOfTaxon(Taxon taxon, TaxonomicTree taxonomicTree, List<String> propertyPaths);
 148
 149         /**
 150          *
 151          * @param taxon
 152          * @param taxonomicTree
 153          * @param propertyPaths
 154          * @return
 155          * @deprecated move to TaxonNodeService
 156          */
 157         public List<TaxonNode> loadChildNodesOfTaxonNode(TaxonNode taxonNode, List<String> propertyPaths);
 158
 159         /**
 160          *
 161          * @param taxonomicTree
 162          * @return
 163          */
 164         public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByTaxonomicTree(TaxonomicTree taxonomicTree);
 165
 166         /**
 167          * @param taxon
 168          * @param taxTree
 169          * @param propertyPaths
 170          * @param size
 171          * @param height
 172          * @param widthOrDuration
 173          * @param mimeTypes
 174          * @return
 175          *  @deprecated use getAllMediaForChildNodes(TaxonNode taxonNode, ...) instead
 176          * if you have a taxonomicTree and a taxon that is in it, you should also have the according taxonNode
 177          */
 178         public Map<UUID, List<MediaRepresentation>> getAllMediaForChildNodes(Taxon taxon, TaxonomicTree taxTree, List<String> propertyPaths, int size, int height, int widthOrDuration, String[] mimeTypes);
 179
 180         /**
 181          *
 182          * @param taxonNode
 183          * @param propertyPaths
 184          * @param size
 185          * @param height
 186          * @param widthOrDuration
 187          * @param mimeTypes
 188          * @return
 189          */
 190         public Map<UUID, List<MediaRepresentation>> getAllMediaForChildNodes(TaxonNode taxonNode, List<String> propertyPaths, int size, int height, int widthOrDuration, String[] mimeTypes);
 191
 192         /**
 193          *
 194          * @param taxonNode
 195          * @return
 196          * @deprecated use TaxonNodeService instead
 197          */
 198         public UUID removeTaxonNode(TaxonNode taxonNode);
 199
 200         /**
 201          *
 202          * @param taxonNode
 203          * @return
 204          * @deprecated use TaxonNodeService instead
 205          */
 206         public UUID saveTaxonNode(TaxonNode taxonNode);
 207
 208         /**
 209          *
 210          * @param taxonNodeCollection
 211          * @return
 212          * @deprecated use TaxonNodeService instead
 213          */
 214         public Map<UUID, TaxonNode> saveTaxonNodeAll(Collection<TaxonNode> taxonNodeCollection);
 215
 216         /**
 217          *
 218          * @param treeNode
 219          * @return
 220          */
 221         public UUID removeTreeNode(ITreeNode treeNode);
 222
 223         /**
 224          *
 225          * @param treeNode
 226          * @return
 227          */
 228         public UUID saveTreeNode(ITreeNode treeNode);
 229
 230
 231         public List<TaxonNode> getAllNodes();
 232
 233
 234 }