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.DefinedTerm;
  19 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
  20 import eu.etaxonomy.cdm.model.common.MarkerType;
  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.name.TaxonName;
  25 import eu.etaxonomy.cdm.model.reference.Reference;
  26 import eu.etaxonomy.cdm.model.taxon.Classification;
  27 import eu.etaxonomy.cdm.model.taxon.Synonym;
  28 import eu.etaxonomy.cdm.model.taxon.SynonymType;
  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.IPublishableDao;
  36 import eu.etaxonomy.cdm.persistence.dao.common.ITitledDao;
  37 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  38 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  39 import eu.etaxonomy.cdm.persistence.query.NameSearchOrder;
  40 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  41 import eu.etaxonomy.cdm.persistence.query.TaxonTitleType;
  42
  43 /**
  44  * @author a.mueller
  45  *
  46  */
  47 public interface ITaxonDao
  48           extends IIdentifiableDao<TaxonBase>, ITitledDao<TaxonBase>, IPublishableDao<TaxonBase> {
  49
  50
  51     /**
  52      * {@inheritDoc}
  53      * <BR><BR>
  54      * NOTE: Also taxa with <code>publish=false</code> are returned.
  55      */
  56     @Override
  57     public TaxonBase load(UUID uuid, List<String> propertyPaths);
  58
  59     /**
  60      * Returns a list of TaxonBase instances where the taxon.titleCache property matches the name parameter,
  61      * and taxon.sec matches the sec parameter.
  62      * @param name
  63      * @param sec
  64      * @return
  65      */
  66     public List<TaxonBase> getTaxaByName(String name, boolean includeUnpublished, Reference sec);
  67
  68     /**
  69      * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  70      * where the taxonBase.name.nameCache property matches the String queryString, and taxon.sec matches the sec parameter.
  71      * @param name
  72      * @param sec
  73      * @return
  74      */
  75     public List<TaxonBase> getTaxaByName(String queryString, Boolean accepted, boolean includeUnpublished, Reference sec);
  76
  77     /**
  78      * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  79      * where the taxonBase.name.nameCache property matches the String queryString.
  80      * @param queryString
  81      * @param matchMode
  82      * @param accepted
  83      * @param pageSize
  84      * @param pageNumber
  85      * @return
  86      */
  87     public List<TaxonBase> getTaxaByName(String queryString, MatchMode matchMode,
  88             Boolean accepted, boolean includeUnpublished, Integer pageSize, Integer pageNumber);
  89
  90
  91     /**
  92      * Returns a list of TaxonBase instances (or Taxon instances, if accepted == true, or Synonym instance, if accepted == false)
  93      * where the taxonBase.name.nameCache property matches the String queryString.
  94      * @param doTaxa
  95      * @param doSynonyms
  96      * @param queryString
  97      * @param classification TODO
  98      * @param subtree
  99      * @param matchMode
 100      * @param namedAreas TODO
 101      * @param pageSize
 102      * @param pageNumber
 103      * @param propertyPaths TODO
 104      * @return list of found taxa
 105      */
 106     public List<TaxonBase> getTaxaByName(boolean doTaxa, boolean doSynonyms, boolean doMisappliedNames, boolean doCommonNames,
 107             boolean includeAuthors, String queryString, Classification classification, TaxonNode subtree,
 108             MatchMode matchMode, Set<NamedArea> namedAreas, boolean includeUnpublished,
 109             NameSearchOrder order, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 110
 111     /**
 112      * @param doTaxa
 113      * @param doSynonyms
 114      * @param queryString
 115      * @param classification TODO
 116      * @param subtree
 117      * @param matchMode
 118      * @param namedAreas
 119      * @param pageSize
 120      * @param pageNumber
 121      * @param propertyPaths
 122      * @return
 123      */
 124     public long countTaxaByName(boolean doTaxa, boolean doSynonyms, boolean doMisappliedNames, boolean doCommonNames,
 125             boolean doIncludeAuthors, String queryString, Classification classification, TaxonNode subtree,
 126             MatchMode matchMode, Set<NamedArea> namedAreas, boolean includeUnpublished);
 127
 128
 129     /**
 130      * Returns a count of TaxonBase instances where the
 131      * taxon.name properties match the parameters passed.
 132      *
 133      * @param doTaxa
 134      * @param doSynonyms
 135      * @param uninomial
 136      * @param infragenericEpithet
 137      * @param specificEpithet
 138      * @param infraspecificEpithet
 139      * @param rank
 140      * @return a count of TaxonBase instances
 141      */
 142     public long countTaxaByName(Class <? extends TaxonBase> clazz, String uninomial, String infragenericEpithet,String specificEpithet, String infraspecificEpithet, Rank rank);
 143
 144     /**
 145      * Returns a list of TaxonBase instances where the
 146      * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
 147      * <i>null</i> will search for those taxa with a value of null in that field
 148      * <p>
 149      * Compare with
 150      * {@link #findByName(String, MatchMode, int, int, boolean)}
 151      * which searches for {@link TaxonName}<strong><code>.titleCache</code>
 152      * </strong>
 153      *
 154      * @param doTaxa
 155      * @param doSynonyms
 156      * @param uninomial
 157      * @param infragenericEpithet
 158      * @param specificEpithet
 159      * @param infraspecificEpithet
 160      * @param rank
 161      * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
 162      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 163      * @return a list of TaxonBase instances
 164      */
 165     public List<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, String authorship, Rank rank, Integer pageSize, Integer pageNumber);
 166
 167     /**
 168      * Find taxa by searching for Taxa and Synonyms where the
 169      * {@link TaxonName}<strong><code>.titleCache</code></strong> matches
 170      * the name specified as queryString <code>taxonName</code>
 171      * <P>
 172      * Compare with
 173      * {@link #findTaxaByName(Class, String, String, String, String, Rank, Integer, Integer)}
 174      * which searches for {@link TaxonName}<strong><code>.nameCache</code>
 175      * </strong>
 176      * @param queryString
 177      *            the taqxon Name to search for
 178      * @param classification TODO
 179      * @param matchMode
 180      * @param namedAreas TODO
 181      * @param pageNumber
 182      * @param pageSize
 183      * @param onlyAcccepted
 184      * @return
 185      */
 186     public List<TaxonBase> findByNameTitleCache(boolean doTaxa, boolean doSynonyms, boolean includeUnpublished,
 187             String queryString, Classification classification, TaxonNode subtree, MatchMode matchMode, Set<NamedArea> namedAreas,
 188             NameSearchOrder order, 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 matching Taxa
 221      */
 222     public List<Taxon> getTaxaByCommonName(String queryString, Classification classification,
 223             MatchMode matchMode, Set<NamedArea> namedAreas, Integer pageSize,
 224             Integer pageNumber, List<String> propertyPaths);
 225
 226     /**
 227      * Counts the number of synonyms
 228      * @param onlyAttachedToTaxon if <code>true</code> only those synonyms being attached to
 229      * an accepted taxon are counted
 230      * @return the number of synonyms
 231      */
 232     public long countSynonyms(boolean onlyAttachedToTaxon);
 233
 234     /**
 235      * @param queryString
 236      * @param matchMode
 237      * @param onlyAcccepted
 238      * @return
 239      */
 240     public long countMatchesByName(String queryString, MatchMode matchMode, boolean onlyAcccepted);
 241
 242     /**
 243      * @param queryString
 244      * @param matchMode
 245      * @param onlyAcccepted
 246      * @param criteria
 247      * @return
 248      */
 249     public long countMatchesByName(String queryString, MatchMode matchMode, boolean onlyAcccepted, List<Criterion> criteria);
 250
 251     /**
 252      * Returns a count of the TaxonRelationships (of where relationship.type ==
 253      * type, if this argument is supplied) where the supplied taxon either is
 254      * relatedFrom or relatedTo depending on the <code>direction</code>
 255      * parameter.
 256      *
 257      * @param taxon
 258      *            The taxon that is relatedFrom
 259      * @param type
 260      *            The type of TaxonRelationship (can be null)
 261      * @param direction
 262      *            specifies the direction of the relationship
 263      * @return the number of TaxonRelationship instances
 264      */
 265     public long countTaxonRelationships(Taxon taxon, TaxonRelationshipType type,
 266             boolean includeUnpublished, Direction direction);
 267     public long countTaxonRelationships(Taxon taxon, Set<TaxonRelationshipType> types,
 268             boolean includeUnpublished, Direction direction);
 269
 270     /**
 271      * Returns the TaxonRelationships (of where relationship.type == type, if
 272      * this argument is supplied) where the supplied taxon either is
 273      * relatedFrom or relatedTo depending on the <code>direction</code>
 274      * parameter.
 275      *
 276      * @param taxon
 277      *            The taxon that is relatedTo
 278      * @param type
 279      *            The type of TaxonRelationship (can be null)
 280      * @param pageSize
 281      *            The maximum number of relationships returned (can be null for
 282      *            all relationships)
 283      * @param pageNumber
 284      *            The offset (in pageSize chunks) from the start of the result
 285      *            set (0 - based)
 286      * @param orderHints
 287      *            Properties to order by
 288      * @param propertyPaths
 289      *            Properties to initialize in the returned entities, following
 290      *            the syntax described in
 291      *            {@link IBeanInitializer#initialize(Object, List)}
 292      * @param direction
 293      *            specifies the direction of the relationship
 294      * @return a List of TaxonRelationship instances
 295      */
 296     public List<TaxonRelationship> getTaxonRelationships(Taxon taxon,
 297             TaxonRelationshipType type, boolean includeUnpublished,
 298             Integer pageSize, Integer pageNumber,
 299             List<OrderHint> orderHints, List<String> propertyPaths,
 300             Direction direction);
 301
 302     public List<TaxonRelationship> getTaxonRelationships(Taxon taxon,
 303             Set<TaxonRelationshipType> type, boolean includeUnpublished,
 304             Integer pageSize, Integer pageNumber,
 305             List<OrderHint> orderHints, List<String> propertyPaths,
 306             Direction direction);
 307
 308     /**
 309      * Returns a count of the Synonyms (where relationship.type == type,
 310      *  if this argument is supplied) where the supplied taxon is relatedTo.
 311      *
 312      * @param taxon The taxon that is relatedTo
 313      * @param type The type of Synonym (can be null)
 314      * @return the number of Synonym instances
 315      */
 316     public long countSynonyms(Taxon taxon, SynonymType type);
 317
 318     /**
 319      * Returns the Synonyms (of where relationship.type == type, if this argument is supplied)
 320      * that do have the supplied taxon as accepted taxon.
 321      *
 322      * @param taxon The accepted taxon
 323      * @param type The type of synonym (can be null)
 324      * @param pageSize The maximum number of synonyms returned (can be null for all synonyms)
 325      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 326      * * @param orderHints Properties to order by
 327      * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
 328      * @return a {@link List} of {@link Synonym} instances
 329      */
 330     public List<Synonym> getSynonyms(Taxon taxon, SynonymType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 331
 332     /**
 333      * Returns a count of the synonyms (where relationship.type == type,
 334      * if this argument is supplied) which do have an accepted taxon.
 335      *
 336      * @param synonym The synonym that is relatedFrom
 337      * @param type The type of Synonym (can be null)
 338      * @return the number of Synonym instances
 339      */
 340     public long countSynonyms(Synonym synonym, SynonymType type);
 341
 342     public List<TaxonName> findIdenticalTaxonNames(List<String> propertyPath);
 343
 344     public long countTaxaByCommonName(String searchString,
 345             Classification classification, MatchMode matchMode,
 346             Set<NamedArea> namedAreas);
 347
 348     public List<UUID> findIdenticalTaxonNameIds(List<String> propertyPath);
 349
 350     public List<TaxonName> findIdenticalNamesNew(List <String> propertyPaths);
 351
 352     public List<UuidAndTitleCache<? extends IdentifiableEntity>> getTaxaByNameForEditor(boolean doTaxa, boolean doSynonyms, boolean doNamesWithoutTaxa,
 353             boolean doMisappliedNames, boolean doCommonNames, boolean includeUnpublished,
 354             String queryString, Classification classification, TaxonNode subtree,
 355             MatchMode matchMode, Set<NamedArea> namedAreas, NameSearchOrder order);
 356
 357     public List<String> taxaByNameNotInDB(List<String> taxonNames);
 358
 359     /**
 360      * This method was originally required when synonyms still had a synonym relationship
 361      * to taxa and could belong to multiple taxa. Now the method might be obsolete.
 362      * @param synonym
 363      * @param classificationFilter
 364      * @param propertyPaths
 365      * @see #countAcceptedTaxonFor(Synonym, Classification)
 366      */
 367     public Taxon acceptedTaxonFor(Synonym synonym, Classification classificationFilter, List<String> propertyPaths);
 368
 369     /**
 370      * This method was originally required when synonyms still had a synonym relationship
 371      * to taxa and could belong to multiple taxa. Now the method might be obsolete.@param synonym
 372      * @param classificationFilter
 373      *
 374      * @see #acceptedTaxonFor(Synonym, Classification, Integer, Integer, List, List)
 375      */
 376     public long countAcceptedTaxonFor(Synonym synonym, Classification classificationFilter);
 377
 378         public List<UuidAndTitleCache<Taxon>> getTaxaByCommonNameForEditor(
 379                         String titleSearchStringSqlized, Classification classification,
 380                         MatchMode matchMode, Set<NamedArea> namedAreas);
 381
 382         public <S extends TaxonBase> List<Object[]> findByIdentifier(Class<S> clazz, String identifier,
 383                         DefinedTerm identifierType, TaxonNode subtreeFilter, MatchMode matchmode,
 384                         boolean includeEntity, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 385
 386         /**
 387          * Counts all taxa which match the given identifier (identifier type, identifier string and match mode).
 388          * Optionally a subtreefilter can be defined.
 389          *
 390          * @param clazz optional, the TaxonBase subclass
 391          * @param identifier the identifier string
 392          * @param identifierType the identifier type
 393      * @param matchmode the match mode for the identifier string
 394          * @param subtreeFilter the subtree filter as taxon node
 395          * @return
 396          */
 397         public <S extends TaxonBase> long countByIdentifier(Class<S> clazz,
 398                         String identifier, DefinedTerm identifierType, TaxonNode subtreeFilter, MatchMode matchmode);
 399
 400         /**
 401      * Counts all taxa which have the given marker of type markerType and with value markerValue.
 402      * Additionally an optional subtreefilter can be defined.
 403      *
 404      * @param clazz
 405      * @param markerType
 406      * @param markerValue
 407      * @param subtreeFilter
 408      * @return
 409      */
 410     public <S extends TaxonBase> long countByMarker(Class<S> clazz, MarkerType markerType,
 411             Boolean markerValue, TaxonNode subtreeFilter);
 412
 413     /**
 414      * @param clazz
 415      * @param markerType
 416      * @param markerValue
 417      * @param subtreeFilter
 418      * @param includeEntity
 419      * @param pageSize
 420      * @param pageNumber
 421      * @param propertyPaths
 422      * @return
 423      */
 424     public <S extends TaxonBase> List<Object[]> findByMarker(Class<S> clazz, MarkerType markerType,
 425             Boolean markerValue, TaxonNode subtreeFilter, boolean includeEntity, TaxonTitleType titleType,
 426             Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 427
 428
 429     /**
 430      * @param types
 431      * @return
 432      */
 433     public long countTaxonRelationships(Set<TaxonRelationshipType> types);
 434
 435     /**
 436      * @param types
 437      * @param pageSize
 438      * @param pageNumber
 439      * @param orderHints
 440      * @param propertyPaths
 441      * @return
 442      */
 443     public List<TaxonRelationship> getTaxonRelationships(Set<TaxonRelationshipType> types,
 444             Integer pageSize, Integer pageNumber,
 445             List<OrderHint> orderHints, List<String> propertyPaths);
 446
 447
 448
 449 }