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