cdmlib-persistence/src/main/java/eu/etaxonomy/cdm/persistence/dao/occurrence/IOccurrenceDao.java

   1 /**
   2 * Copyright (C) 2008 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 */
   6
   7 package eu.etaxonomy.cdm.persistence.dao.occurrence;
   8
   9 import java.util.Collection;
  10 import java.util.List;
  11 import java.util.UUID;
  12
  13 import org.springframework.dao.DataAccessException;
  14
  15 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  16 import eu.etaxonomy.cdm.model.description.IndividualsAssociation;
  17 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  18 import eu.etaxonomy.cdm.model.media.Media;
  19 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  20 import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignation;
  21 import eu.etaxonomy.cdm.model.name.TaxonName;
  22 import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;
  23 import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;
  24 import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;
  25 import eu.etaxonomy.cdm.model.occurrence.FieldUnit;
  26 import eu.etaxonomy.cdm.model.occurrence.GatheringEvent;
  27 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;
  28 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationType;
  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.persistence.dao.common.IIdentifiableDao;
  33 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  34 import eu.etaxonomy.cdm.persistence.dto.SpecimenNodeWrapper;
  35 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  36 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  37 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  38
  39 /**
  40  * @author a.babadshanjan
  41  * @since 01.09.2008
  42  */
  43 public interface IOccurrenceDao extends IIdentifiableDao<SpecimenOrObservationBase> {
  44
  45     /**
  46      * Returns the number of occurences belonging to a certain subclass - which must extend SpecimenOrObservationBase
  47      * @param clazz optionally restrict the counted occurrences to those of a certain subclass of SpecimenOrObservationBase
  48      * @param determinedAs the taxon name that these specimens are determined to belong to
  49      * @return
  50      */
  51     public long count(Class<? extends SpecimenOrObservationBase> clazz,TaxonName determinedAs);
  52
  53     /**
  54      * Returns a sublist of SpecimenOrObservationBase instances stored in the database. A maximum
  55      * of 'limit' objects are returned, starting at object with index 'start'. Only occurrences which
  56      * have been determined to belong to the supplied name are returned.
  57      *
  58      * @param type
  59      * @param determinedAs the taxon name that these specimens are determined to belong to
  60      * @param orderHints
  61      *            Supports path like <code>orderHints.propertyNames</code> which
  62      *            include *-to-one properties like createdBy.username or
  63      *            authorTeam.persistentTitleCache
  64      * @return
  65      * @throws DataAccessException
  66      */
  67     public List<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonName determinedAs,
  68             Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
  69
  70     /**
  71          * Returns the number of occurences belonging to a certain subclass - which must extend SpecimenOrObservationBase
  72          * @param clazz optionally restrict the counted occurrences to those of a certain subclass of SpecimenOrObservationBase
  73          * @param determinedAs the taxon concept that these specimens are determined to belong to
  74          * @return
  75          */
  76         public long count(Class<? extends SpecimenOrObservationBase> clazz,TaxonBase determinedAs);
  77
  78         /**
  79          * Returns a sublist of SpecimenOrObservationBase instances stored in the database. A maximum
  80          * of 'limit' objects are returned, starting at object with index 'start'. Only occurrences which
  81          * have been determined to belong to the supplied concept are returned.
  82          *
  83          * @param type
  84          * @param determinedAs the taxon concept that these specimens are determined to belong to
  85          * @param orderHints
  86          *            Supports path like <code>orderHints.propertyNames</code> which
  87          *            include *-to-one properties like createdBy.username or
  88          *            authorTeam.persistentTitleCache
  89          * @return
  90          * @throws DataAccessException
  91          */
  92         public List<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonBase determinedAs,
  93                 Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
  94
  95         /**
  96      * Queries the database for specimens which match the given criteria<br>
  97      * <b>Note:</b> Specifying a taxon will already check the name of this
  98      * taxon, its synonymy and the synonym names for determinations of the
  99      * specimen. So specifying a taxon name is only necessary if it does not
 100      * belong to the before-mentioned group of names.
 101      *
 102      * @param clazz
 103      *            the class to match
 104      * @param queryString
 105      *            the queryString to match
 106      * @param type
 107      *            the {@link SpecimenOrObservationType} to match
 108      * @param associatedTaxon
 109      *            the taxon these specimens are in any way associated to via
 110      *            determination, type designations, individuals associations,
 111      *            etc.
 112      * @param associatedTaxonName
 113      *            the taxon name that the specimens have been determined as
 114      * @param matchmode
 115      *            determines how the query string should be matched
 116      * @param limit
 117      *            the maximum number of entities returned (can be null to return
 118      *            all entities)
 119      * @param start
 120      * @param orderHints
 121      *            Supports path like <code>orderHints.propertyNames</code> which
 122      *            include *-to-one properties like createdBy.username or
 123      *            authorTeam.persistentTitleCache
 124      * @param propertyPaths
 125      * @return a list of specimens that match the given parameters
 126      */
 127     public <T extends SpecimenOrObservationBase> List<T> findOccurrences(Class<T> clazz, String queryString,
 128             String significantIdentifier, SpecimenOrObservationType type, Taxon determinedAs,
 129             TaxonName associatedTaxonName, MatchMode matchmode, Integer limit, Integer start,
 130             List<OrderHint> orderHints, List<String> propertyPaths);
 131
 132     /**
 133      * @see IOccurrenceDao#findOccurrences(Class, String, String, SpecimenOrObservationType, Taxon, TaxonName, MatchMode, Integer, Integer, List, List)
 134      * @param clazz
 135      * @param queryString
 136      * @param significantIdentifier
 137      * @param type
 138      * @param determinedAs
 139      * @param associatedTaxonName
 140      * @param matchmode
 141      * @param limit
 142      * @param start
 143      * @param orderHints
 144      * @param propertyPaths
 145      * @return
 146      */
 147     public <T extends SpecimenOrObservationBase> List<UuidAndTitleCache<SpecimenOrObservationBase>> findOccurrencesUuidAndTitleCache(
 148             Class<T> clazz, String queryString,
 149             String significantIdentifier, SpecimenOrObservationType type, Taxon determinedAs,
 150             TaxonName associatedTaxonName, MatchMode matchmode, Integer limit, Integer start,
 151             List<OrderHint> orderHints);
 152
 153     /**
 154      * Returns the number of specimens that match the given parameters
 155      * <b>Note:</b> Specifying a taxon will already check the name of this
 156      * taxon, its synonymy and the synonym names for determinations of the
 157      * specimen. So specifying a taxon name is only necessary if it does not
 158      * belong to the before-mentioned group of names.
 159      *
 160      * @param clazz
 161      *            the class to match
 162      * @param queryString
 163      *            the queryString to match
 164      * @param type
 165      *            the {@link SpecimenOrObservationType} to match
 166      * @param associatedTaxon
 167      *            the taxon these specimens are in any way associated to via
 168      *            determination, type designations, individuals associations,
 169      *            etc.
 170      * @param associatedTaxonName
 171      *            the taxon name that the specimens have been determined as
 172      * @param matchmode
 173      *            determines how the query string should be matched
 174      * @param limit
 175      *            the maximum number of entities returned (can be null to return
 176      *            all entities)
 177      * @param start
 178      * @param orderHints
 179      *            Supports path like <code>orderHints.propertyNames</code> which
 180      *            include *-to-one properties like createdBy.username or
 181      *            authorTeam.persistentTitleCache
 182      * @return the number of found specimens
 183      */
 184     public <T extends SpecimenOrObservationBase> long countOccurrences(Class<T> clazz, String queryString,
 185             String significantIdentifier, SpecimenOrObservationType recordBasis, Taxon associatedTaxon,
 186             TaxonName associatedTaxonName, MatchMode matchmode, Integer limit, Integer start,
 187             List<OrderHint> orderHints, List<String> propertyPaths);
 188
 189         /**
 190      * Returns a count of Media that are associated with a given occurence
 191      *
 192          * @param occurence the occurence associated with these media
 193      * @return a count of media instances
 194      */
 195         public long countMedia(SpecimenOrObservationBase occurence);
 196
 197     /**
 198      * Returns a List of Media that are associated with a given occurence
 199      *
 200          * @param occurence the occurence associated with these media
 201          * @param pageSize The maximum number of media returned (can be null for all related media)
 202          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 203          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 204      * @return a List of media instances
 205      */
 206         public List<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 207
 208         /**
 209      * Returns a count of determinations that have been made for a given occurence and for a given taxon concept
 210      *
 211          * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 212          * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 213      * @return a count of determination events
 214      */
 215     public long countDeterminations(SpecimenOrObservationBase occurence,TaxonBase taxonbase);
 216
 217     /**
 218      * Returns a List of determinations that have been made for a given occurence and for a given taxon concept
 219      *
 220          * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 221          * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 222          * @param pageSize The maximum number of determinations returned (can be null for all related determinations)
 223          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 224          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 225      * @return a List of determination instances
 226      */
 227         public List<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence,TaxonBase taxonbase, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 228
 229         /**
 230      * Returns a count of derivation events that have involved creating new DerivedUnits from this occurence
 231      *
 232          * @param occurence the occurence that was a source of these derivation events
 233      * @return a count of derivation events
 234      */
 235     public long countDerivationEvents(SpecimenOrObservationBase occurence);
 236
 237     /**
 238      * Returns a list of derivation events that have involved creating new DerivedUnits from this occurence
 239      *
 240          * @param occurence the occurence that was a source of these derivation events
 241          * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)
 242          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 243          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 244      * @return a List of derivation events
 245      */
 246         public List<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 247
 248     /**
 249      * Retrieves the {@link UUID} and the string representation (title cache) of all
 250      * {@link FieldUnit}s found in the data base.
 251      * @return a list of {@link UuidAndTitleCache}
 252      */
 253         public List<UuidAndTitleCache<FieldUnit>> getFieldUnitUuidAndTitleCache();
 254
 255     /**
 256      * Retrieves the {@link UUID} and the string representation (title cache) of all
 257      * {@link DerivedUnit}s found in the data base.
 258      * @return a list of {@link UuidAndTitleCache}
 259      */
 260         public List<UuidAndTitleCache<DerivedUnit>> getDerivedUnitUuidAndTitleCache(Integer limit, String pattern);
 261
 262         /**
 263          * Lists all instances of {@link SpecimenOrObservationBase} which are determined as the <code>taxon name</code> specified as parameter.
 264          *
 265          * @param <T>
 266          * @param type
 267          * @param associatedTaxonName
 268          * @param limit
 269          * @param start
 270          * @param orderHints
 271          * @param propertyPaths
 272          * @return
 273          */
 274         public <T extends SpecimenOrObservationBase> List<T> listByAssociatedTaxonName(Class<T> type,
 275             TaxonName associatedTaxonName, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 276
 277         /**
 278          * Lists all instances of {@link SpecimenOrObservationBase} which are associated with the <code>taxon</code> specified as parameter.
 279          * SpecimenOrObservationBase instances can be associated to taxa in multiple ways, all these possible relations are taken into account:
 280          * <ul>
 281          * <li>The {@link IndividualsAssociation} elements in a {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 282          * <li>{@link SpecimenTypeDesignation}s may be associated with any {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 283          * <li>A {@link Taxon} or a {@link TaxonName} may be referenced by the {@link DeterminationEvent} of the {@link SpecimenOrObservationBase}</li>
 284          * </ul>
 285          *
 286          * @param <T>
 287          * @param type
 288          * @param associatedTaxon
 289          * @param limit
 290          * @param start
 291          * @param orderHints
 292          * @param propertyPaths
 293          * @return
 294          */
 295         public <T extends SpecimenOrObservationBase> List<T> listByAssociatedTaxon(Class<T> type, Taxon associatedTaxon,
 296                         Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 297
 298         /**
 299          * @see IOccurrenceDao#listByAssociatedTaxon(Class, Taxon, Integer, Integer, List, List)
 300          * @param type
 301          * @param associatedTaxon
 302          * @param limit
 303          * @param start
 304          * @param orderHints
 305          * @param propertyPaths
 306          * @return
 307          */
 308         public <T extends SpecimenOrObservationBase> List<UuidAndTitleCache<SpecimenOrObservationBase>> listUuidAndTitleCacheByAssociatedTaxon(Class<T> type, Taxon associatedTaxon,
 309                 Integer limit, Integer start, List<OrderHint> orderHints);
 310
 311     /**
 312      * The method will search for specimen associated with the taxon nodes.<br>
 313      * It will search for 3 possible association types:
 314      * : <br>
 315      *  - via IndividualAssociations of the taxon<br>
 316      *  - via TypeDesignations of the taxon name<br>
 317      *  - via Determinations of the taxon or taxon name<br>
 318      *  <br>
 319      *  (more are covered in
 320      * {@link IOccurrenceDao#findOccurrences(Class, String, String, SpecimenOrObservationType, Taxon, TaxonName, MatchMode, Integer, Integer, List, List)}
 321      * @param taxonNodeUuids a list of {@link UUID}s of the taxon nodes
 322      * @param limit
 323      * @param start
 324      * @return a collection of {@link SpecimenNodeWrapper} containing the {@link TaxonNode}
 325      * and the corresponding {@link UuidAndTitleCache}  object for the specimen found for this taxon node
 326      */
 327         public Collection<SpecimenNodeWrapper> listUuidAndTitleCacheByAssociatedTaxon(List<UUID> taxonNodeUuids,
 328             Integer limit, Integer start);
 329
 330     /**
 331      * Retrieves all {@link IndividualsAssociation} with the given specimen.<br>
 332      * @param specimen the specimen for which the associations are retrieved
 333      * @param limit
 334      * @param start
 335      * @param orderHints
 336      * @param propertyPaths
 337      * @return collection of all associations
 338      */
 339         public Collection<IndividualsAssociation> listIndividualsAssociations(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 340
 341         /**
 342          * Retrieves all {@link SpecimenTypeDesignation}s which have the given specimen as a type specimen.
 343          * @param specimen the type specimen
 344          * @param limit
 345          * @param start
 346          * @param orderHints
 347          * @param propertyPaths
 348          * @return collection of all designations with the given type specimen
 349          */
 350
 351         /**
 352      * Retrieves all {@link DeterminationEvent}s which have the given specimen set as identified unit.
 353          * @param specimen
 354          * @param limit
 355          * @param start
 356          * @param orderHints
 357          * @param propertyPaths
 358          * @return collection of all determinations with the given specimen
 359          */
 360     public Collection<DeterminationEvent> listDeterminationEvents(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 361
 362     /**
 363      * Retrieves all {@link SpecimenTypeDesignation}s which have the given specimen as a type specimen.
 364      * @param specimen the type specimen
 365      * @param limit
 366      * @param start
 367      * @param orderHints
 368      * @param propertyPaths
 369      * @return collection of all designations with the given type specimen
 370      */
 371     public Collection<SpecimenTypeDesignation> listTypeDesignations(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 372
 373     /**
 374      * Retrieves all {@link DescriptionBase}s that have the given specimen set as described specimen.
 375      * @param specimen the described specimen
 376      * @param limit
 377      * @param start
 378      * @param orderHints
 379      * @param propertyPaths
 380      * @return collection of all descriptions with the given described specimen
 381      */
 382     public Collection<DescriptionBase<?>> listDescriptionsWithDescriptionSpecimen(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 383
 384     /**
 385      * Retrieves all {@link SpecimenOrObservationBase}s that have the given {@link SpecimenOrObservationType}.
 386      * @param type
 387      * @param limit
 388      * @param start
 389      * @param orderHints
 390      * @param propertyPaths
 391      * @return collection of specimen with the given type
 392      */
 393     public Collection<SpecimenOrObservationBase> listBySpecimenOrObservationType(SpecimenOrObservationType type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 394
 395     /**
 396      *
 397      * Returns all {@link FieldUnit}s that are referencing this {@link GatheringEvent}
 398      * @param gatheringEventUuid the {@link UUID} of the gathering event
 399      * @param limit
 400      * @param start
 401      * @param orderHints
 402      * @param propertyPaths
 403      * @return a list of field units referencing the gathering event
 404      */
 405     public List<FieldUnit> getFieldUnitsForGatheringEvent(UUID gatheringEventUuid, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 406
 407     /**
 408     *
 409     * Returns {@link DerivedUNit} that has the accession number
 410     * @param accessionNumber
 411     * @param propertyPaths
 412     * @return a derived unit
 413     */
 414    public List<DerivedUnit> getByGeneticAccessionNumber(String accessionNumberString, List<String> propertyPaths);
 415 }