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