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.List;
  14 import java.util.Set;
  15
  16 import eu.etaxonomy.cdm.api.service.config.ITaxonServiceConfigurator;
  17 import eu.etaxonomy.cdm.api.service.pager.Pager;
  18 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  19 import eu.etaxonomy.cdm.model.common.OrderedTermVocabulary;
  20 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  21 import eu.etaxonomy.cdm.model.common.RelationshipBase.Direction;
  22 import eu.etaxonomy.cdm.model.media.MediaRepresentation;
  23 import eu.etaxonomy.cdm.model.name.Rank;
  24 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  25 import eu.etaxonomy.cdm.model.reference.Reference;
  26 import eu.etaxonomy.cdm.model.taxon.Classification;
  27 import eu.etaxonomy.cdm.model.taxon.Synonym;
  28 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  29 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  30 import eu.etaxonomy.cdm.model.taxon.Taxon;
  31 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  32 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  33 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  34 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  35 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  36 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  37 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  38
  39
  40 public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{
  41
  42         /**
  43          * Computes all taxon bases.
  44          * @param limit
  45          * @param start
  46          * @return
  47          *
  48          * FIXME could substitute with list(Synonym.class, limit, start)
  49          */
  50         public List<Synonym> getAllSynonyms(int limit, int start);
  51
  52         /**
  53          * Computes all taxon bases.
  54          * @param limit
  55          * @param start
  56          * @return
  57          *
  58          * FIXME could substitute with list(Taxon.class, limit,start)
  59          */
  60         public List<Taxon> getAllTaxa(int limit, int start);
  61
  62         /**
  63          * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
  64          * @param sec The concept reference that the taxon belongs to
  65          * @return The List<Taxon> of root taxa.
  66          * @deprecated obsolete when using classification
  67          */
  68         public List<Taxon> getRootTaxa(Reference sec);
  69
  70
  71         /**
  72          * Computes all Taxon instances that do not have a taxonomic parent.
  73          * @param sec The concept reference that the taxon belongs to
  74          *
  75          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  76          * @return The List<Taxon> of root taxa.
  77          * @deprecated obsolete when using classification
  78          */
  79         public List<Taxon> getRootTaxa(Reference sec, CdmFetch cdmFetch, boolean onlyWithChildren);
  80
  81         /**
  82          * Computes all Taxon instances that do not have a taxonomic parent.
  83          * @param sec The concept reference that the taxon belongs to
  84          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  85          * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
  86          * the misapplied name are not returned.<Br>Default: true.
  87          * @return The List<Taxon> of root taxa.
  88          * @deprecated obsolete when using classification
  89          */
  90         public List<Taxon> getRootTaxa(Reference sec, boolean onlyWithChildren, boolean withMisapplications);
  91
  92         /**
  93          * Computes all Taxon instances which name is of a certain Rank.
  94          * @param rank The rank of the taxon name
  95          * @param sec The concept reference that the taxon belongs to
  96          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  97          * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
  98          * the misapplied name are not returned.<Br>Default: true.
  99          * @param propertyPaths
 100          *            properties to be initialized, For detailed description and
 101          *            examples <b>please refer to:</b>
 102          *            {@link BeanInitializer#initialize(Object, List)}. <Br>
 103          *            Default: true.
 104          * @return The List<Taxon> of root taxa.
 105          * @deprecated obsolete when using classification
 106          */
 107         public List<Taxon> getRootTaxa(Rank rank, Reference sec, boolean onlyWithChildren, boolean withMisapplications, List<String> propertyPaths);
 108
 109         /**
 110          * Computes all relationships.
 111          * @param limit
 112          * @param start
 113          * @return
 114          * FIXME candidate for harmonization - rename to listRelationships
 115          */
 116     public List<RelationshipBase> getAllRelationships(int limit, int start);
 117
 118         /**
 119          * Returns TaxonRelationshipType vocabulary
 120          * @return
 121          * @deprecated use TermService#getVocabulary(VocabularyType) instead
 122          */
 123         public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();
 124
 125         /**
 126          * Returns a list of taxa that matches the name string and the sec reference
 127          * @param name the name string to search for
 128          * @param sec the taxons sec reference
 129          * @return a list of taxa matching the name and the sec reference
 130          */
 131         public List<TaxonBase> searchTaxaByName(String name, Reference sec);
 132
 133         /**
 134          * Changes an accepted taxon to a synonym of another taxon.
 135          *
 136          * @param oldTaxonNode
 137          *                              the <code>TaxonNode</code> of the accepted taxon that will be changed into a synonym
 138          * @param newAcceptedTaxonNode
 139          *                              the <code>TaxonNode</code> of the accepted taxon, the old taxon will become a synonym of
 140          * @param synonymType
 141          *                              <code>SynonymRelationshipType</code> to indicate whether hetero or homotypic
 142          * @param citation
 143          *                              the reference for this assumption
 144          * @param citationMicroReference
 145          *                              the micro citation
 146          * @return
 147          *                              the newly created synonym
 148          */
 149         public Synonym changeAcceptedTaxonToSynonym (TaxonNode oldTaxonNode, TaxonNode newAcceptedTaxonNode, SynonymRelationshipType synonymType, Reference citation, String citationMicroReference);
 150
 151         /**
 152          * Swaps given synonym and accepted taxon.
 153          * In particular:
 154          * <ul>
 155          *              <li>A new accepted taxon with the synonyms name is created</li>
 156          *              <li>The synonym is deleted from the old accepted taxons synonym list</li>
 157          *              <li>A new synonym with the name of the old accepted taxon is created</li>
 158          *              <li>The newly created synonym get related to the newly created accepted taxon</li>
 159          * </ul>
 160          *
 161          * @param synonym
 162          * @param acceptedTaxon
 163          * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
 164          */
 165         public void swapSynonymAndAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
 166
 167         /**
 168          * Change a synonym into an accepted taxon and removes
 169          * the synonym relationship to the given accepted taxon.
 170          *
 171          * @param synonym
 172          *                              the synonym to change into an accepted taxon
 173          * @param acceptedTaxon
 174          *                              an accepted taxon, the synonym had a relationship to
 175          * @return
 176          *                              the newly created accepted taxon
 177          */
 178         public Taxon changeSynonymToAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
 179
 180         /**
 181          * Change a synonym into a related concept
 182          *
 183          * @param synonym
 184          *                              the synonym to change into the concept taxon
 185          * @param toTaxon
 186          *                              the taxon the newly created concept should be related to
 187          * @param taxonRelationshipType
 188          *                              the type of relationship
 189          * @param citation
 190          * @param microcitation
 191          * @return
 192          *                              the newly created concept
 193          */
 194         public Taxon changeSynonymToRelatedTaxon(Synonym synonym, Taxon toTaxon, TaxonRelationshipType taxonRelationshipType, Reference citation, String microcitation);
 195
 196
 197         /**
 198          * Move a synonym to another taxon, effectively removing the old synonym relationship
 199          *
 200          * @param synonymRelation
 201          * @param toTaxon
 202          * @param reference
 203          * @param referenceDetail
 204          * @return
 205          */
 206         public Taxon moveSynonymToAnotherTaxon(SynonymRelationship synonymRelation, Taxon toTaxon, SynonymRelationshipType synonymRelationshipType, Reference reference, String referenceDetail);
 207
 208         /**
 209          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 210          * where the supplied taxon is relatedTo.
 211          *
 212          * @param taxon The taxon that is relatedTo
 213          * @param type The type of TaxonRelationship (can be null)
 214          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 215          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 216          * @param orderHints Properties to order by
 217          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 218          * @return a List of TaxonRelationship instances
 219          */
 220         public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 221
 222
 223
 224         /**
 225          * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
 226          * where the supplied taxon is relatedTo.
 227          *
 228          * @param taxon The taxon that is relatedTo
 229          * @param type The type of TaxonRelationship (can be null)
 230          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 231          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 232          * @param orderHints Properties to order by
 233          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 234          * @return a Pager of TaxonRelationship instances
 235          */
 236         public Pager<TaxonRelationship> pageToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 237
 238         /**
 239          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 240          * where the supplied taxon is relatedFrom.
 241          *
 242          * @param taxon The taxon that is relatedFrom
 243          * @param type The type of TaxonRelationship (can be null)
 244          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 245          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 246          * @param orderHints Properties to order by
 247          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 248          * @return a List of TaxonRelationship instances
 249          */
 250         public List<TaxonRelationship> listFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 251
 252
 253         /**
 254          * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 255          * where the supplied taxon is relatedFrom.
 256          *
 257          * @param taxon The taxon that is relatedFrom
 258          * @param type The type of TaxonRelationship (can be null)
 259          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 260          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 261          * @param orderHints Properties to order by
 262          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 263          * @return a Pager of TaxonRelationship instances
 264          */
 265         public Pager<TaxonRelationship> pageFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 266
 267         /**
 268          * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 269          * where the supplied synonym is relatedFrom.
 270          *
 271          * @param taxon The synonym that is relatedFrom
 272          * @param type The type of SynonymRelationship (can be null)
 273          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 274          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 275          * * @param orderHints Properties to order by
 276          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 277          * @return a Pager of SynonymRelationship instances
 278          */
 279         public Pager<SynonymRelationship> getSynonyms(Synonym synonym, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 280
 281         /**
 282          * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 283          * where the supplied taxon is relatedTo.
 284          *
 285          * @param taxon The taxon that is relatedTo
 286          * @param type The type of SynonymRelationship (can be null)
 287          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 288          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 289          * * @param orderHints Properties to order by
 290          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 291          * @return a Pager of SynonymRelationship instances
 292          */
 293         public Pager<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 294
 295         public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
 296
 297         public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
 298
 299         /**
 300          * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 301          *
 302          * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
 303          * @param queryString
 304          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 305          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 306          * @param orderHints
 307          *            Supports path like <code>orderHints.propertyNames</code> which
 308          *            include *-to-one properties like createdBy.username or
 309          *            authorTeam.persistentTitleCache
 310          * @param propertyPaths properties to be initialized
 311          * @return a Pager Taxon instances
 312          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 313          */
 314         public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 315
 316         /**
 317          * Returns a list of TaxonBase instances where the
 318          * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 319          * <i>null</i> will search for those taxa with a value of null in that field
 320          *
 321          * @param clazz optionally filter by class (can be null to return all taxa)
 322          * @param uninomial
 323          * @param infragenericEpithet
 324          * @param specificEpithet
 325          * @param infraspecificEpithet
 326          * @param rank
 327          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 328          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 329          * @return a list of TaxonBase instances
 330          */
 331         public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 332
 333         /**
 334          * Returns a list of TaxonBase instances where the
 335          * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 336          * <i>null</i> will search for those taxa with a value of null in that field
 337          *
 338          * @param clazz optionally filter by class
 339          * @param uninomial
 340          * @param infragenericEpithet
 341          * @param specificEpithet
 342          * @param infraspecificEpithet
 343          * @param rank
 344          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 345          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 346          * @return a List of TaxonBase instances
 347          */
 348         public List<TaxonBase> listTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 349
 350         /**
 351          * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
 352          * that match the properties specified in the configurator.
 353          * @param configurator
 354          * @return
 355          */
 356         public Pager<IdentifiableEntity> findTaxaAndNames(ITaxonServiceConfigurator configurator);
 357
 358         /**
 359          *
 360          * @param taxon
 361          * @param size
 362          * @param height
 363          * @param widthOrDuration
 364          * @param mimeTypes
 365          * @return
 366          *
 367          * FIXME candidate for harmonization - rename to listMedia()
 368          */
 369         public List<MediaRepresentation> getAllMedia(Taxon taxon, int size, int height, int widthOrDuration, String[] mimeTypes);
 370
 371         public List<TaxonBase> findTaxaByID(Set<Integer> listOfIDs);
 372         /**
 373          * returns a list of inferred synonyms concerning the taxon with synonymrelationshiptype type
 374          * @param tree
 375          * @param taxon
 376          * @param type
 377          * @return
 378          */
 379         public List<Synonym> createInferredSynonyms(Classification tree, Taxon taxon, SynonymRelationshipType type);
 380         /**
 381          * returns a list of all inferred synonyms (inferred epithet, inferred genus and potential combination) concerning the taxon
 382          * @param tree
 383          * @param taxon
 384          * @return
 385          */
 386         public List<Synonym> createAllInferredSynonyms(Classification tree, Taxon taxon);
 387
 388         public int countAllRelationships();
 389
 390         public List<TaxonNameBase> findIdenticalTaxonNames(List<String> propertyPath);
 391         public List<TaxonNameBase> findIdenticalTaxonNameIds(List<String> propertyPath);
 392         public String getPhylumName(TaxonNameBase name);
 393
 394         public long deleteSynonymRelationships(Synonym syn);
 395         /**
 396          * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 397          * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
 398          *
 399          * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
 400          * @param type The type of SynonymRelationship (can be null)
 401          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 402          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 403          * @param orderHints Properties to order by
 404          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 405          * @param direction The direction of the relationship
 406          * @return a List of SynonymRelationship instances
 407          */
 408         public List<SynonymRelationship> listSynonymRelationships(
 409                         TaxonBase taxonBase, SynonymRelationshipType type, Integer pageSize, Integer pageNumber,
 410                         List<OrderHint> orderHints, List<String> propertyPaths, Direction direction);
 411
 412         /**
 413          * @param tnb
 414          * @return
 415          */
 416         public Taxon findBestMatchingTaxon(String taxonName);
 417
 418         public Synonym findBestMatchingSynonym(String taxonName);
 419
 420 }