cdmlib-persistence/src/main/java/eu/etaxonomy/cdm/persistence/dao/taxon/ITaxonDao.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.persistence.dao.taxon;
  11
  12 import java.util.List;
  13 import java.util.Set;
  14 import java.util.UUID;
  15
  16 import org.hibernate.criterion.Criterion;
  17
  18 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  19 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  20 import eu.etaxonomy.cdm.model.common.RelationshipBase.Direction;
  21 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  22 import eu.etaxonomy.cdm.model.location.NamedArea;
  23 import eu.etaxonomy.cdm.model.name.Rank;
  24 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  25 import eu.etaxonomy.cdm.model.reference.Reference;
  26 import eu.etaxonomy.cdm.model.taxon.Classification;
  27 import eu.etaxonomy.cdm.model.taxon.Synonym;
  28 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  29 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  30 import eu.etaxonomy.cdm.model.taxon.Taxon;
  31 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  32 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  33 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  34 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  35 import eu.etaxonomy.cdm.persistence.dao.common.IIdentifiableDao;
  36 import eu.etaxonomy.cdm.persistence.dao.common.ITitledDao;
  37 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  38 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  39 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  40 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  41
  42 /**
  43  * @author a.mueller
  44  *
  45  */
  46 public interface ITaxonDao extends IIdentifiableDao<TaxonBase>, ITitledDao<TaxonBase> {
  47
  48     /**
  49      * Returns a list of TaxonBase instances where the taxon.titleCache property matches the name parameter,
  50      * and taxon.sec matches the sec parameter.
  51      * @param name
  52      * @param sec
  53      * @return
  54      */
  55     public List<TaxonBase> getTaxaByName(String name, Reference sec);
  56
  57     /**
  58      * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  59      * where the taxonBase.name.nameCache property matches the String queryString, and taxon.sec matches the sec parameter.
  60      * @param name
  61      * @param sec
  62      * @return
  63      */
  64     public List<TaxonBase> getTaxaByName(String queryString, Boolean accepted, Reference sec);
  65
  66     /**
  67      * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  68      * where the taxonBase.name.nameCache property matches the String queryString.
  69      * @param queryString
  70      * @param matchMode
  71      * @param accepted
  72      * @param pageSize
  73      * @param pageNumber
  74      * @return
  75      */
  76     public List<TaxonBase> getTaxaByName(String queryString, MatchMode matchMode,
  77             Boolean accepted, Integer pageSize, Integer pageNumber);
  78
  79
  80     /**
  81      * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  82      * where the taxonBase.name.nameCache property matches the String queryString.
  83      * @param doTaxa
  84      * @param doSynonyms
  85      * @param queryString
  86      * @param classification TODO
  87      * @param matchMode
  88      * @param namedAreas TODO
  89      * @param pageSize
  90      * @param pageNumber
  91      * @param propertyPaths TODO
  92      * @return list of found taxa
  93      */
  94     public List<TaxonBase> getTaxaByName(boolean doTaxa, boolean doSynonyms, boolean doMisappliedNames, String queryString, Classification classification,
  95             MatchMode matchMode, Set<NamedArea> namedAreas, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  96
  97     /**
  98      * @param doTaxa
  99      * @param doSynonyms
 100      * @param queryString
 101      * @param classification TODO
 102      * @param matchMode
 103      * @param namedAreas
 104      * @param pageSize
 105      * @param pageNumber
 106      * @param propertyPaths
 107      * @return
 108      */
 109     public long countTaxaByName(boolean doTaxa, boolean doSynonyms, boolean doMisappliedNames, String queryString, Classification classification,
 110
 111             MatchMode matchMode, Set<NamedArea> namedAreas);
 112
 113 //      /**
 114 //       * @param queryString
 115 //       * @param matchMode
 116 //       * @param accepted
 117 //       * @return
 118 //       */
 119 //      public Integer countTaxaByName(String queryString, MatchMode matchMode,
 120 //                      Boolean accepted);
 121
 122 //      /**
 123 //       * Returns a count of TaxonBase instances where the
 124 //       * taxon.name properties match the parameters passed.
 125 //       *
 126 //       * @param queryString search string
 127 //       * @param matchMode way how search string shall be matched: exact, beginning, or anywhere
 128 //       * @param selectModel all taxon base, taxa, or synonyms
 129 //       */
 130 //      public Integer countTaxaByName(String queryString, MatchMode matchMode, SelectMode selectMode);
 131
 132     /**
 133      * Returns a count of TaxonBase instances where the
 134      * taxon.name properties match the parameters passed.
 135      *
 136      * @param doTaxa
 137      * @param doSynonyms
 138      * @param uninomial
 139      * @param infragenericEpithet
 140      * @param specificEpithet
 141      * @param infraspecificEpithet
 142      * @param rank
 143      * @return a count of TaxonBase instances
 144      */
 145     public int countTaxaByName(Class <? extends TaxonBase> clazz, String uninomial, String infragenericEpithet,String specificEpithet, String infraspecificEpithet, Rank rank);
 146
 147     /**
 148      * Returns a list of TaxonBase instances where the
 149      * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 150      * <i>null</i> will search for those taxa with a value of null in that field
 151      * <p>
 152      * Compare with
 153      * {@link #findByName(String, MatchMode, int, int, boolean)}
 154      * which searches for {@link TaxonNameBase}<strong><code>.titleCache</code>
 155      * </strong>
 156      *
 157      * @param doTaxa
 158      * @param doSynonyms
 159      * @param uninomial
 160      * @param infragenericEpithet
 161      * @param specificEpithet
 162      * @param infraspecificEpithet
 163      * @param rank
 164      * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 165      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 166      * @return a list of TaxonBase instances
 167      */
 168     public List<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 169
 170     /**
 171      * Find taxa by searching for Taxa and Synonyms where the
 172      * {@link TaxonNameBase}<strong><code>.titleCache</code></strong> matches
 173      * the name specified as queryString <code>taxonName</code>
 174      * <P>
 175      * Compare with
 176      * {@link #findTaxaByName(Class, String, String, String, String, Rank, Integer, Integer)}
 177      * which searches for {@link TaxonNameBase}<strong><code>.nameCache</code>
 178      * </strong>
 179      * @param queryString
 180      *            the taqxon Name to search for
 181      * @param classification TODO
 182      * @param matchMode
 183      * @param namedAreas TODO
 184      * @param pageNumber
 185      * @param pageSize
 186      * @param onlyAcccepted
 187      * @return
 188      */
 189     public List<TaxonBase> findByNameTitleCache(boolean doTaxa, boolean doSynonyms, String queryString, Classification classification, MatchMode matchMode, Set<NamedArea> namedAreas, Integer pageNumber, Integer pageSize, List<String> propertyPaths) ;
 190
 191     /**
 192      * Returns a taxon corresponding to the given uuid
 193      *
 194      * @param uuid
 195      *                  The uuid of the taxon requested
 196      * @param criteria
 197      *                  Custom criteria to be added to the default list of applied criteria.
 198      * @param propertyPaths
 199      *
 200      * @return
 201      */
 202     public TaxonBase findByUuid(UUID uuid, List<Criterion> criteria, List<String> propertyPaths);
 203
 204     /**
 205      * Returns a list of Taxon entities corresponding to the given uuid list.
 206      * @param uuids
 207      * @param criteria
 208      * @param propertyPaths
 209      * @return
 210      */
 211     public List<? extends TaxonBase> findByUuids(List<UUID> uuids, List<Criterion> criteria, List<String> propertyPaths);
 212
 213     /**
 214      * @param queryString
 215      * @param classification
 216      * @param matchMode
 217      * @param namedAreas
 218      * @param pageSize
 219      * @param pageNumber
 220      * @param propertyPaths
 221      * @return A List matching Taxa
 222      */
 223     public List<Taxon> getTaxaByCommonName(String queryString, Classification classification,
 224     MatchMode matchMode, Set<NamedArea> namedAreas, Integer pageSize,
 225     Integer pageNumber, List<String> propertyPaths);
 226
 227
 228     /**
 229      * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
 230      * @return The List<Taxon> of root taxa.
 231      * @deprecated obsolete when using classification
 232      */
 233     @Deprecated
 234     public List<Taxon> getRootTaxa(Reference sec);
 235
 236
 237     /**
 238      * Computes all Taxon instances that do not have a taxonomic parent.
 239      * @param sec The concept reference that the taxon belongs to
 240      * @param cdmFetch not used yet !! TODO
 241      * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 242      * @param withMisaplications if false only taxa are returned that have no isMisappliedNameFor relationship.
 243      * <Br>Default: true.
 244      * @return The List<Taxon> of root taxa.
 245      * @deprecated obsolete when using classification
 246      */
 247     @Deprecated
 248     public List<Taxon> getRootTaxa(Reference sec, CdmFetch cdmFetch, Boolean onlyWithChildren, Boolean withMisapplications);
 249
 250
 251     /**
 252      * Computes all Taxon instances which name is of a certain Rank.
 253      *
 254      * @param rank
 255      *            The rank of the taxon name
 256      * @param sec
 257      *            The concept reference that the taxon belongs to
 258      * @param cdmFetch
 259      *            not used yet !! TODO
 260      * @param onlyWithChildren
 261      *            if true only taxa are returned that have taxonomic children. <Br>
 262      *            Default: true.
 263      * @param withMisaplications
 264      *            if false only taxa are returned that have no
 265      *            isMisappliedNameFor relationship.
 266      * @param propertyPaths
 267      *            properties to be initialized, For detailed description and
 268      *            examples <b>please refer to:</b>
 269      *            {@link IBeanInitializer#initialize(Object, List)}. <Br>
 270      *            Default: true.
 271      * @return The List<Taxon> of root taxa.
 272      * @deprecated obsolete when using classification
 273      */
 274     @Deprecated
 275     public List<Taxon>
 276     getRootTaxa(Rank rank, Reference sec, CdmFetch cdmFetch, Boolean onlyWithChildren, Boolean withMisapplications, List<String> propertyPaths);
 277
 278         /**
 279      * TODO necessary?
 280      * @param pagesize max maximum number of returned taxa
 281      * @param page page to start, with 0 being first page
 282      * @return
 283      */
 284     public List<TaxonBase> getAllTaxonBases(Integer pagesize, Integer page);
 285
 286
 287     /**
 288      * @param limit
 289      * @param start
 290      * @return
 291      */
 292     public List<Taxon> getAllTaxa(Integer limit, Integer start);
 293
 294     /**
 295      * @param limit
 296      * @param start
 297      * @return
 298      */
 299     public List<Synonym> getAllSynonyms(Integer limit, Integer start);
 300
 301     public List<RelationshipBase> getAllRelationships(Integer limit, Integer start);
 302
 303     public int countAllRelationships();
 304
 305     /**
 306      * @param queryString
 307      * @param matchMode
 308      * @param onlyAcccepted
 309      * @return
 310      */
 311     public int countMatchesByName(String queryString, MatchMode matchMode, boolean onlyAcccepted);
 312
 313     /**
 314      * @param queryString
 315      * @param matchMode
 316      * @param onlyAcccepted
 317      * @param criteria
 318      * @return
 319      */
 320     public int countMatchesByName(String queryString, MatchMode matchMode, boolean onlyAcccepted, List<Criterion> criteria);
 321
 322     /**
 323      * Returns a count of the TaxonRelationships (of where relationship.type ==
 324      * type, if this argument is supplied) where the supplied taxon either is
 325      * relatedFrom or relatedTo depending on the <code>direction</code>
 326      * parameter.
 327      *
 328      * @param taxon
 329      *            The taxon that is relatedFrom
 330      * @param type
 331      *            The type of TaxonRelationship (can be null)
 332      * @param direction
 333      *            specifies the direction of the relationship
 334      * @return the number of TaxonRelationship instances
 335      */
 336     public int countTaxonRelationships(Taxon taxon, TaxonRelationshipType type,
 337             Direction direction);
 338
 339     /**
 340      * Returns the TaxonRelationships (of where relationship.type == type, if
 341      * this argument is supplied) where the supplied taxon either is
 342      * relatedFrom or relatedTo depending on the <code>direction</code>
 343      * parameter.
 344      *
 345      * @param taxon
 346      *            The taxon that is relatedTo
 347      * @param type
 348      *            The type of TaxonRelationship (can be null)
 349      * @param pageSize
 350      *            The maximum number of relationships returned (can be null for
 351      *            all relationships)
 352      * @param pageNumber
 353      *            The offset (in pageSize chunks) from the start of the result
 354      *            set (0 - based)
 355      * @param orderHints
 356      *            Properties to order by
 357      * @param propertyPaths
 358      *            Properties to initialize in the returned entities, following
 359      *            the syntax described in
 360      *            {@link IBeanInitializer#initialize(Object, List)}
 361      * @param direction
 362      *            specifies the direction of the relationship
 363      * @return a List of TaxonRelationship instances
 364      */
 365     public List<TaxonRelationship> getTaxonRelationships(Taxon taxon,
 366             TaxonRelationshipType type, Integer pageSize, Integer pageNumber,
 367             List<OrderHint> orderHints, List<String> propertyPaths,
 368             Direction direction);
 369
 370     /**
 371      * Returns a count of the SynonymRelationships (of where relationship.type == type,
 372      *  if this arguement is supplied) where the supplied taxon is relatedTo.
 373      *
 374      * @param taxon The taxon that is relatedTo
 375      * @param type The type of SynonymRelationship (can be null)
 376      * @return the number of SynonymRelationship instances
 377      */
 378     public int countSynonyms(Taxon taxon, SynonymRelationshipType type);
 379
 380     /**
 381      * Returns the SynonymRelationships (of where relationship.type == type, if this arguement is supplied)
 382      * where the supplied taxon is relatedTo.
 383      *
 384      * @param taxon The taxon that is relatedTo
 385      * @param type The type of SynonymRelationship (can be null)
 386      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 387      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 388      * * @param orderHints Properties to order by
 389      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 390      * @return a List of SynonymRelationship instances
 391      */
 392     public List<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 393
 394     /**
 395      * Returns a count of the SynonymRelationships (of where relationship.type == type,
 396      *  if this arguement is supplied) where the supplied synonym is relatedFrom.
 397      *
 398      * @param taxon The synonym that is relatedFrom
 399      * @param type The type of SynonymRelationship (can be null)
 400      * @return the number of SynonymRelationship instances
 401      */
 402     public int countSynonyms(Synonym synonym, SynonymRelationshipType type);
 403
 404     /**
 405      * Returns the SynonymRelationships (of where relationship.type == type, if this arguement is supplied)
 406      * where the supplied synonym is relatedFrom.
 407      *
 408      * @param taxon The synonym that is relatedFrom
 409      * @param type The type of SynonymRelationship (can be null)
 410      * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 411      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 412      * * @param orderHints Properties to order by
 413      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 414      * @return a List of SynonymRelationship instances
 415      */
 416     public List<SynonymRelationship> getSynonyms(Synonym synoynm, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 417
 418     /**
 419      *
 420      * @return
 421      */
 422     public List<UuidAndTitleCache<TaxonNode>> getTaxonNodeUuidAndTitleCacheOfAcceptedTaxaByClassification(Classification classification);
 423
 424
 425     /**
 426      * Creates all inferred synonyms for the species in the tree and insert it to the database
 427      * @param tree
 428      * @return List of inferred synonyms
 429      */
 430     //public List<Synonym> insertAllInferredSynonymy(Classification tree);
 431
 432
 433
 434     public List<TaxonNameBase> findIdenticalTaxonNames(List<String> propertyPath);
 435     public String getPhylumName(TaxonNameBase name);
 436
 437     public long countTaxaByCommonName(String searchString,
 438             Classification classification, MatchMode matchMode,
 439             Set<NamedArea> namedAreas);
 440
 441     /**
 442      * Deletes all synonym relationships of a given synonym.
 443      * If taxon is given only those relationships to the taxon
 444      * are deleted.
 445      * @param synonym the synonym
 446      * @param taxon the taxon, may be <code>null</code>
 447      * @return
 448      * @deprecated This method must no longer being used since the
 449      *             SynonymRelationship is annotated at the {@link Taxon} and at
 450      *             the {@link Synonym} with <code>orphanDelete=true</code>. Just
 451      *             remove the from and to entities from the relationship and
 452      *             hibernate will care for the deletion. Using this method can cause
 453      *             <code>StaleStateException</code> (see http://dev.e-taxonomy.eu/trac/ticket/3797)
 454      */
 455     @Deprecated
 456     public long deleteSynonymRelationships(Synonym syn, Taxon taxon);
 457
 458     public List<UUID> findIdenticalTaxonNameIds(List<String> propertyPath);
 459
 460     public List<TaxonNameBase> findIdenticalNamesNew(List <String> propertyPaths);
 461
 462
 463     public Integer countSynonymRelationships(TaxonBase taxonBase,
 464             SynonymRelationshipType type, Direction relatedfrom);
 465
 466     public List<SynonymRelationship> getSynonymRelationships(TaxonBase taxonBase,
 467             SynonymRelationshipType type, Integer pageSize, Integer pageNumber,
 468             List<OrderHint> orderHints, List<String> propertyPaths,
 469             Direction relatedfrom);
 470
 471     /**
 472      * @return
 473      */
 474     public List<UuidAndTitleCache<TaxonBase>> getUuidAndTitleCacheTaxon();
 475
 476     /**
 477      * @return
 478      */
 479     public List<UuidAndTitleCache<TaxonBase>> getUuidAndTitleCacheSynonym();
 480
 481     public List<UuidAndTitleCache<IdentifiableEntity>> getTaxaByNameForEditor(boolean doTaxa, boolean doSynonyms, boolean doNamesWithoutTaxa, boolean doMisappliedNames, String queryString, Classification classification,
 482             MatchMode matchMode, Set<NamedArea> namedAreas);
 483
 484     public List<String> taxaByNameNotInDB(List<String> taxonNames);
 485
 486     public List<Taxon> listAcceptedTaxaFor(Synonym synonym, Classification classificationFilter, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints,
 487             List<String> propertyPaths);
 488
 489     public long countAcceptedTaxaFor(Synonym synonym, Classification classificationFilter);
 490
 491         public List<UuidAndTitleCache<IdentifiableEntity>> getTaxaByCommonNameForEditor(
 492                         String titleSearchStringSqlized, Classification classification,
 493                         MatchMode matchMode, Set namedAreas);
 494
 495
 496 }