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