cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/ITaxonService.java

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