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