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