cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/ITaxonService.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.api.service.config.ITaxonServiceConfigurator;
  19 import eu.etaxonomy.cdm.api.service.pager.Pager;
  20 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  21 import eu.etaxonomy.cdm.model.common.OrderedTermVocabulary;
  22 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  23 import eu.etaxonomy.cdm.model.name.Rank;
  24 import eu.etaxonomy.cdm.model.reference.ReferenceBase;
  25 import eu.etaxonomy.cdm.model.taxon.Synonym;
  26 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  27 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  28 import eu.etaxonomy.cdm.model.taxon.Taxon;
  29 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  30 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  31 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  32 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  33 import eu.etaxonomy.cdm.model.taxon.TaxonomicTree;
  34 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  35 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  36 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  37
  38
  39 public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{
  40
  41         /**
  42          * FIXME candidate for harmonization?
  43          */
  44         public abstract TaxonBase getTaxonByUuid(UUID uuid);
  45
  46         /**
  47          *
  48          * @param uuid
  49          * @return
  50          */
  51         public abstract TaxonNode getTaxonNodeByUuid(UUID uuid);
  52
  53         /**
  54          * @param taxon
  55          * @param taxonomicTree
  56          * @param propertyPath
  57          * @return
  58          */
  59         public TaxonNode loadTaxonNodeByTaxon(Taxon taxon, UUID taxonomicTreeUuid, List<String> propertyPaths);
  60
  61         /**
  62          * @param taxonNode
  63          * @param baseRank
  64          *            specifies the root level of the taxonomic tree, may be null.
  65          *            Nodes of this rank or in case this rank does not exist in the
  66          *            current branch the next lower rank is taken as root node for
  67          *            this rank henceforth called the <b>base node</b>.
  68          * @param propertyPaths
  69          *            the initialization strategy for the returned TaxonNode
  70          *            instances.
  71          * @return the path of nodes from the <b>base node</b> to the node of the
  72          *         specified taxon.
  73          */
  74         public List<TaxonNode> loadTreeBranchTo(TaxonNode taxonNode, Rank baseRank, List<String> propertyPaths);
  75
  76         /**
  77          * @param taxon
  78          * @param taxonomicTree
  79          *            the taxonomic tree to be used
  80          * @param baseRank
  81          *            specifies the root level of the taxonomic tree, may be null.
  82          *            Nodes of this rank or in case this rank does not exist in the
  83          *            current branch the next lower rank is taken as as root node for
  84          *            this rank henceforth called the <b>base node</b>.
  85          * @param propertyPaths
  86          *            the initialization strategy for the returned TaxonNode
  87          *            instances.
  88          * @return the path of nodes from the <b>base node</b> to the node of the specified
  89          *         taxon.
  90          */
  91         public List<TaxonNode> loadTreeBranchToTaxon(Taxon taxon, TaxonomicTree taxonomicTree, Rank baseRank,
  92                         List<String> propertyPaths);
  93
  94         /**
  95          * @param taxon
  96          * @param taxonomicTree
  97          * @param propertyPaths
  98          * @return
  99          */
 100         public List<TaxonNode> loadChildNodesOfTaxon(Taxon taxon, TaxonomicTree taxonomicTree, List<String> propertyPaths);
 101
 102
 103         /**
 104          * FIXME candidate for harmonization?
 105          * save a taxon and return its UUID
 106          */
 107         public abstract UUID saveTaxon(TaxonBase taxon);
 108
 109         /**
 110          *
 111          * @param taxonNode
 112          * @return
 113          */
 114         public abstract UUID saveTaxonNode(TaxonNode taxonNode);
 115
 116         /**
 117          * FIXME candidate for harmonization?
 118          *  save a taxon and return its UUID
 119          */
 120         //public abstract UUID saveTaxon(TaxonBase taxon, TransactionStatus txStatus);
 121
 122         /**
 123          * FIXME candidate for harmonization?
 124          * save a collection of taxa and return its UUID
 125          */
 126         public abstract Map<UUID, ? extends TaxonBase> saveTaxonAll(Collection<? extends TaxonBase> taxonCollection);
 127
 128         /**
 129          *
 130          * @param taxonNodeCollection
 131          * @return
 132          */
 133         public abstract Map<UUID, TaxonNode> saveTaxonNodeAll(Collection<TaxonNode> taxonNodeCollection);
 134
 135         /**
 136          * FIXME candidate for harmonization?
 137          * delete a taxon and return its UUID
 138          */
 139         public abstract UUID removeTaxon(TaxonBase taxon);
 140
 141         /**
 142          * Computes all taxon bases.
 143          * FIXME could substitute with list(Synonym.class, limit, start)
 144          * @param limit
 145          * @param start
 146          * @return
 147          */
 148         public abstract List<Synonym> getAllSynonyms(int limit, int start);
 149
 150         /**
 151          * Computes all taxon bases.
 152          * FIXME could substitute with list(Taxon.class, limit,start)
 153          * @param limit
 154          * @param start
 155          * @return
 156          */
 157         public abstract List<Taxon> getAllTaxa(int limit, int start);
 158
 159         /**
 160          * Computes all taxon bases.
 161          * FIXME could substitute with list(limit,start) from superclass
 162          * @param limit
 163          * @param start
 164          * @return
 165          */
 166         public abstract List<TaxonBase> getAllTaxonBases(int limit, int start);
 167
 168
 169         /**
 170          * Computes all taxonomic trees.
 171          * FIXME candidate for harmonization
 172          * @param limit
 173          * @param start
 174          * @return
 175          * @deprecated use {#listTaxonomicTrees} instead
 176          */
 177         @Deprecated
 178         public List<TaxonomicTree> getAllTaxonomicTrees(int limit, int start);
 179
 180         /**
 181          * @param limit
 182          * @param start
 183          * @param orderHints
 184          * @param propertyPaths
 185          * @return
 186          */
 187         public List<TaxonomicTree> listTaxonomicTrees(Integer limit, Integer start, List<OrderHint> orderHints,
 188                         List<String> propertyPaths);
 189
 190
 191         /**
 192          * Loads all TaxonNodes of the specified tree for a given Rank.
 193          * If a branch does not contain a TaxonNode with a TaxonName at the given
 194          * Rank the node associated with the next lower Rank is taken as root node.
 195          * If the <code>rank</code> is null the absolute root nodes will be returned.
 196          *
 197          * @param taxonomicTree
 198          * @param rank may be null
 199          * @param propertyPaths
 200          * @return
 201          */
 202         public List<TaxonNode> loadRankSpecificRootNodes(TaxonomicTree taxonomicTree, Rank rank, List<String> propertyPaths);
 203
 204
 205         /**
 206          * Returns a taxonomic tree by it's uuid.
 207          * @param uuid
 208          * @return
 209          */
 210         public TaxonomicTree getTaxonomicTreeByUuid(UUID uuid);
 211
 212         /**
 213          * Returns a taxonomic tree by it's uuid.
 214          * @param uuid
 215          * @return
 216          */
 217         public UUID saveTaxonomicTree(TaxonomicTree tree);
 218
 219         /**
 220          * Remove the taxonomic tree from the persitence context
 221          *
 222          * @param taxonomicTree
 223          * @return
 224          */
 225         public UUID removeTaxonomicTree(TaxonomicTree taxonomicTree);
 226
 227         /**
 228          * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
 229          * @param sec The concept reference that the taxon belongs to
 230          * @return The List<Taxon> of root taxa.
 231          */
 232         public List<Taxon> getRootTaxa(ReferenceBase sec);
 233
 234
 235         /**
 236          * Computes all Taxon instances that do not have a taxonomic parent.
 237          * @param sec The concept reference that the taxon belongs to
 238          *
 239          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 240          * @return The List<Taxon> of root taxa.
 241          */
 242         public abstract List<Taxon> getRootTaxa(ReferenceBase sec, CdmFetch cdmFetch, boolean onlyWithChildren);
 243
 244         /**
 245          * Computes all Taxon instances that do not have a taxonomic parent.
 246          * @param sec The concept reference that the taxon belongs to
 247          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 248          * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
 249          * the misapplied name are not returned.<Br>Default: true.
 250          * @return The List<Taxon> of root taxa.
 251          */
 252         public abstract List<Taxon> getRootTaxa(ReferenceBase sec, boolean onlyWithChildren, boolean withMisapplications);
 253
 254         /**
 255          * Computes all Taxon instances which name is of a certain Rank.
 256          * @param rank The rank of the taxon name
 257          * @param sec The concept reference that the taxon belongs to
 258          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 259          * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
 260          * the misapplied name are not returned.<Br>Default: true.
 261          * @param propertyPaths
 262          *            properties to be initialized, For detailed description and
 263          *            examples <b>please refer to:</b>
 264          *            {@link BeanInitializer#initialize(Object, List)}. <Br>
 265          *            Default: true.
 266          * @return The List<Taxon> of root taxa.
 267          */
 268         public abstract List<Taxon> getRootTaxa(Rank rank, ReferenceBase sec, boolean onlyWithChildren, boolean withMisapplications, List<String> propertyPaths);
 269
 270         /**
 271          * Computes all relationships.
 272          * @param limit
 273          * @param start
 274          * @return
 275          */
 276     public abstract List<RelationshipBase> getAllRelationships(int limit, int start);
 277
 278         /**
 279          * Returns TaxonRelationshipType vocabulary
 280          * @return
 281          * @deprecated use TermService#getVocabulary(VocabularyType) instead
 282          */
 283         public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();
 284
 285         /** */
 286         public abstract List<TaxonBase> searchTaxaByName(String name, ReferenceBase sec);
 287
 288         public Synonym makeTaxonSynonym (Taxon oldTaxon, Taxon newAcceptedTaxon, SynonymRelationshipType synonymType, ReferenceBase citation, String citationMicroReference);
 289
 290         /**
 291          * Sets the synonyms name as the accepted taxons name. Deletes the synonym from the accepted taxon synonym list
 292          * and attaches a new synonym created with the former name of the accepted taxon
 293          *
 294          * @param synonym
 295          * @param acceptedTaxon
 296          * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
 297          */
 298         public void makeSynonymAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon, SynonymRelationshipType synonymRelationshipType );
 299
 300         /**
 301          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 302          * where the supplied taxon is relatedTo.
 303          *
 304          * @param taxon The taxon that is relatedTo
 305          * @param type The type of TaxonRelationship (can be null)
 306          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 307          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 308          * @param orderHints Properties to order by
 309          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 310          * @return a List of TaxonRelationship instances
 311          */
 312         public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 313
 314         /**
 315          * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
 316          * where the supplied taxon is relatedTo.
 317          *
 318          * @param taxon The taxon that is relatedTo
 319          * @param type The type of TaxonRelationship (can be null)
 320          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 321          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 322          * @param orderHints Properties to order by
 323          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 324          * @return a Pager of TaxonRelationship instances
 325          */
 326         public Pager<TaxonRelationship> pageToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 327
 328         /**
 329          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 330          * where the supplied taxon is relatedFrom.
 331          *
 332          * @param taxon The taxon that is relatedFrom
 333          * @param type The type of TaxonRelationship (can be null)
 334          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 335          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 336          * @param orderHints Properties to order by
 337          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 338          * @return a List of TaxonRelationship instances
 339          */
 340         public List<TaxonRelationship> listFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 341
 342         /**
 343          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 344          * where the supplied taxon is relatedFrom.
 345          *
 346          * @param taxon The taxon that is relatedFrom
 347          * @param type The type of TaxonRelationship (can be null)
 348          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 349          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 350          * @param orderHints Properties to order by
 351          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 352          * @return a Pager of TaxonRelationship instances
 353          */
 354         public Pager<TaxonRelationship> pageFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 355
 356         /**
 357          * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 358          * where the supplied taxon is relatedTo.
 359          *
 360          * @param taxon The taxon that is relatedTo
 361          * @param type The type of SynonymRelationship (can be null)
 362          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 363          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 364          * * @param orderHints Properties to order by
 365          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 366          * @return a Pager of SynonymRelationship instances
 367          */
 368         public Pager<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 369
 370         public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
 371
 372         public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
 373
 374         /**
 375          * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 376          *
 377          * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
 378          * @param queryString
 379          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 380          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 381          * @param orderHints
 382          *            Supports path like <code>orderHints.propertyNames</code> which
 383          *            include *-to-one properties like createdBy.username or
 384          *            authorTeam.persistentTitleCache
 385          * @param propertyPaths properties to be initialized
 386          * @return a Pager Taxon instances
 387          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 388          */
 389         public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 390
 391         /**
 392          * Returns a list of TaxonBase instances where the
 393          * taxon.name properties match the parameters passed.
 394          *
 395          * @param clazz optionally filter by class
 396          * @param uninomial
 397          * @param infragenericEpithet
 398          * @param specificEpithet
 399          * @param infraspecificEpithet
 400          * @param rank
 401          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 402          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 403          * @return a Pager of TaxonBase instances
 404          */
 405         public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 406
 407         /**
 408          * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
 409          * that match the properties specified in the configurator.
 410          * @param configurator
 411          * @return
 412          */
 413         public Pager<IdentifiableEntity> findTaxaAndNames(ITaxonServiceConfigurator configurator);
 414 }