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.io.IOException;
  14 import java.util.List;
  15 import java.util.Set;
  16 import java.util.UUID;
  17
  18 import org.apache.lucene.index.CorruptIndexException;
  19 import org.apache.lucene.queryParser.ParseException;
  20
  21 import eu.etaxonomy.cdm.api.service.config.ITaxonServiceConfigurator;
  22 import eu.etaxonomy.cdm.api.service.config.MatchingTaxonConfigurator;
  23 import eu.etaxonomy.cdm.api.service.config.TaxonDeletionConfigurator;
  24 import eu.etaxonomy.cdm.api.service.exception.DataChangeNoRollbackException;
  25 import eu.etaxonomy.cdm.api.service.exception.HomotypicalGroupChangeException;
  26 import eu.etaxonomy.cdm.api.service.exception.ReferencedObjectUndeletableException;
  27 import eu.etaxonomy.cdm.api.service.pager.Pager;
  28 import eu.etaxonomy.cdm.api.service.search.SearchResult;
  29 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  30 import eu.etaxonomy.cdm.model.common.Language;
  31 import eu.etaxonomy.cdm.model.common.OrderedTermVocabulary;
  32 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  33 import eu.etaxonomy.cdm.model.common.RelationshipBase.Direction;
  34 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  35 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  36 import eu.etaxonomy.cdm.model.media.MediaRepresentation;
  37 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  38 import eu.etaxonomy.cdm.model.name.Rank;
  39 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  40 import eu.etaxonomy.cdm.model.reference.Reference;
  41 import eu.etaxonomy.cdm.model.taxon.Classification;
  42 import eu.etaxonomy.cdm.model.taxon.Synonym;
  43 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  44 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  45 import eu.etaxonomy.cdm.model.taxon.Taxon;
  46 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  47 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  48 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  49 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  50 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  51 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  52
  53
  54 public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{
  55
  56     /**
  57      * Computes all taxon bases.
  58      * @param limit
  59      * @param start
  60      * @return
  61      *
  62      * FIXME could substitute with list(Synonym.class, limit, start)
  63      */
  64     public List<Synonym> getAllSynonyms(int limit, int start);
  65
  66     /**
  67      * Computes all taxon bases.
  68      * @param limit
  69      * @param start
  70      * @return
  71      *
  72      * FIXME could substitute with list(Taxon.class, limit,start)
  73      */
  74     public List<Taxon> getAllTaxa(int limit, int start);
  75
  76     /**
  77      * Computes all Taxon instances that do not have a taxonomic parent.
  78      * @param sec The concept reference that the taxon belongs to
  79      *
  80      * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  81      * @return The List<Taxon> of root taxa.
  82      * @deprecated obsolete when using classification
  83      */
  84     public List<Taxon> getRootTaxa(Reference sec, CdmFetch cdmFetch, boolean onlyWithChildren);
  85
  86     /**
  87      * Computes all Taxon instances which name is of a certain Rank.
  88      * @param rank The rank of the taxon name
  89      * @param sec The concept reference that the taxon belongs to
  90      * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  91      * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
  92      * the misapplied name are not returned.<Br>Default: true.
  93      * @param propertyPaths
  94      *            properties to be initialized, For detailed description and
  95      *            examples <b>please refer to:</b>
  96      *            {@link BeanInitializer#initialize(Object, List)}. <Br>
  97      *            Default: true.
  98      * @return The List<Taxon> of root taxa.
  99      * @deprecated obsolete when using classification
 100      */
 101     public List<Taxon> getRootTaxa(Rank rank, Reference sec, boolean onlyWithChildren, boolean withMisapplications, List<String> propertyPaths);
 102
 103     /**
 104      * Computes all relationships.
 105      * @param limit
 106      * @param start
 107      * @return
 108      * FIXME candidate for harmonization - rename to listRelationships
 109      */
 110     public List<RelationshipBase> getAllRelationships(int limit, int start);
 111
 112     /**
 113      * Returns TaxonRelationshipType vocabulary
 114      * @return
 115      * @deprecated use TermService#getVocabulary(VocabularyType) instead
 116      */
 117     public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();
 118
 119     /**
 120      * Returns a list of taxa that matches the name string and the sec reference
 121      * @param name the name string to search for
 122      * @param sec the taxons sec reference
 123      * @return a list of taxa matching the name and the sec reference
 124      */
 125     public List<TaxonBase> searchTaxaByName(String name, Reference sec);
 126
 127     /**
 128      * Swaps given synonym and accepted taxon.
 129      * In particular:
 130      * <ul>
 131      *          <li>A new accepted taxon with the synonyms name is created</li>
 132      *          <li>The synonym is deleted from the old accepted taxons synonym list</li>
 133      *          <li>A new synonym with the name of the old accepted taxon is created</li>
 134      *          <li>The newly created synonym get related to the newly created accepted taxon</li>
 135      * </ul>
 136      *
 137      * @param synonym
 138      * @param acceptedTaxon
 139      * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
 140      */
 141     public void swapSynonymAndAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
 142
 143     /**
 144      * Changes a synonym into an accepted taxon and removes
 145      * the synonym relationship to the given accepted taxon.
 146      * Other synonyms homotypic to the synonym to change are
 147      * moved to the same new accepted taxon as homotypic
 148      * synonyms. The new accepted taxon has the same name and
 149      * the same sec reference as the old synonym.<BR>
 150      * If the given accepted taxon and the synonym are homotypic
 151      * to each other an exception may be thrown as taxonomically it doesn't
 152      * make sense to have two accepted taxa in the same homotypic group
 153      * but also it is than difficult to decide how to handle other names
 154      * in the homotypic group. It is up to the implementing class to
 155      * handle this situation via an exception or in another way.
 156      * TODO Open issue: does the old synonym need to be deleted from the database?
 157      *
 158      * @param synonym
 159      *                          the synonym to change into an accepted taxon
 160      * @param acceptedTaxon
 161      *                          an accepted taxon, the synonym had a relationship to
 162      * @param deleteSynonym
 163      *                  if true the method tries to delete the old synonym from the database
 164      * @param copyCitationInfo
 165      *                  if true the citation and the microcitation of newly created synonyms
 166      *                  is taken from the old synonym relationships.
 167      * @param citation
 168      *                  if given this citation is added to the newly created synonym
 169      *                  relationships as citation. Only used if copyCitationInfo is <code> false</code>
 170      * @param microCitation
 171      *                  if given this microCitation is added to the newly created synonym
 172      *                  relationships as microCitation.Only used if copyCitationInfo is <code> false</code>
 173      * @return
 174      *                  the newly created accepted taxon
 175      * @throws IllegalArgumentException
 176      *                  if the given accepted taxon and the synonym are homotypic
 177      *              to each other an exception may be thrown as taxonomically it doesn't
 178      *                  make sense to have two accepted taxa in the same homotypic group
 179      *          but also it is than difficult to decide how to handle other names
 180      *          in the homotypic group. It is up to the implementing class to
 181      *          handle this situation via an exception or in another way.
 182      */
 183     public Taxon changeSynonymToAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon, boolean deleteSynonym, boolean copyCitationInfo, Reference citation, String microCitation) throws HomotypicalGroupChangeException;
 184
 185     /**
 186      * TODO still needed and correct?
 187      * Change a synonym into a related concept
 188      *
 189      * @param synonym
 190      *                          the synonym to change into the concept taxon
 191      * @param toTaxon
 192      *                          the taxon the newly created concept should be related to
 193      * @param taxonRelationshipType
 194      *                          the type of relationship
 195      * @param reference
 196      * @param microReference
 197      * @return
 198      *                          the newly created concept
 199      */
 200     public Taxon changeSynonymToRelatedTaxon(Synonym synonym, Taxon toTaxon, TaxonRelationshipType taxonRelationshipType, Reference reference, String microReference);
 201
 202     /**
 203      * Deletes all synonym relationships of a given synonym. If taxon is given only those relationships to the taxon are deleted.
 204      * @param syn the synonym
 205      * @param taxon
 206      * @return
 207      */
 208     public long deleteSynonymRelationships(Synonym syn, Taxon taxon);
 209
 210     /**
 211      * Deletes a taxon from the underlying database according to the given {@link TaxonDeletionConfigurator configurator}.
 212      * @param taxon
 213      * @param config
 214      * @throws ReferencedObjectUndeletableException
 215      */
 216     public void deleteTaxon(Taxon taxon, TaxonDeletionConfigurator config) throws ReferencedObjectUndeletableException;
 217
 218     /**
 219      * Changes the homotypic group of a synonym into the new homotypic group.
 220      * All relations to taxa are updated correctly depending on the homotypic
 221      * group of the accepted taxon. <BR>
 222      * All existing basionym relationships to and from this name are removed.<BR>
 223      * If the parameter <code>targetTaxon</code> is defined, the synonym is
 224      * added to this taxon irrespctive of if it has been related to this
 225      * taxon before.<BR>
 226      * If <code>removeFromOtherTaxa</code> is true and <code>targetTaxon</code> is
 227      * defined all relationships to other taxa are deleted.<BR>
 228      * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
 229      * between the existing basionym(s) of the new homotypic group and the synonyms name
 230      * is added.<BR>
 231      *
 232      * @param synonym
 233      * @param newHomotypicalGroup
 234      * @param taxon
 235      * @param setBasionymRelationIfApplicable
 236      */
 237     public void changeHomotypicalGroupOfSynonym(Synonym synonym, HomotypicalGroup newHomotypicalGroup, Taxon targetTaxon,
 238                         boolean removeFromOtherTaxa, boolean setBasionymRelationIfApplicable);
 239
 240
 241     /**
 242      * Moves a synonym to another taxon and removes the old synonym relationship.
 243      *
 244      * @param oldSynonymRelation the old synonym relationship defining the synonym to move and the old accepted taxon.
 245      * @param newTaxon the taxon the synonym will be moved to
 246      * @param moveHomotypicGroup if the synonym belongs to a homotypical group with other synonyms and
 247      *          <code>moveHomotypicGroup</code> is <code>true</code> all these synonyms are moved to the new taxon,
 248      *          if <code>false</code> a {@link HomotypicalGroupChangeException} is thrown.
 249      *          <code>MoveHomotypicGroup</code> has no effect if the synonym is the only synonym in it's homotypic group.
 250      * @param newSynonymRelationshipType the synonym relationship type of the new synonym relations. Default is
 251      *          {@link SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF() heterotypic}.
 252      * @param newReference The reference for the new synonym relation(s).
 253      * @param newReferenceDetail The reference detail for the new synonym relation(s).
 254      * @param keepReference if no <code>newReference</code> and/or no <code>newReferenceDetail</code>
 255      *          is defined they are taken from the old synonym relation(s) if <code>keepReference</code> is
 256      *          <code>true</code>. If <code>false</code> the reference and the reference detail will be taken
 257      *          only from the <code>newReference</code> and <code>newReferenceDetail</code>.
 258      * @return The new synonym relationship. If <code>moveHomotypicGroup</code> is <code>true</code> additionally
 259      *          created new synonym relationships must be retrieved separately from the new taxon.
 260      * @throws HomotypicalGroupChangeException Exception is thrown if (1) synonym is homotypic to the old accepted taxon or
 261      *          (2) synonym is in homotypic group with other synonyms and <code>moveHomotypicGroup</code> is false
 262      */
 263     public SynonymRelationship moveSynonymToAnotherTaxon(SynonymRelationship oldSynonymRelation, Taxon newTaxon, boolean moveHomotypicGroup,
 264             SynonymRelationshipType newSynonymRelationshipType, Reference newReference, String newReferenceDetail, boolean keepReference) throws HomotypicalGroupChangeException;
 265
 266     /**
 267      * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 268      * where the supplied taxon is relatedTo.
 269      *
 270      * @param taxon The taxon that is relatedTo
 271      * @param type The type of TaxonRelationship (can be null)
 272      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 273      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 274      * @param orderHints Properties to order by
 275      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 276      * @return a List of TaxonRelationship instances
 277      */
 278     public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 279
 280
 281
 282     /**
 283      * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
 284      * where the supplied taxon is relatedTo.
 285      *
 286      * @param taxon The taxon that is relatedTo
 287      * @param type The type of TaxonRelationship (can be null)
 288      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 289      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 290      * @param orderHints Properties to order by
 291      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 292      * @return a Pager of TaxonRelationship instances
 293      */
 294     public Pager<TaxonRelationship> pageToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 295
 296     /**
 297      * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 298      * where the supplied taxon is relatedFrom.
 299      *
 300      * @param taxon The taxon that is relatedFrom
 301      * @param type The type of TaxonRelationship (can be null)
 302      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 303      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 304      * @param orderHints Properties to order by
 305      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 306      * @return a List of TaxonRelationship instances
 307      */
 308     public List<TaxonRelationship> listFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 309
 310
 311     /**
 312      * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 313      * where the supplied taxon is relatedFrom.
 314      *
 315      * @param taxon The taxon that is relatedFrom
 316      * @param type The type of TaxonRelationship (can be null)
 317      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 318      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 319      * @param orderHints Properties to order by
 320      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 321      * @return a Pager of TaxonRelationship instances
 322      */
 323     public Pager<TaxonRelationship> pageFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 324
 325     /**
 326      * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 327      * where the supplied synonym is relatedFrom.
 328      *
 329      * @param taxon The synonym that is relatedFrom
 330      * @param type The type of SynonymRelationship (can be null)
 331      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 332      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 333      * * @param orderHints Properties to order by
 334      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 335      * @return a Pager of SynonymRelationship instances
 336      */
 337     public Pager<SynonymRelationship> getSynonyms(Synonym synonym, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 338
 339     /**
 340      * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 341      * where the supplied taxon is relatedTo.
 342      *
 343      * @param taxon The taxon that is relatedTo
 344      * @param type The type of SynonymRelationship (can be null)
 345      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 346      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 347      * * @param orderHints Properties to order by
 348      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 349      * @return a Pager of SynonymRelationship instances
 350      */
 351     public Pager<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 352
 353     /**
 354      * Returns the list of all synonyms that share the same homotypical group with the given taxon.
 355      * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
 356      * @param taxon
 357      * @param propertyPaths
 358      * @return
 359      */
 360     public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
 361
 362     /**
 363      * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
 364      * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
 365      * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
 366      * belong to a homotypical group which cannot be the homotypical group to which the
 367      * taxon name of the given taxon belongs. This method does not return the homotypic group the given
 368      * taxon belongs to.<BR>
 369      * This method does neglect the type of synonym relationship that is defined between the given taxon
 370      * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
 371      * in one of the result lists as long as the synonym does not belong to the same homotypic group as
 372      * the given taxon.<BR>
 373      * The list returned is ordered according to the date of publication of the
 374      * first published name within each homotypical group.
 375      *
 376      * @see                     #getHeterotypicSynonymyGroups()
 377      * @see                     #getSynonyms()
 378      * @see                     SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
 379      * @see                     eu.etaxonomy.cdm.model.name.HomotypicalGroup
 380
 381      * @param taxon
 382      * @param propertyPaths
 383      * @return
 384      */
 385     public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
 386
 387     /**
 388      * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 389      *
 390      * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
 391      * @param queryString
 392      * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 393      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 394      * @param orderHints
 395      *            Supports path like <code>orderHints.propertyNames</code> which
 396      *            include *-to-one properties like createdBy.username or
 397      *            authorTeam.persistentTitleCache
 398      * @param propertyPaths properties to be initialized
 399      * @return a Pager Taxon instances
 400      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 401      */
 402     public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 403
 404     /**
 405      * Returns a list of TaxonBase instances where the
 406      * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 407      * <i>null</i> will search for those taxa with a value of null in that field
 408      *
 409      * @param clazz optionally filter by class (can be null to return all taxa)
 410      * @param uninomial
 411      * @param infragenericEpithet
 412      * @param specificEpithet
 413      * @param infraspecificEpithet
 414      * @param rank
 415      * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 416      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 417      * @return a list of TaxonBase instances
 418      */
 419     public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 420
 421     /**
 422      * Returns a list of TaxonBase instances where the
 423      * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 424      * <i>null</i> will search for those taxa with a value of null in that field
 425      *
 426      * @param clazz optionally filter by class
 427      * @param uninomial
 428      * @param infragenericEpithet
 429      * @param specificEpithet
 430      * @param infraspecificEpithet
 431      * @param rank
 432      * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 433      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 434      * @return a List of TaxonBase instances
 435      */
 436     public List<TaxonBase> listTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 437
 438     /**
 439      * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
 440      * that match the properties specified in the configurator.
 441      * @param configurator
 442      * @return
 443      */
 444     public Pager<IdentifiableEntity> findTaxaAndNames(ITaxonServiceConfigurator configurator);
 445
 446     /**
 447      * <h4>This is an experimental feature, it may be moved, modified, or even
 448      * removed in future releases!!!</h4>
 449      *
 450      * @param clazz
 451      * @param queryString
 452      *            the query string to filter by
 453      * @param classification
 454      *            If a taxonomic classification three is specified here the
 455      *            result set will only contain taxa of the given classification
 456      * @param languages
 457      *            Search only in these languages. Not all text fields in the cdm
 458      *            model are multilingual, thus this setting will only apply to
 459      *            the multilingiual fields. Other fields are searched
 460      *            nevertheless if this parameter is set or not.
 461      * @param pageSize
 462      *            The maximum number of objects returned (can be null for all
 463      *            objects)
 464      * @param pageNumber
 465      *            The offset (in pageSize chunks) from the start of the result
 466      *            set (0 - based)
 467      * @param orderHints
 468      *            Supports path like <code>orderHints.propertyNames</code> which
 469      *            include *-to-one properties like createdBy.username or
 470      *            authorTeam.persistentTitleCache
 471      * @param propertyPaths
 472      *            properties to initialize - see
 473      *            {@link BeanInitializer#initialize(Object, List)}
 474      * @return a paged list of instances of type T matching the queryString
 475      * @throws IOException
 476      * @throws CorruptIndexException
 477      * @throws ParseException
 478      */
 479     public Pager<SearchResult<TaxonBase>> findByDescriptionElementFullText(Class<? extends DescriptionElementBase> clazz, String queryString, Classification classification, List<Language> languages, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException;
 480
 481
 482     /**
 483      *
 484      * @param taxon
 485      * @param size
 486      * @param height
 487      * @param widthOrDuration
 488      * @param mimeTypes
 489      * @return
 490      *
 491      * FIXME candidate for harmonization - rename to listMedia()
 492      */
 493     public List<MediaRepresentation> getAllMedia(Taxon taxon, int size, int height, int widthOrDuration, String[] mimeTypes);
 494
 495
 496     public List<TaxonBase> findTaxaByID(Set<Integer> listOfIDs);
 497
 498     /**
 499      * Returns the TaxonBase with the given UUID
 500      * using the given match mode and initialization strategy
 501      *
 502      * @param uuid
 503      * @param propertyPaths
 504      * @return
 505      */
 506     public TaxonBase findTaxonByUuid(UUID uuid, List<String> propertyPaths);
 507
 508     public int countAllRelationships();
 509
 510     public List<TaxonNameBase> findIdenticalTaxonNames(List<String> propertyPath);
 511     public List<TaxonNameBase> findIdenticalTaxonNameIds(List<String> propertyPath);
 512     public String getPhylumName(TaxonNameBase name);
 513
 514     public long deleteSynonymRelationships(Synonym syn);
 515
 516
 517     /**
 518      * Removes a synonym.<BR><BR>
 519      *
 520      * In detail it removes
 521      *  <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
 522      *  <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
 523      *  <BR><BR>
 524      *  If <code>removeNameIfPossible</code> is true
 525      *  it also removes the synonym name if it is not used in any other context
 526      *  (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
 527      *  If <code>newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
 528      *  the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
 529      *
 530      *  If synonym is <code>null</code> the method has no effect.
 531      *
 532      * @param taxon
 533      * @param synonym
 534      * @param removeNameIfPossible
 535      * @throws DataChangeNoRollbackException
 536      */
 537     public void deleteSynonym(Synonym synonym, Taxon taxon, boolean removeNameIfPossible, boolean newHomotypicGroupIfNeeded);
 538
 539
 540     /**
 541      * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
 542      * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
 543      *
 544      * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
 545      * @param type The type of SynonymRelationship (can be null)
 546      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 547      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 548      * @param orderHints Properties to order by
 549      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 550      * @param direction The direction of the relationship
 551      * @return a List of SynonymRelationship instances
 552      */
 553     public List<SynonymRelationship> listSynonymRelationships(
 554             TaxonBase taxonBase, SynonymRelationshipType type, Integer pageSize, Integer pageNumber,
 555             List<OrderHint> orderHints, List<String> propertyPaths, Direction direction);
 556
 557     /**
 558      * @param tnb
 559      * @return
 560      */
 561     public Taxon findBestMatchingTaxon(String taxonName);
 562
 563     public Taxon findBestMatchingTaxon(MatchingTaxonConfigurator config);
 564
 565     public Synonym findBestMatchingSynonym(String taxonName);
 566
 567     public List<UuidAndTitleCache<TaxonBase>> getUuidAndTitleCacheTaxon();
 568
 569     public List<UuidAndTitleCache<TaxonBase>> getUuidAndTitleCacheSynonym();
 570
 571     public List<UuidAndTitleCache<TaxonBase>> findTaxaAndNamesForEditor(ITaxonServiceConfigurator configurator);
 572
 573     /**
 574      * Creates the specified inferred synonyms for the taxon in the classification, but do not insert it to the database
 575      * @param taxon
 576      * @param tree
 577      * @return list of inferred synonyms
 578      */
 579     public List<Synonym> createInferredSynonyms(Taxon taxon, Classification tree, SynonymRelationshipType type, boolean doWithMisappliedNames);
 580
 581     /**
 582      * Creates all inferred synonyms for the taxon in the classification, but do not insert it to the database
 583      * @param taxon
 584      * @param tree
 585      * @param iDatabase
 586      * @return list of inferred synonyms
 587      */
 588     public List<Synonym>  createAllInferredSynonyms(Taxon taxon, Classification tree, boolean doWithMisappliedNames);
 589
 590
 591
 592
 593 }