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