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.UUID;
  14
  15 import org.hibernate.criterion.Criterion;
  16
  17 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  18 import eu.etaxonomy.cdm.model.common.RelationshipBase.Direction;
  19 import eu.etaxonomy.cdm.model.name.Rank;
  20 import eu.etaxonomy.cdm.model.reference.ReferenceBase;
  21 import eu.etaxonomy.cdm.model.taxon.Synonym;
  22 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  23 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  24 import eu.etaxonomy.cdm.model.taxon.Taxon;
  25 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  26 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  27 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  28 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  29 import eu.etaxonomy.cdm.persistence.dao.common.IIdentifiableDao;
  30 import eu.etaxonomy.cdm.persistence.dao.common.ISearchableDao;
  31 import eu.etaxonomy.cdm.persistence.dao.common.ITitledDao;
  32 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  33 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  34 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  35 import eu.etaxonomy.cdm.persistence.query.SelectMode;
  36
  37 /**
  38  * @author a.mueller
  39  *
  40  */
  41 public interface ITaxonDao extends IIdentifiableDao<TaxonBase>, ITitledDao<TaxonBase>, ISearchableDao<TaxonBase> {
  42
  43         /**
  44          * Returns a count of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  45          * where the taxonBase.name.nameCache property matches the String queryString
  46          *
  47          * @param queryString
  48          * @param accepted
  49          * @param sec
  50          * @return a count of the matching taxa
  51          */
  52         public int countTaxaByName(String queryString, Boolean accepted, ReferenceBase sec);
  53
  54         /**
  55          * Returns a count of TaxonBase instances where the
  56          * taxon.name properties match the parameters passed.
  57          *
  58          * @param queryString search string
  59          * @param matchMode way how search string shall be matched: exact, beginning, or anywhere
  60          * @param selectMode either all taxon bases, or all taxa, or all synonyms
  61          * @param sec reference
  62          */
  63         public Integer countTaxaByName(String queryString,
  64                         MatchMode matchMode, SelectMode selectMode, ReferenceBase sec);
  65
  66         /**
  67          * Returns a list of TaxonBase instances where the taxon.titleCache property matches the name parameter,
  68          * and taxon.sec matches the sec parameter.
  69          * @param name
  70          * @param sec
  71          * @return
  72          */
  73         public List<TaxonBase> getTaxaByName(String name, ReferenceBase sec);
  74
  75         /**
  76          * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  77          * where the taxonBase.name.nameCache property matches the String queryString, and taxon.sec matches the sec parameter.
  78          * @param name
  79          * @param sec
  80          * @return
  81          */
  82         public List<TaxonBase> getTaxaByName(String queryString, Boolean accepted, ReferenceBase sec);
  83
  84         /**
  85          * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  86          * where the taxonBase.name.nameCache property matches the String queryString.
  87          * @param queryString
  88          * @param matchMode
  89          * @param accepted
  90          * @param pageSize
  91          * @param pageNumber
  92          * @return
  93          */
  94         public List<TaxonBase> getTaxaByName(String queryString, MatchMode matchMode,
  95                         Boolean accepted, Integer pageSize, Integer pageNumber);
  96
  97
  98         /**
  99          * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
 100          * where the taxonBase.name.nameCache property matches the String queryString.
 101          * @param queryString
 102          * @param matchMode
 103          * @param selectMode
 104          * @param pageSize
 105          * @param pageNumber
 106          * @param propertyPaths TODO
 107          * @return list of found taxa
 108          */
 109         public List<TaxonBase> getTaxaByName(String queryString, MatchMode matchMode, SelectMode selectMode,
 110                         ReferenceBase sec, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 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          * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
 133          * @return The List<Taxon> of root taxa.
 134          */
 135         public List<Taxon> getRootTaxa(ReferenceBase sec);
 136
 137
 138         /**
 139          * Computes all Taxon instances that do not have a taxonomic parent.
 140          * @param sec The concept reference that the taxon belongs to
 141          * @param cdmFetch not used yet !! TODO
 142          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 143          * @param withMisaplications if false only taxa are returned that have no isMisappliedNameFor relationship.
 144          * <Br>Default: true.
 145          * @return The List<Taxon> of root taxa.
 146          */
 147         public List<Taxon> getRootTaxa(ReferenceBase sec, CdmFetch cdmFetch, Boolean onlyWithChildren, Boolean withMisapplications);
 148
 149
 150         /**
 151          * Computes all Taxon instances which name is of a certain Rank.
 152          *
 153          * @param rank
 154          *            The rank of the taxon name
 155          * @param sec
 156          *            The concept reference that the taxon belongs to
 157          * @param cdmFetch
 158          *            not used yet !! TODO
 159          * @param onlyWithChildren
 160          *            if true only taxa are returned that have taxonomic children. <Br>
 161          *            Default: true.
 162          * @param withMisaplications
 163          *            if false only taxa are returned that have no
 164          *            isMisappliedNameFor relationship.
 165          * @param propertyPaths
 166          *            properties to be initialized, For detailed description and
 167          *            examples <b>please refer to:</b>
 168          *            {@link BeanInitializer#initialize(Object, List)}. <Br>
 169          *            Default: true.
 170          * @return The List<Taxon> of root taxa.
 171          */
 172         public List<Taxon>
 173         getRootTaxa(Rank rank, ReferenceBase sec, CdmFetch cdmFetch, Boolean onlyWithChildren, Boolean withMisapplications, List<String> propertyPaths);
 174
 175                 /**
 176          * TODO necessary?
 177          * @param pagesize max maximum number of returned taxa
 178          * @param page page to start, with 0 being first page
 179          * @return
 180          */
 181         public List<TaxonBase> getAllTaxonBases(Integer pagesize, Integer page);
 182
 183
 184         /**
 185          * @param limit
 186          * @param start
 187          * @return
 188          */
 189         public List<Taxon> getAllTaxa(Integer limit, Integer start);
 190
 191         /**
 192          * @param limit
 193          * @param start
 194          * @return
 195          */
 196         public List<Synonym> getAllSynonyms(Integer limit, Integer start);
 197
 198         public List<RelationshipBase> getAllRelationships(Integer limit, Integer start);
 199
 200         /**
 201          * Find taxa by searching for @{link NameBase}
 202          * @param queryString
 203          * @param matchMode
 204          * @param page
 205          * @param pagesize
 206          * @param onlyAcccepted
 207          * @return
 208          */
 209         public List<Taxon> findByName(String queryString, MatchMode matchMode, int page, int pagesize, boolean onlyAcccepted);
 210
 211         /**
 212          * @param queryString
 213          * @param matchMode
 214          * @param onlyAcccepted
 215          * @return
 216          */
 217         public int countMatchesByName(String queryString, MatchMode matchMode, boolean onlyAcccepted);
 218
 219         /**
 220          * @param queryString
 221          * @param matchMode
 222          * @param onlyAcccepted
 223          * @param criteria
 224          * @return
 225          */
 226         public int countMatchesByName(String queryString, MatchMode matchMode, boolean onlyAcccepted, List<Criterion> criteria);
 227
 228         /**
 229          * Returns a count of the TaxonRelationships (of where relationship.type ==
 230          * type, if this argument is supplied) where the supplied taxon either is
 231          * relatedFrom or relatedTo depending on the <code>direction</code>
 232          * parameter.
 233          *
 234          * @param taxon
 235          *            The taxon that is relatedFrom
 236          * @param type
 237          *            The type of TaxonRelationship (can be null)
 238          * @param direction
 239          *            specifies the direction of the relationship
 240          * @return the number of TaxonRelationship instances
 241          */
 242         public int countTaxonRelationships(Taxon taxon, TaxonRelationshipType type,
 243                         Direction direction);
 244
 245         /**
 246          * Returns the TaxonRelationships (of where relationship.type == type, if
 247          * this argument is supplied) where the supplied taxon either is
 248          * relatedFrom or relatedTo depending on the <code>direction</code>
 249          * parameter.
 250          *
 251          * @param taxon
 252          *            The taxon that is relatedTo
 253          * @param type
 254          *            The type of TaxonRelationship (can be null)
 255          * @param pageSize
 256          *            The maximum number of relationships returned (can be null for
 257          *            all relationships)
 258          * @param pageNumber
 259          *            The offset (in pageSize chunks) from the start of the result
 260          *            set (0 - based)
 261          * @param orderHints
 262          *            Properties to order by
 263          * @param propertyPaths
 264          *            Properties to initialize in the returned entities, following
 265          *            the syntax described in
 266          *            {@link BeanInitializer#initialize(Object, List)}
 267          * @param direction
 268          *            specifies the direction of the relationship
 269          * @return a List of TaxonRelationship instances
 270          */
 271         public List<TaxonRelationship> getTaxonRelationships(Taxon taxon,
 272                         TaxonRelationshipType type, Integer pageSize, Integer pageNumber,
 273                         List<OrderHint> orderHints, List<String> propertyPaths,
 274                         Direction direction);
 275
 276         /**
 277          * Returns a count of the SynonymRelationships (of where relationship.type == type,
 278          *  if this arguement is supplied) where the supplied taxon is relatedTo.
 279          *
 280          * @param taxon The taxon that is relatedTo
 281          * @param type The type of SynonymRelationship (can be null)
 282          * @return the number of SynonymRelationship instances
 283          */
 284         public int countSynonyms(Taxon taxon, SynonymRelationshipType type);
 285
 286         /**
 287          * Returns the SynonymRelationships (of where relationship.type == type, if this arguement is supplied)
 288          * where the supplied taxon is relatedTo.
 289          *
 290          * @param taxon The taxon that is relatedTo
 291          * @param type The type of SynonymRelationship (can be null)
 292          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 293          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 294          * * @param orderHints Properties to order by
 295          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 296          * @return a List of SynonymRelationship instances
 297          */
 298         public List<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 299
 300         /**
 301          * Returns a count of TaxonBase instances where the
 302          * taxon.name properties match the parameters passed.
 303          *
 304          * @param clazz
 305          * @param uninomial
 306          * @param infragenericEpithet
 307          * @param specificEpithet
 308          * @param infraspecificEpithet
 309          * @param rank
 310          * @return a count of TaxonBase instances
 311          */
 312         public int countTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet,String specificEpithet, String infraspecificEpithet, Rank rank);
 313
 314         /**
 315          * Returns a list of TaxonBase instances where the
 316          * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 317          * <i>null</i> will search for those taxa with a value of null in that field
 318          *
 319          * @param clazz optionally filter by class (can be null to return all taxa)
 320          * @param uninomial
 321          * @param infragenericEpithet
 322          * @param specificEpithet
 323          * @param infraspecificEpithet
 324          * @param rank
 325          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 326          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 327          * @return a list of TaxonBase instances
 328          */
 329         public List<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 330
 331
 332 }