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