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
  14 import org.hibernate.criterion.Criterion;
  15
  16 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  17 import eu.etaxonomy.cdm.model.name.Rank;
  18 import eu.etaxonomy.cdm.model.reference.ReferenceBase;
  19 import eu.etaxonomy.cdm.model.taxon.Synonym;
  20 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  21 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  22 import eu.etaxonomy.cdm.model.taxon.Taxon;
  23 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  24 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  25 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  26 import eu.etaxonomy.cdm.persistence.dao.common.IIdentifiableDao;
  27 import eu.etaxonomy.cdm.persistence.dao.common.ITitledDao;
  28 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  29
  30 /**
  31  * @author a.mueller
  32  *
  33  */
  34 public interface ITaxonDao extends IIdentifiableDao<TaxonBase>, ITitledDao<TaxonBase> {
  35
  36         /**
  37          * Returns a count of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  38          * where the taxonBase.name.nameCache property matches the String queryString
  39          *
  40          * @param queryString
  41          * @param accepted
  42          * @param sec
  43          * @return a count of the matching taxa
  44          */
  45         public int countTaxaByName(String queryString, Boolean accepted, ReferenceBase sec);
  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, ReferenceBase 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, ReferenceBase sec);
  64
  65         /**
  66          * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
  67          * @return The List<Taxon> of root taxa.
  68          */
  69         public List<Taxon> getRootTaxa(ReferenceBase sec);
  70
  71
  72         /**
  73          * Computes all Taxon instances that do not have a taxonomic parent.
  74          * @param sec The concept reference that the taxon belongs to
  75          * @param cdmFetch not used yet !! TODO
  76          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
  77          * @param withMisaplications if false only taxa are returned that have no isMisappliedNameFor relationship.
  78          * <Br>Default: true.
  79          * @return The List<Taxon> of root taxa.
  80          */
  81         public List<Taxon> getRootTaxa(ReferenceBase sec, CdmFetch cdmFetch, Boolean onlyWithChildren, Boolean withMisapplications);
  82
  83
  84         /**
  85          * TODO necessary?
  86          * @param pagesize max maximum number of returned taxa
  87          * @param page page to start, with 0 being first page
  88          * @return
  89          */
  90         public List<TaxonBase> getAllTaxonBases(Integer pagesize, Integer page);
  91
  92
  93         /**
  94          * @param limit
  95          * @param start
  96          * @return
  97          */
  98         public List<Taxon> getAllTaxa(Integer limit, Integer start);
  99
 100         /**
 101          * @param limit
 102          * @param start
 103          * @return
 104          */
 105         public List<Synonym> getAllSynonyms(Integer limit, Integer start);
 106
 107         /**
 108          * @param limit
 109          * @param start
 110          * @return
 111          */
 112         //public List<TaxonRelationship> getAllTaxonRelationships(Integer limit, Integer start);
 113
 114         /**
 115          * @param limit
 116          * @param start
 117          * @return
 118          */
 119         //public List<SynonymRelationship> getAllSynonymRelationships(Integer limit, Integer start);
 120
 121         public List<RelationshipBase> getAllRelationships(Integer limit, Integer start);
 122
 123         /**
 124          * Find taxa by searching for @{link NameBase}
 125          * @param queryString
 126          * @param matchMode
 127          * @param page
 128          * @param pagesize
 129          * @param onlyAcccepted
 130          * @return
 131          */
 132         public List<Taxon> findByName(String queryString, ITitledDao.MATCH_MODE matchMode, int page, int pagesize, boolean onlyAcccepted);
 133
 134         /**
 135          * @param queryString
 136          * @param matchMode
 137          * @param onlyAcccepted
 138          * @return
 139          */
 140         public int countMatchesByName(String queryString, ITitledDao.MATCH_MODE matchMode, boolean onlyAcccepted);
 141
 142         /**
 143          * @param queryString
 144          * @param matchMode
 145          * @param onlyAcccepted
 146          * @param criteria
 147          * @return
 148          */
 149         public int countMatchesByName(String queryString, ITitledDao.MATCH_MODE matchMode, boolean onlyAcccepted, List<Criterion> criteria);
 150
 151         /**
 152          * Returns a count of the TaxonRelationships (of where relationship.type == type,
 153          *  if this arguement is supplied) where the supplied taxon is relatedFrom.
 154          *
 155          * @param taxon The taxon that is relatedFrom
 156          * @param type The type of TaxonRelationship (can be null)
 157          * @return the number of TaxonRelationship instances
 158          */
 159         public int countRelatedTaxa(Taxon taxon, TaxonRelationshipType type);
 160
 161         /**
 162          * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
 163          * where the supplied taxon is relatedTo.
 164          *
 165          * @param taxon The taxon that is relatedTo
 166          * @param type The type of TaxonRelationship (can be null)
 167          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 168          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 169          * @return a List of TaxonRelationship instances
 170          */
 171         public List<TaxonRelationship> getRelatedTaxa(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber);
 172
 173         /**
 174          * Returns a count of the SynonymRelationships (of where relationship.type == type,
 175          *  if this arguement is supplied) where the supplied taxon is relatedTo.
 176          *
 177          * @param taxon The taxon that is relatedTo
 178          * @param type The type of SynonymRelationship (can be null)
 179          * @return the number of SynonymRelationship instances
 180          */
 181         public int countSynonyms(Taxon taxon, SynonymRelationshipType type);
 182
 183         /**
 184          * Returns the SynonymRelationships (of where relationship.type == type, if this arguement is supplied)
 185          * where the supplied taxon is relatedTo.
 186          *
 187          * @param taxon The taxon that is relatedTo
 188          * @param type The type of SynonymRelationship (can be null)
 189          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 190          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 191          * @return a List of SynonymRelationship instances
 192          */
 193         public List<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber);
 194
 195         /**
 196          * Returns a count of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false) where the
 197          * taxonBase.name.nameCache property matches the String queryString (as interpreted by the Lucene QueryParser)
 198          *
 199          * @param queryString
 200          * @param accepted
 201          * @return a count of the matching taxa
 202          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 203          */
 204         public int countTaxa(String queryString, Boolean accepted);
 205
 206         /**
 207          * Returns a List of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false) where the
 208          * taxonBase.name.nameCache property matches the String queryString (as interpreted by the Lucene QueryParser)
 209          *
 210          * @param queryString
 211          * @param accepted
 212          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 213          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 214          * @return a List Taxon instances
 215          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 216          */
 217         public List<TaxonBase> searchTaxa(String queryString, Boolean accepted, Integer pageSize, Integer pageNumber);
 218
 219         /**
 220          * Returns a count of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false) where the
 221          * taxon.name properties match the parameters passed.
 222          *
 223          * @param accepted
 224          * @param uninomial
 225          * @param infragenericEpithet
 226          * @param specificEpithet
 227          * @param infraspecificEpithet
 228          * @param rank
 229          * @return a count of TaxonBase instances
 230          */
 231         public int countTaxaByName(Boolean accepted, String uninomial, String infragenericEpithet,String specificEpithet, String infraspecificEpithet, Rank rank);
 232
 233         /**
 234          * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false) where the
 235          * taxon.name properties match the parameters passed.
 236          *
 237          * @param accepted Whether the taxon is accepted (true) a synonym (false), or either (null)
 238          * @param uninomial
 239          * @param infragenericEpithet
 240          * @param specificEpithet
 241          * @param infraspecificEpithet
 242          * @param rank
 243          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 244          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 245          * @return a list of TaxonBase instances
 246          */
 247         public List<TaxonBase> findTaxaByName(Boolean accepted, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 248
 249         /**
 250          * Suggest a query that will return hits based upon an existing lucene query string (that is presumably misspelt and returns no hits)
 251          * Used to implement "did you mean?"-type functionality using the lucene spellchecker.
 252          *
 253          * @param string Query string to check
 254          * @return a suggested query string that will return hits or null if no such alternative spelling can be found.
 255          */
 256         public String suggestQuery(String string);
 257
 258         /**
 259          * Removes all TaxonBase entities from the index
 260          */
 261         public void purgeIndex();
 262
 263         /**
 264          * Index all TaxonBase entities currenly in the database (useful in concert with purgeIndex() to (re-)create
 265          * indexes or in the  case of corrupt indexes / mismatch between
 266          * the database and the free-text indices)
 267          */
 268         public void rebuildIndex();
 269
 270         /**
 271          * Calls optimize on the relevant index (useful periodically to increase response times on the free-text search)
 272          */
 273         public void optimizeIndex();
 274 }