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.EnumSet;
  15 import java.util.List;
  16 import java.util.Set;
  17 import java.util.UUID;
  18
  19 import org.apache.lucene.index.CorruptIndexException;
  20 import org.apache.lucene.queryparser.classic.ParseException;
  21
  22 import eu.etaxonomy.cdm.api.service.config.IFindTaxaAndNamesConfigurator;
  23 import eu.etaxonomy.cdm.api.service.config.IncludedTaxonConfiguration;
  24 import eu.etaxonomy.cdm.api.service.config.MatchingTaxonConfigurator;
  25 import eu.etaxonomy.cdm.api.service.config.SynonymDeletionConfigurator;
  26 import eu.etaxonomy.cdm.api.service.config.TaxonDeletionConfigurator;
  27 import eu.etaxonomy.cdm.api.service.dto.IdentifiedEntityDTO;
  28 import eu.etaxonomy.cdm.api.service.dto.IncludedTaxaDTO;
  29 import eu.etaxonomy.cdm.api.service.dto.MarkedEntityDTO;
  30 import eu.etaxonomy.cdm.api.service.exception.DataChangeNoRollbackException;
  31 import eu.etaxonomy.cdm.api.service.exception.HomotypicalGroupChangeException;
  32 import eu.etaxonomy.cdm.api.service.pager.Pager;
  33 import eu.etaxonomy.cdm.api.service.search.LuceneMultiSearchException;
  34 import eu.etaxonomy.cdm.api.service.search.SearchResult;
  35 import eu.etaxonomy.cdm.api.service.util.TaxonRelationshipEdge;
  36 import eu.etaxonomy.cdm.model.common.DefinedTerm;
  37 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  38 import eu.etaxonomy.cdm.model.common.Language;
  39 import eu.etaxonomy.cdm.model.common.MarkerType;
  40 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  41 import eu.etaxonomy.cdm.model.description.Feature;
  42 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTerm;
  43 import eu.etaxonomy.cdm.model.location.NamedArea;
  44 import eu.etaxonomy.cdm.model.media.Media;
  45 import eu.etaxonomy.cdm.model.media.MediaRepresentation;
  46 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  47 import eu.etaxonomy.cdm.model.name.Rank;
  48 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  49 import eu.etaxonomy.cdm.model.reference.Reference;
  50 import eu.etaxonomy.cdm.model.taxon.Classification;
  51 import eu.etaxonomy.cdm.model.taxon.Synonym;
  52 import eu.etaxonomy.cdm.model.taxon.SynonymType;
  53 import eu.etaxonomy.cdm.model.taxon.Taxon;
  54 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  55 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  56 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  57 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  58 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  59 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  60 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  61 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  62
  63
  64 public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{
  65
  66     /**
  67      * Returns a list of taxa that matches the name string and the sec reference
  68      * @param name the name string to search for
  69      * @param sec the taxons sec reference
  70      * @return a list of taxa matching the name and the sec reference
  71      */
  72     public List<TaxonBase> searchTaxaByName(String name, Reference sec);
  73
  74     /**
  75      * Swaps given synonym and accepted taxon.
  76      * In particular:
  77      * <ul>
  78      *          <li>A new accepted taxon with the synonyms name is created</li>
  79      *          <li>The synonym is deleted from the old accepted taxons synonym list</li>
  80      *          <li>A new synonym with the name of the old accepted taxon is created</li>
  81      *          <li>The newly created synonym get related to the newly created accepted taxon</li>
  82      * </ul>
  83      *
  84      * @param synonym
  85      * @param acceptedTaxon
  86      * @return
  87      */
  88     public UpdateResult swapSynonymAndAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
  89
  90     /**
  91      * Changes a synonym into an accepted taxon and removes
  92      * the synonym relationship to the given accepted taxon.
  93      * Other synonyms homotypic to the synonym to change are
  94      * moved to the same new accepted taxon as homotypic
  95      * synonyms. The new accepted taxon has the same name and
  96      * the same sec reference as the old synonym.<BR>
  97      * If the given accepted taxon and the synonym are homotypic
  98      * to each other an exception may be thrown as taxonomically it doesn't
  99      * make sense to have two accepted taxa in the same homotypic group
 100      * but also it is than difficult to decide how to handle other names
 101      * in the homotypic group. It is up to the implementing class to
 102      * handle this situation via an exception or in another way.
 103      *
 104      *
 105      * @param synonym
 106      *                          the synonym to change into an accepted taxon
 107      * @param acceptedTaxon
 108      *                          an accepted taxon, the synonym had a relationship to
 109      * @param deleteSynonym
 110      *                  if true the method tries to delete the old synonym from the database
 111      * @return
 112      *                  the newly created accepted taxon
 113      * @throws IllegalArgumentException
 114      *                  if the given accepted taxon and the synonym are homotypic
 115      *              to each other an exception may be thrown as taxonomically it doesn't
 116      *                  make sense to have two accepted taxa in the same homotypic group
 117      *          but also it is than difficult to decide how to handle other names
 118      *          in the homotypic group. It is up to the implementing class to
 119      *          handle this situation via an exception or in another way.
 120      */
 121     public Taxon changeSynonymToAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon, boolean deleteSynonym) throws HomotypicalGroupChangeException;
 122
 123     /**
 124      * @param synonymUuid
 125      * @param acceptedTaxonUuid
 126      * @param newParentNodeUuid
 127      * @param deleteSynonym
 128      * @return
 129      * @throws HomotypicalGroupChangeException
 130      */
 131     public UpdateResult changeSynonymToAcceptedTaxon(UUID synonymUuid, UUID acceptedTaxonUuid, UUID newParentNodeUuid,
 132             boolean deleteSynonym)
 133             throws HomotypicalGroupChangeException;
 134
 135     /**
 136      * TODO still needed and correct?
 137      * Change a synonym into a related concept
 138      *
 139      * @param synonym
 140      *                          the synonym to change into the concept taxon
 141      * @param toTaxon
 142      *                          the taxon the newly created concept should be related to
 143      * @param taxonRelationshipType
 144      *                          the type of relationship
 145      * @param reference
 146      * @param microReference
 147      * @return
 148      *                          the newly created concept
 149      */
 150     public Taxon changeSynonymToRelatedTaxon(Synonym synonym, Taxon toTaxon, TaxonRelationshipType taxonRelationshipType, Reference reference, String microReference);
 151
 152     /**
 153      * TODO still needed and correct?
 154      * Change a synonym into a related concept
 155      *
 156      * @param synonym
 157      *                          the synonym to change into the concept taxon
 158      * @param toTaxon
 159      *                          the taxon the newly created concept should be related to
 160      * @param taxonRelationshipType
 161      *                          the type of relationship
 162      * @param reference
 163      * @param microReference
 164      * @return
 165      *                          the newly created concept
 166      * @throws DataChangeNoRollbackException
 167      */
 168   public        Synonym changeRelatedTaxonToSynonym(Taxon fromTaxon, Taxon toTaxon,
 169              TaxonRelationshipType oldRelationshipType,
 170             SynonymType synonymType) throws DataChangeNoRollbackException;
 171
 172     /**
 173      * Changes the homotypic group of a synonym into the new homotypic group.
 174      * All relations to taxa are updated correctly depending on the homotypic
 175      * group of the accepted taxon. <BR>
 176      * All existing basionym relationships to and from this name are removed.<BR>
 177      * If the parameter <code>targetTaxon</code> is defined, the synonym is
 178      * added to this taxon irrespctive of if it has been related to this
 179      * taxon before.<BR>
 180      * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
 181      * between the existing basionym(s) of the new homotypic group and the synonyms name
 182      * is added.<BR>
 183      *
 184      * @param synonym
 185      * @param newHomotypicalGroup
 186      * @param taxon
 187      * @param setBasionymRelationIfApplicable
 188      */
 189     public void changeHomotypicalGroupOfSynonym(Synonym synonym, HomotypicalGroup newHomotypicalGroup,
 190             Taxon targetTaxon, boolean setBasionymRelationIfApplicable);
 191
 192     /**
 193      * See {@link #moveSynonymToAnotherTaxon(Synonym, Taxon, boolean, SynonymType, Reference, String, boolean)}
 194      * @param oldSynonym
 195      * @param newTaxon
 196      * @param moveHomotypicGroup
 197      * @param newSynonymType
 198      * @return
 199      * @throws HomotypicalGroupChangeException
 200      */
 201     public UpdateResult moveSynonymToAnotherTaxon(Synonym oldSynonym, Taxon newTaxon, boolean moveHomotypicGroup,
 202             SynonymType newSynonymType) throws HomotypicalGroupChangeException;
 203
 204
 205     /**
 206      * Moves a synonym to another taxon and removes the old synonym relationship.
 207      *
 208      * @param oldSynonym the old synonym to move.
 209      * @param newTaxon the taxon the synonym will be moved to
 210      * @param moveHomotypicGroup if the synonym belongs to a homotypic group with other synonyms and
 211      *          <code>moveHomotypicGroup</code> is <code>true</code> all these synonyms are moved to the new taxon,
 212      *          if <code>false</code> a {@link HomotypicalGroupChangeException} is thrown.
 213      *          <code>moveHomotypicGroup</code> has no effect if the synonym is the only synonym in it's homotypic group.
 214      * @param newSynonymType the synonym type of the new synonyms. Default is
 215      *          {@link SynonymType#HETEROTYPIC_SYNONYM_OF() heterotypic}.
 216      * @param newSecundum The secundum for the new synonyms).
 217      * @param newSecundumDetail The secundum micro reference for the new synonym(s).
 218      * @param keepSecundumIfUndefined if no <code>newSecundum</code> and/or no <code>newSecundumDetail</code>
 219      *          is defined they are taken from the old synonym(s) if <code>keepSecundumIfUndefined</code> is
 220      *          <code>true</code>. If <code>false</code> the secundum and the secundum detail will be taken
 221      *          only from the <code>newSecundum</code> and <code>newSecundumDetail</code> even if they are
 222      *      undefined (<code>null</code>).
 223      * @return The new synonym relationship. If <code>moveHomotypicGroup</code> is <code>true</code> additionally
 224      *          created new synonym relationships must be retrieved separately from the new taxon.
 225      * @throws HomotypicalGroupChangeException Exception is thrown if (1) synonym is homotypic to the old accepted taxon or
 226      *          (2) synonym is in homotypic group with other synonyms and <code>moveHomotypicGroup</code> is false
 227      */
 228     public UpdateResult moveSynonymToAnotherTaxon(Synonym oldSynonym, Taxon newTaxon, boolean moveHomotypicGroup,
 229             SynonymType newSynonymType, Reference newSecundum,
 230             String newSecundumDetail, boolean keepSecundumIfUndefined) throws HomotypicalGroupChangeException;
 231
 232
 233     /**
 234      * @param oldSynonym
 235      * @param newTaxonUUID
 236      * @param moveHomotypicGroup
 237      * @param newSynonymType
 238      * @param reference
 239      * @param referenceDetail
 240      * @param keepReference
 241      * @return
 242      * @throws HomotypicalGroupChangeException
 243      *
 244      * @see {@link #moveSynonymToAnotherTaxon(Synonym, Taxon, boolean, SynonymType, Reference, String, boolean)}
 245      */
 246     public UpdateResult moveSynonymToAnotherTaxon(Synonym oldSynonym,
 247             UUID newTaxonUUID, boolean moveHomotypicGroup,
 248             SynonymType newSynonymType,
 249             Reference newSecundum, String newSecundumDetail, boolean keepSecundumIfUndefined)
 250             throws HomotypicalGroupChangeException;
 251
 252     /**
 253      * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 254      * where the supplied taxon is relatedTo.
 255      *
 256      * @param taxon The taxon that is relatedTo
 257      * @param type The type of TaxonRelationship (can be null)
 258      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 259      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 260      * @param orderHints Properties to order by
 261      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 262      * @return a List of TaxonRelationship instances
 263      */
 264     public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 265
 266
 267
 268     /**
 269      * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
 270      * where the supplied taxon is relatedTo.
 271      *
 272      * @param taxon The taxon that is relatedTo
 273      * @param type The type of TaxonRelationship (can be null)
 274      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 275      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 276      * @param orderHints Properties to order by
 277      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 278      * @return a Pager of TaxonRelationship instances
 279      */
 280     public Pager<TaxonRelationship> pageToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 281
 282     /**
 283      * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 284      * where the supplied taxon is relatedFrom.
 285      *
 286      * @param taxon The taxon that is relatedFrom
 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 IBeanInitializer#initialize(Object, List)}
 292      * @return a List of TaxonRelationship instances
 293      */
 294     public List<TaxonRelationship> listFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 295
 296
 297     /**
 298      * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
 299      * where the supplied taxon is relatedFrom.
 300      *
 301      * @param taxon The taxon that is relatedFrom
 302      * @param type The type of TaxonRelationship (can be null)
 303      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 304      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 305      * @param orderHints Properties to order by
 306      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 307      * @return a Pager of TaxonRelationship instances
 308      */
 309     public Pager<TaxonRelationship> pageFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 310
 311     /**
 312      * lists all taxa which are related to the <code>taxon</code> given as
 313      * parameter.
 314      *
 315      * @param taxon
 316      * @param includeRelationships
 317      * @param maxDepth
 318      *            <code>1</code> for one level, <code>null</code> for infinite
 319      *            depth, <code>0</code> will completely omit collecting related taxa.
 320      * @param limit
 321      * @param start
 322      * @param propertyPaths
 323      * @return
 324      */
 325     public Set<Taxon> listRelatedTaxa(Taxon taxon, Set<TaxonRelationshipEdge> includeRelationships, Integer maxDepth,
 326             Integer limit, Integer start, List<String> propertyPaths);
 327
 328     /**
 329      * Lists all classifications the given taxon/synonym is used in{@link Synonym}
 330      *
 331      * @param taxonBase
 332      * @param limit
 333      * @param start
 334      * @param propertyPaths
 335      * @return
 336      */
 337     public List<Classification> listClassifications(TaxonBase taxonBase, Integer limit, Integer start, List<String> propertyPaths);
 338
 339     /**
 340      * Returns the Synonyms (with the given synonym relationship type, if this argument is supplied)
 341      * that do have the supplied taxon as accepted taxon.
 342      *
 343      * @param taxon The accepted taxon
 344      * @param type The type of Synonym (can be null)
 345      * @param pageSize The maximum number of synonyms returned (can be null for returning synonyms)
 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 IBeanInitializer#initialize(Object, List)}
 349      * @return a Pager of {@link Synonym} instances
 350      */
 351     public Pager<Synonym> getSynonyms(Taxon taxon, SynonymType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 352
 353     /**
 354      * This method returns in the first entry the list of synonyms of the
 355      * homotypic group of the accepted taxon. All other entries represent the lists of heterotypic
 356      * synonym groups. For detailed information about these 2 groups see
 357      * {@link #getHomotypicSynonymsByHomotypicGroup(Taxon, List)} and
 358      * {@link #getHeterotypicSynonymyGroups(Taxon, List)}
 359      *
 360      * @see                     #getSynonyms()
 361      * @see                     SynonymType#HETEROTYPIC_SYNONYM_OF()
 362      * @see                     eu.etaxonomy.cdm.model.name.HomotypicalGroup
 363
 364      * @param taxon the accepted taxon
 365      * @param propertyPaths the property path
 366      * @return the list of groups of synonyms
 367      */
 368     public List<List<Synonym>> getSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
 369
 370
 371     /**
 372      * Returns the list of all synonyms that share the same homotypical group with the given taxon.
 373      * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
 374      * @param taxon
 375      * @param propertyPaths
 376      * @return
 377      */
 378     public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
 379
 380     /**
 381      * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
 382      * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
 383      * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
 384      * belong to a homotypical group which cannot be the homotypical group to which the
 385      * taxon name of the given taxon belongs. This method does not return the homotypic group the given
 386      * taxon belongs to.<BR>
 387      * This method does neglect the type of synonym relationship that is defined between the given taxon
 388      * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
 389      * in one of the result lists as long as the synonym does not belong to the same homotypic group as
 390      * the given taxon.<BR>
 391      * The list returned is ordered according to the date of publication of the
 392      * first published name within each homotypical group.
 393      *
 394      * @see                     #getHeterotypicSynonymyGroups()
 395      * @see                     #getSynonyms()
 396      * @see                     SynonymType#HETEROTYPIC_SYNONYM_OF()
 397      * @see                     eu.etaxonomy.cdm.model.name.HomotypicalGroup
 398
 399      * @param taxon
 400      * @param propertyPaths
 401      * @return
 402      */
 403     public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
 404
 405     /**
 406      * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 407      *
 408      * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
 409      * @param queryString
 410      * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 411      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 412      * @param orderHints
 413      *            Supports path like <code>orderHints.propertyNames</code> which
 414      *            include *-to-one properties like createdBy.username or
 415      *            authorTeam.persistentTitleCache
 416      * @param propertyPaths properties to be initialized
 417      * @return a Pager Taxon instances
 418      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 419      */
 420     @Override
 421     public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 422
 423     /**
 424      * Returns a list of TaxonBase instances where the
 425      * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 426      * <i>null</i> will search for those taxa with a value of null in that field
 427      *
 428      * @param clazz optionally filter by class (can be null to return all taxa)
 429      * @param uninomial
 430      * @param infragenericEpithet
 431      * @param specificEpithet
 432      * @param infraspecificEpithet
 433      * @param rank
 434      * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 435      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 436      * @return a list of TaxonBase instances
 437      */
 438     public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, String authorship, Rank rank, Integer pageSize, Integer pageNumber);
 439
 440     /**
 441      * Returns a list of TaxonBase instances where the
 442      * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 443      * <i>null</i> will search for those taxa with a value of null in that field
 444      *
 445      * @param clazz optionally filter by class
 446      * @param uninomial
 447      * @param infragenericEpithet
 448      * @param specificEpithet
 449      * @param infraspecificEpithet
 450      * @param rank
 451      * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 452      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 453      * @return a List of TaxonBase instances
 454      */
 455     public List<TaxonBase> listTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, String authorship, Rank rank, Integer pageSize, Integer pageNumber);
 456
 457     /**
 458      * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
 459      * that match the properties specified in the configurator.
 460      * @param configurator
 461      * @return
 462      */
 463     public Pager<IdentifiableEntity> findTaxaAndNames(IFindTaxaAndNamesConfigurator configurator);
 464
 465     /**
 466      * performes a union searches for TaxonBase instances on all available
 467      * free text indexes. At the time of writing this documentation it combines
 468      * {@link #findByDescriptionElementFullText(Class, String, Classification, List, List, boolean, Integer, Integer, List, List)}
 469      * and {@link #findByFullText(Class, String, Classification, List, boolean, Integer, Integer, List, List)
 470      *
 471      * @param queryString
 472      *            the query string
 473      * @param classification
 474      *            Additional filter criterion: If a taxonomic classification
 475      *            three is specified here the result set will only contain taxa
 476      *            of the given classification
 477      * @param languages
 478      *            Additional filter criterion: Search only in these languages.
 479      *            Not all text fields in the cdm model are multilingual, thus
 480      *            this setting will only apply to the multilingiual fields.
 481      *            Other fields are searched nevertheless if this parameter is
 482      *            set or not.
 483      * @param highlightFragments
 484      *            TODO
 485      * @param pageSize
 486      *            The maximum number of objects returned (can be null for all
 487      *            objects)
 488      * @param pageNumber
 489      *            The offset (in pageSize chunks) from the start of the result
 490      *            set (0 - based)
 491      * @param orderHints
 492      *            Supports path like <code>orderHints.propertyNames</code> which
 493      *            include *-to-one properties like createdBy.username or
 494      *            authorTeam.persistentTitleCache
 495      * @param propertyPaths
 496      *            properties to initialize - see
 497      *            {@link IBeanInitializer#initialize(Object, List)}
 498      * @return a paged list of instances of type T matching the queryString and
 499      *         the additional filter criteria
 500      * @return
 501      * @throws CorruptIndexException
 502      * @throws IOException
 503      * @throws ParseException
 504      * @throws LuceneMultiSearchException
 505      * @deprecated this search should fully be covered by the new method
 506      *      {@link #findTaxaAndNamesByFullText(EnumSet, String, Classification, Set, List, boolean, Integer, Integer, List, List)}
 507      *      , maybe we should rename this latter method to give it a more meaningful name
 508      */
 509     @Deprecated
 510     public Pager<SearchResult<TaxonBase>> findByEverythingFullText(String queryString,
 511             Classification classification, List<Language> languages, boolean highlightFragments,
 512             Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException, LuceneMultiSearchException;
 513
 514     /**
 515      * Searches for TaxonBase instances using the TaxonBase free text index.
 516      *
 517      * <h4>This is an experimental feature, it may be moved, modified, or even
 518      * removed in future releases!!!</h4>
 519      *
 520      * @param clazz
 521      *            Additional filter criterion: The specific TaxonBase subclass
 522      *            to search for
 523      * @param queryString
 524      *            the query string
 525      * @param classification
 526      *            Additional filter criterion: If a taxonomic classification
 527      *            three is specified here the result set will only contain taxa
 528      *            of the given classification
 529      * @param languages
 530      *            Additional filter criterion: Search only in these languages.
 531      *            Not all text fields in the cdm model are multilingual, thus
 532      *            this setting will only apply to the multilingiual fields.
 533      *            Other fields are searched nevertheless if this parameter is
 534      *            set or not.
 535      * @param highlightFragments
 536      *            TODO
 537      * @param pageSize
 538      *            The maximum number of objects returned (can be null for all
 539      *            objects)
 540      * @param pageNumber
 541      *            The offset (in pageSize chunks) from the start of the result
 542      *            set (0 - based)
 543      * @param orderHints
 544      *            Supports path like <code>orderHints.propertyNames</code> which
 545      *            include *-to-one properties like createdBy.username or
 546      *            authorTeam.persistentTitleCache
 547      * @param propertyPaths
 548      *            properties to initialize - see
 549      *            {@link IBeanInitializer#initialize(Object, List)}
 550      * @return a paged list of instances of type T matching the queryString and
 551      *         the additional filter criteria
 552      * @throws CorruptIndexException
 553      * @throws IOException
 554      * @throws ParseException
 555      */
 556     public Pager<SearchResult<TaxonBase>> findByFullText(Class<? extends TaxonBase> clazz, String queryString, Classification classification,
 557             List<Language> languages, boolean highlightFragments, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints,
 558             List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException;
 559
 560
 561     /**
 562      * @param areaFilter
 563      * @param statusFilter
 564      * @param classification
 565      *            Additional filter criterion: If a taxonomic classification
 566      *            three is specified here the result set will only contain taxa
 567      *            of the given classification
 568      * @param highlightFragments
 569      * @param pageSize
 570      *            The maximum number of objects returned (can be null for all
 571      *            objects)
 572      * @param pageNumber
 573      *            The offset (in pageSize chunks) from the start of the result
 574      *            set (0 - based)
 575      * @param orderHints
 576      *            Supports path like <code>orderHints.propertyNames</code> which
 577      *            include *-to-one properties like createdBy.username or
 578      *            authorTeam.persistentTitleCache
 579      * @param propertyPath
 580      *            Common properties to initialize the instances of the
 581      *            CDM types ({@link Taxon} and {@link Synonym}
 582      *            this method can return - see {@link IBeanInitializer#initialize(Object, List)}
 583      * @return a paged list of instances of {@link Taxon} instances
 584      * @throws IOException
 585      * @throws ParseException
 586      */
 587     public Pager<SearchResult<TaxonBase>> findByDistribution(List<NamedArea> areaFilter, List<PresenceAbsenceTerm> statusFilter,
 588             Classification classification,
 589             Integer pageSize, Integer pageNumber,
 590             List<OrderHint> orderHints, List<String> propertyPaths) throws IOException, ParseException;
 591
 592     /**
 593      * Searches for TaxonBase instances using the TaxonBase free text index.
 594      *
 595      *
 596      *
 597      * <h4>This is an experimental feature, it may be moved, modified, or even
 598      * removed in future releases!!!</h4>
 599      * @param searchModes
 600      *            Additional filter criterion: defaults to [doTaxa] if set null
 601      * @param queryString
 602      *            the query string
 603      * @param classification
 604      *            Additional filter criterion: If a taxonomic classification
 605      *            three is specified here the result set will only contain taxa
 606      *            of the given classification
 607      * @param namedAreas
 608      * @param languages
 609      *            Additional filter criterion: Search only in these languages.
 610      *            Not all text fields in the cdm model are multilingual, thus
 611      *            this setting will only apply to the multilingiual fields.
 612      *            Other fields are searched nevertheless if this parameter is
 613      *            set or not.
 614      * @param highlightFragments
 615      *            TODO
 616      * @param pageSize
 617      *            The maximum number of objects returned (can be null for all
 618      *            objects)
 619      * @param pageNumber
 620      *            The offset (in pageSize chunks) from the start of the result
 621      *            set (0 - based)
 622      * @param orderHints
 623      *            Supports path like <code>orderHints.propertyNames</code> which
 624      *            include *-to-one properties like createdBy.username or
 625      *            authorTeam.persistentTitleCache
 626      * @param propertyPath
 627      *            Common properties to initialize the instances of the
 628      *            CDM types ({@link Taxon} and {@link Synonym}
 629      *            this method can return - see {@link IBeanInitializer#initialize(Object, List)}
 630      * @return a paged list of instances of {@link Taxon}, {@link Synonym}, matching the queryString and
 631      *         the additional filter criteria
 632      * @throws CorruptIndexException
 633      * @throws IOException
 634      * @throws ParseException
 635      * @throws LuceneMultiSearchException
 636      */
 637     public Pager<SearchResult<TaxonBase>> findTaxaAndNamesByFullText(
 638             EnumSet<TaxaAndNamesSearchMode> searchModes,
 639             String queryString, Classification classification, Set<NamedArea> namedAreas, Set<PresenceAbsenceTerm> distributionStatus,
 640             List<Language> languages, boolean highlightFragments, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints,
 641             List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException, LuceneMultiSearchException;
 642
 643     /**
 644      * Searches for TaxonBase instances by using the DescriptionElement free text index.
 645      *
 646      * <h4>This is an experimental feature, it may be moved, modified, or even
 647      * removed in future releases!!!</h4>
 648      *
 649      * @param clazz
 650      *            Additional filter criterion:
 651      * @param queryString
 652      *            the query string to filter by
 653      * @param classification
 654      *            Additional filter criterion: If a taxonomic classification
 655      *            three is specified here the result set will only contain taxa
 656      *            of the given classification
 657      * @param features
 658      *            TODO
 659      * @param languages
 660      *            Additional filter criterion: Search only in these languages.
 661      *            Not all text fields in the cdm model are multilingual, thus
 662      *            this setting will only apply to the multilingiual fields.
 663      *            Other fields are searched nevertheless if this parameter is
 664      *            set or not.
 665      * @param highlightFragments
 666      *            TODO
 667      * @param pageSize
 668      *            The maximum number of objects returned (can be null for all
 669      *            objects)
 670      * @param pageNumber
 671      *            The offset (in pageSize chunks) from the start of the result
 672      *            set (0 - based)
 673      * @param orderHints
 674      *            Supports path like <code>orderHints.propertyNames</code> which
 675      *            include *-to-one properties like createdBy.username or
 676      *            authorTeam.persistentTitleCache
 677      * @param propertyPaths
 678      *            properties to initialize - see
 679      *            {@link IBeanInitializer#initialize(Object, List)}
 680      * @return a paged list of instances of type T matching the queryString and
 681      *         the additional filter criteria
 682      * @throws IOException
 683      * @throws CorruptIndexException
 684      * @throws ParseException
 685      */
 686     public Pager<SearchResult<TaxonBase>> findByDescriptionElementFullText(Class<? extends DescriptionElementBase> clazz, String queryString, Classification classification, List<Feature> features, List<Language> languages, boolean highlightFragments, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException, IOException, ParseException;
 687
 688
 689     /**
 690      *
 691      * @param taxon
 692      * @param size
 693      * @param height
 694      * @param widthOrDuration
 695      * @param mimeTypes
 696      * @return
 697      *
 698      * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
 699      */
 700     @Deprecated
 701     public List<MediaRepresentation> getAllMedia(Taxon taxon, int size, int height, int widthOrDuration, String[] mimeTypes);
 702
 703
 704     /**
 705      * Lists all Media found in an any TaxonDescription associated with this
 706      * taxon.
 707      *
 708      * @param taxon
 709      * @param includeRelationships
 710      *            the given list of TaxonRelationshipEdges will be taken into
 711      *            account when retrieving media associated with the given taxon.
 712      *            Can be NULL.
 713      * @param limitToGalleries
 714      *            whether to take only TaxonDescription into account which are
 715      *            marked as gallery
 716      * @return
 717      * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
 718      */
 719     @Deprecated
 720     public List<Media> listTaxonDescriptionMedia(Taxon taxon, Set<TaxonRelationshipEdge> includeRelationships, boolean limitToGalleries, List<String> propertyPath);
 721
 722     /**
 723      * Lists all Media found in an any TaxonDescription, NameDescription,
 724      * SpecimenOrObservationBase, DnaSample Chromatograms, etc. associated with this taxon.
 725      *
 726      * @param taxon
 727      * @param includeRelationships
 728      *            the given list of TaxonRelationshipEdges will be taken into
 729      *            account when retrieving media associated with the given taxon.
 730      *            Can be NULL.
 731      * @param limitToGalleries
 732      *            whether to take only descriptions into account which are
 733      *            marked as gallery, can be NULL
 734      * @param includeTaxonDescriptions
 735      *            whether to take TaxonDescriptions into account, can be NULL
 736      * @param includeOccurrences
 737      *          whether to take TaxonDescriptions into account, can be NULL
 738      * @param includeTaxonNameDescriptions
 739      *       whether to take TaxonNameDescriptions into account, can be NULL
 740      * @param propertyPath
 741      * @return
 742      */
 743     public List<Media> listMedia(Taxon taxon, Set<TaxonRelationshipEdge> includeRelationships,
 744             Boolean limitToGalleries, Boolean includeTaxonDescriptions, Boolean includeOccurrences,
 745             Boolean includeTaxonNameDescriptions, List<String> propertyPath);
 746
 747     public List<TaxonBase> findTaxaByID(Set<Integer> listOfIDs);
 748
 749     /**
 750      * Returns the TaxonBase with the given UUID
 751      * using the given match mode and initialization strategy
 752      *
 753      * @param uuid
 754      * @param propertyPaths
 755      * @return
 756      */
 757     public TaxonBase findTaxonByUuid(UUID uuid, List<String> propertyPaths);
 758
 759     /**
 760      * Counts the number of synonyms
 761      * @param onlyAttachedToTaxon if <code>true</code> only those synonyms being attached to
 762      * an accepted taxon are counted
 763      * @return the number of synonyms
 764      */
 765     public int countSynonyms(boolean onlyAttachedToTaxon);
 766
 767     public List<TaxonNameBase> findIdenticalTaxonNames(List<String> propertyPath);
 768
 769     public List<TaxonNameBase> findIdenticalTaxonNameIds(List<String> propertyPath);
 770 //
 771 //    public String getPhylumName(TaxonNameBase name);
 772
 773     /**
 774      * Returns all {@link Taxon taxa} which are {@link TaxonRelationshipType#CONGRUENT_TO() congruent} or
 775      * {@link TaxonRelationshipType#INCLUDES() included} in the taxon represented by the given taxon uuid.
 776      * The result also returns the path to these taxa represented by the uuids of
 777      * the {@link TaxonRelationshipType taxon relationships types} and doubtful information.
 778      * If classificationUuids is set only taxa of classifications are returned which are included
 779      * in the given {@link Classification classifications}. ALso the path to these taxa may not include
 780      * taxa from other classifications.
 781      * @param taxonUuid uuid of the original taxon
 782      * @param classificationUuids List of uuids of classifications used as a filter
 783      * @param includeDoubtful set to <code>true</code> if also doubtfully included taxa should be included in the result
 784      * @return a DTO which includes a list of taxa with the pathes from the original taxon to the given taxon as well
 785      * as doubtful and date information. The original taxon is included in the result.
 786      */
 787     public IncludedTaxaDTO listIncludedTaxa(UUID taxonUuid, IncludedTaxonConfiguration configuration);
 788
 789
 790    /**
 791      * Removes a synonym.<BR><BR>
 792      *
 793      * In detail it removes
 794      *  <li>the synonym concept</li>
 795      *  <BR><BR>
 796      *  If <code>removeNameIfPossible</code> is true
 797      *  it also removes the synonym name if it is not used in any other context
 798      *  (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
 799      *  If <code>newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name
 800      *  is not deleted and the name is homotypic to the taxon
 801      *  the name is moved to a new homotypic group.<BR><BR>
 802      *
 803      *  If synonym is <code>null</code> the method has no effect.
 804      *
 805      * @param taxon
 806      * @param synonym
 807      * @param removeNameIfPossible
 808      * @return deleteResult
 809      *
 810      */
 811     public DeleteResult deleteSynonym(Synonym synonym, SynonymDeletionConfigurator config);
 812
 813     /**
 814      * Removes a synonym.
 815      *
 816      * The method essentially loads the synonym and calls the
 817      * {@link #deleteSynonym(Synonym, SynonymDeletionConfigurator) deleteSynonym} method
 818      *
 819      * @param synonymUuid
 820      * @param config
 821      * @return
 822      */
 823     public DeleteResult deleteSynonym(UUID synonymUuid, SynonymDeletionConfigurator config);
 824
 825     /**
 826      * @param tnb
 827      * @return
 828      */
 829     public Taxon findBestMatchingTaxon(String taxonName);
 830
 831     public Taxon findBestMatchingTaxon(MatchingTaxonConfigurator config);
 832
 833     public Synonym findBestMatchingSynonym(String taxonName);
 834
 835      public List<UuidAndTitleCache<IdentifiableEntity>> findTaxaAndNamesForEditor(IFindTaxaAndNamesConfigurator configurator);
 836
 837     /**
 838      * Creates the specified inferred synonyms for the taxon in the classification, but do not insert it to the database
 839      * @param taxon
 840      * @param tree
 841      * @return list of inferred synonyms
 842      */
 843     public List<Synonym> createInferredSynonyms(Taxon taxon, Classification tree, SynonymType type, boolean doWithMisappliedNames);
 844
 845     /**
 846      * Creates all inferred synonyms for the taxon in the classification, but do not insert it to the database
 847      * @param taxon
 848      * @param tree
 849      * @param iDatabase
 850      * @return list of inferred synonyms
 851      */
 852     public List<Synonym>  createAllInferredSynonyms(Taxon taxon, Classification tree, boolean doWithMisappliedNames);
 853
 854     public Taxon findAcceptedTaxonFor(UUID synonymUuid, UUID classificationUuid, List<String> propertyPaths);
 855
 856     public List<TaxonBase> findTaxaByName(MatchingTaxonConfigurator config);
 857
 858
 859     /**
 860      * @param clazz the optional {@link TaxonBase} subclass
 861      * @param identifier the identifier string
 862      * @param identifierType the identifier type
 863      * @param subtreeFilter filter on a classification subtree (TaxonNode)
 864      * @param matchmode the match mode for the identifier string
 865      * @param includeEntity should the taxon as an object be included in the result
 866      * @param pageSize page size
 867      * @param pageNumber page number
 868      * @param propertyPaths property path for initializing the returned taxon object (requires includeEntity=true)
 869      * @return the resulting {@link IdentifiedEntityDTO} pager
 870      * @see IIdentifiableEntityService#findByIdentifier(Class, String, DefinedTerm, MatchMode, boolean, Integer, Integer, List)
 871      */
 872     public <S extends TaxonBase> Pager<IdentifiedEntityDTO<S>> findByIdentifier(
 873                         Class<S> clazz, String identifier, DefinedTerm identifierType, TaxonNode subtreeFilter,
 874                         MatchMode matchmode, boolean includeEntity, Integer pageSize,
 875                         Integer pageNumber,     List<String> propertyPaths);
 876
 877     /**
 878      * Returns a pager for {@link MarkedEntityDTO DTOs} that hold the marker including type, title and uuid
 879      * and the according {@link TaxonBase} information (uuid, title and the taxon object itself (optional)).
 880      *
 881      * @param clazz The optional {@link TaxonBase} subclass
 882      * @param markerType the obligatory marker type, if not given, the results will always be empty
 883      * @param markerValue the optional
 884      * @param subtreeFilter filter on a classification subtree (TaxonNode)
 885      * @param includeEntity should the taxon as an object be included in the result
 886      * @param pageSize page size
 887      * @param pageNumber page number
 888      * @param propertyPaths property path for initializing the returned taxon object (requires includeEntity=true)
 889      * @return the resulting {@link MarkedEntityDTO} pager
 890      * @see IIdentifiableEntityService#findByMarker(Class, MarkerType, Boolean, boolean, Integer, Integer, List)
 891      */
 892     public <S extends TaxonBase> Pager<MarkedEntityDTO<S>> findByMarker(
 893             Class<S> clazz, MarkerType markerType, Boolean markerValue,
 894             TaxonNode subtreeFilter, boolean includeEntity, Integer pageSize,
 895             Integer pageNumber, List<String> propertyPaths);
 896
 897     /**
 898      * @param synonymUUid
 899      * @param acceptedTaxonUuid
 900      * @return
 901      */
 902     public UpdateResult swapSynonymAndAcceptedTaxon(UUID synonymUUid, UUID acceptedTaxonUuid);
 903
 904     /**
 905      * @param taxonUuid
 906      * @param config
 907      * @param classificationUuid
 908      * @return
 909      */
 910     public DeleteResult deleteTaxon(UUID taxonUuid, TaxonDeletionConfigurator config, UUID classificationUuid);
 911
 912
 913         public UpdateResult moveFactualDateToAnotherTaxon(UUID fromTaxonUuid,
 914                         UUID toTaxonUuid);
 915
 916
 917     /**
 918      * @param synonymUuid
 919      * @param toTaxonUuid
 920      * @param taxonRelationshipType
 921      * @param citation
 922      * @param microcitation
 923      * @return
 924      */
 925     public UpdateResult changeSynonymToRelatedTaxon(UUID synonymUuid, UUID toTaxonUuid, TaxonRelationshipType taxonRelationshipType,
 926             Reference citation, String microcitation);
 927
 928     /**
 929      * @param fromTaxonUuid
 930      * @param toTaxonUuid
 931      * @param oldRelationshipType
 932      * @param synonymType
 933      * @return
 934      * @throws DataChangeNoRollbackException
 935      */
 936     public UpdateResult changeRelatedTaxonToSynonym(UUID fromTaxonUuid, UUID toTaxonUuid,
 937             TaxonRelationshipType oldRelationshipType, SynonymType synonymType) throws DataChangeNoRollbackException;
 938
 939
 940
 941
 942
 943
 944
 945
 946 }