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
  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.location.NamedArea;
  20 import eu.etaxonomy.cdm.model.name.Rank;
  21 import eu.etaxonomy.cdm.model.reference.ReferenceBase;
  22 import eu.etaxonomy.cdm.model.taxon.Synonym;
  23 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
  24 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
  25 import eu.etaxonomy.cdm.model.taxon.Taxon;
  26 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  27 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  28 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
  29 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  30 import eu.etaxonomy.cdm.persistence.dao.common.IIdentifiableDao;
  31 import eu.etaxonomy.cdm.persistence.dao.common.ISearchableDao;
  32 import eu.etaxonomy.cdm.persistence.dao.common.ITitledDao;
  33 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
  34 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  35 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  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 clazz
 102          * @param queryString
 103          * @param matchMode
 104          * @param namedAreas TODO
 105          * @param pageSize
 106          * @param pageNumber
 107          * @param propertyPaths TODO
 108          * @return list of found taxa
 109          */
 110         public List<TaxonBase> getTaxaByName(Class<? extends TaxonBase> clazz, String queryString, MatchMode matchMode,
 111                         ReferenceBase sec, Set<NamedArea> namedAreas, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 112
 113         /**
 114          * @param clazz
 115          * @param queryString
 116          * @param matchMode
 117          * @param sec
 118          * @param namedAreas
 119          * @param pageSize
 120          * @param pageNumber
 121          * @param propertyPaths
 122          * @return
 123          */
 124         public long countTaxaByName(Class<? extends TaxonBase> clazz, String queryString, MatchMode matchMode,
 125
 126                         ReferenceBase sec, Set<NamedArea> namedAreas);
 127
 128 //      /**
 129 //       * @param queryString
 130 //       * @param matchMode
 131 //       * @param accepted
 132 //       * @return
 133 //       */
 134 //      public Integer countTaxaByName(String queryString, MatchMode matchMode,
 135 //                      Boolean accepted);
 136
 137 //      /**
 138 //       * Returns a count of TaxonBase instances where the
 139 //       * taxon.name properties match the parameters passed.
 140 //       *
 141 //       * @param queryString search string
 142 //       * @param matchMode way how search string shall be matched: exact, beginning, or anywhere
 143 //       * @param selectModel all taxon base, taxa, or synonyms
 144 //       */
 145 //      public Integer countTaxaByName(String queryString, MatchMode matchMode, SelectMode selectMode);
 146
 147         /**
 148          * Computes all Taxon instances that do not have a taxonomic parent and has at least one child.
 149          * @return The List<Taxon> of root taxa.
 150          */
 151         public List<Taxon> getRootTaxa(ReferenceBase sec);
 152
 153
 154         /**
 155          * Computes all Taxon instances that do not have a taxonomic parent.
 156          * @param sec The concept reference that the taxon belongs to
 157          * @param cdmFetch not used yet !! TODO
 158          * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
 159          * @param withMisaplications if false only taxa are returned that have no isMisappliedNameFor relationship.
 160          * <Br>Default: true.
 161          * @return The List<Taxon> of root taxa.
 162          */
 163         public List<Taxon> getRootTaxa(ReferenceBase sec, CdmFetch cdmFetch, Boolean onlyWithChildren, Boolean withMisapplications);
 164
 165
 166         /**
 167          * Computes all Taxon instances which name is of a certain Rank.
 168          *
 169          * @param rank
 170          *            The rank of the taxon name
 171          * @param sec
 172          *            The concept reference that the taxon belongs to
 173          * @param cdmFetch
 174          *            not used yet !! TODO
 175          * @param onlyWithChildren
 176          *            if true only taxa are returned that have taxonomic children. <Br>
 177          *            Default: true.
 178          * @param withMisaplications
 179          *            if false only taxa are returned that have no
 180          *            isMisappliedNameFor relationship.
 181          * @param propertyPaths
 182          *            properties to be initialized, For detailed description and
 183          *            examples <b>please refer to:</b>
 184          *            {@link BeanInitializer#initialize(Object, List)}. <Br>
 185          *            Default: true.
 186          * @return The List<Taxon> of root taxa.
 187          */
 188         public List<Taxon>
 189         getRootTaxa(Rank rank, ReferenceBase sec, CdmFetch cdmFetch, Boolean onlyWithChildren, Boolean withMisapplications, List<String> propertyPaths);
 190
 191                 /**
 192          * TODO necessary?
 193          * @param pagesize max maximum number of returned taxa
 194          * @param page page to start, with 0 being first page
 195          * @return
 196          */
 197         public List<TaxonBase> getAllTaxonBases(Integer pagesize, Integer page);
 198
 199
 200         /**
 201          * @param limit
 202          * @param start
 203          * @return
 204          */
 205         public List<Taxon> getAllTaxa(Integer limit, Integer start);
 206
 207         /**
 208          * @param limit
 209          * @param start
 210          * @return
 211          */
 212         public List<Synonym> getAllSynonyms(Integer limit, Integer start);
 213
 214         public List<RelationshipBase> getAllRelationships(Integer limit, Integer start);
 215
 216         /**
 217          * Find taxa by searching for @{link NameBase}
 218          * @param queryString
 219          * @param matchMode
 220          * @param page
 221          * @param pagesize
 222          * @param onlyAcccepted
 223          * @return
 224          */
 225         public List<Taxon> findByName(String queryString, MatchMode matchMode, int page, int pagesize, boolean onlyAcccepted);
 226
 227         /**
 228          * @param queryString
 229          * @param matchMode
 230          * @param onlyAcccepted
 231          * @return
 232          */
 233         public int countMatchesByName(String queryString, MatchMode matchMode, boolean onlyAcccepted);
 234
 235         /**
 236          * @param queryString
 237          * @param matchMode
 238          * @param onlyAcccepted
 239          * @param criteria
 240          * @return
 241          */
 242         public int countMatchesByName(String queryString, MatchMode matchMode, boolean onlyAcccepted, List<Criterion> criteria);
 243
 244         /**
 245          * Returns a count of the TaxonRelationships (of where relationship.type ==
 246          * type, if this argument is supplied) where the supplied taxon either is
 247          * relatedFrom or relatedTo depending on the <code>direction</code>
 248          * parameter.
 249          *
 250          * @param taxon
 251          *            The taxon that is relatedFrom
 252          * @param type
 253          *            The type of TaxonRelationship (can be null)
 254          * @param direction
 255          *            specifies the direction of the relationship
 256          * @return the number of TaxonRelationship instances
 257          */
 258         public int countTaxonRelationships(Taxon taxon, TaxonRelationshipType type,
 259                         Direction direction);
 260
 261         /**
 262          * Returns the TaxonRelationships (of where relationship.type == type, if
 263          * this argument is supplied) where the supplied taxon either is
 264          * relatedFrom or relatedTo depending on the <code>direction</code>
 265          * parameter.
 266          *
 267          * @param taxon
 268          *            The taxon that is relatedTo
 269          * @param type
 270          *            The type of TaxonRelationship (can be null)
 271          * @param pageSize
 272          *            The maximum number of relationships returned (can be null for
 273          *            all relationships)
 274          * @param pageNumber
 275          *            The offset (in pageSize chunks) from the start of the result
 276          *            set (0 - based)
 277          * @param orderHints
 278          *            Properties to order by
 279          * @param propertyPaths
 280          *            Properties to initialize in the returned entities, following
 281          *            the syntax described in
 282          *            {@link BeanInitializer#initialize(Object, List)}
 283          * @param direction
 284          *            specifies the direction of the relationship
 285          * @return a List of TaxonRelationship instances
 286          */
 287         public List<TaxonRelationship> getTaxonRelationships(Taxon taxon,
 288                         TaxonRelationshipType type, Integer pageSize, Integer pageNumber,
 289                         List<OrderHint> orderHints, List<String> propertyPaths,
 290                         Direction direction);
 291
 292         /**
 293          * Returns a count of the SynonymRelationships (of where relationship.type == type,
 294          *  if this arguement is supplied) where the supplied taxon is relatedTo.
 295          *
 296          * @param taxon The taxon that is relatedTo
 297          * @param type The type of SynonymRelationship (can be null)
 298          * @return the number of SynonymRelationship instances
 299          */
 300         public int countSynonyms(Taxon taxon, SynonymRelationshipType type);
 301
 302         /**
 303          * Returns the SynonymRelationships (of where relationship.type == type, if this arguement is supplied)
 304          * where the supplied taxon is relatedTo.
 305          *
 306          * @param taxon The taxon that is relatedTo
 307          * @param type The type of SynonymRelationship (can be null)
 308          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 309          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 310          * * @param orderHints Properties to order by
 311          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 312          * @return a List of SynonymRelationship instances
 313          */
 314         public List<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 315
 316         /**
 317          * Returns a count of TaxonBase instances where the
 318          * taxon.name properties match the parameters passed.
 319          *
 320          * @param clazz
 321          * @param uninomial
 322          * @param infragenericEpithet
 323          * @param specificEpithet
 324          * @param infraspecificEpithet
 325          * @param rank
 326          * @return a count of TaxonBase instances
 327          */
 328         public int countTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet,String specificEpithet, String infraspecificEpithet, Rank rank);
 329
 330         /**
 331          * Returns a list of TaxonBase instances where the
 332          * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 333          * <i>null</i> will search for those taxa with a value of null in that field
 334          *
 335          * @param clazz optionally filter by class (can be null to return all taxa)
 336          * @param uninomial
 337          * @param infragenericEpithet
 338          * @param specificEpithet
 339          * @param infraspecificEpithet
 340          * @param rank
 341          * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 342          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 343          * @return a list of TaxonBase instances
 344          */
 345         public List<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
 346
 347
 348 }