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