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