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.List;
  10
  11 import org.springframework.dao.DataAccessException;
  12
  13 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  14 import eu.etaxonomy.cdm.model.description.IndividualsAssociation;
  15 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  16 import eu.etaxonomy.cdm.model.media.Media;
  17 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  18 import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;
  19 import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;
  20 import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;
  21 import eu.etaxonomy.cdm.model.occurrence.FieldUnit;
  22 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;
  23 import eu.etaxonomy.cdm.model.taxon.Taxon;
  24 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  25 import eu.etaxonomy.cdm.persistence.dao.IBeanInitializer;
  26 import eu.etaxonomy.cdm.persistence.dao.common.IIdentifiableDao;
  27 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  28
  29 /**
  30  * @author a.babadshanjan
  31  * @created 01.09.2008
  32  */
  33 public interface IOccurrenceDao extends IIdentifiableDao<SpecimenOrObservationBase> {
  34
  35         /**
  36          * Returns the number of occurences belonging to a certain subclass - which must extend SpecimenOrObservationBase
  37          * @param clazz optionally restrict the counted occurrences to those of a certain subclass of SpecimenOrObservationBase
  38          * @param determinedAs the taxon concept that these specimens are determined to belong to
  39          * @return
  40          */
  41         public int count(Class<? extends SpecimenOrObservationBase> clazz,TaxonBase determinedAs);
  42
  43         /**
  44          * Returns a sublist of SpecimenOrObservationBase instances stored in the database. A maximum
  45          * of 'limit' objects are returned, starting at object with index 'start'. Only occurrences which
  46          * have been determined to belong to the supplied concept are returned.
  47          *
  48          * @param type
  49          * @param determinedAs the taxon concept that these specimens are determined to belong to
  50          * @param limit
  51          *            the maximum number of entities returned (can be null to return
  52          *            all entities)
  53          * @param start
  54          * @param orderHints
  55          *            Supports path like <code>orderHints.propertyNames</code> which
  56          *            include *-to-one properties like createdBy.username or
  57          *            authorTeam.persistentTitleCache
  58          * @return
  59          * @throws DataAccessException
  60          */
  61         public List<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonBase determinedAs, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  62
  63         /**
  64      * Returns a count of Media that are associated with a given occurence
  65      *
  66          * @param occurence the occurence associated with these media
  67      * @return a count of media instances
  68      */
  69         public int countMedia(SpecimenOrObservationBase occurence);
  70
  71     /**
  72      * Returns a List of Media that are associated with a given occurence
  73      *
  74          * @param occurence the occurence associated with these media
  75          * @param pageSize The maximum number of media returned (can be null for all related media)
  76          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  77          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  78      * @return a List of media instances
  79      */
  80         public List<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  81
  82         /**
  83      * Returns a count of determinations that have been made for a given occurence and for a given taxon concept
  84      *
  85          * @param occurence the occurence associated with these determinations (can be null for all occurrences)
  86          * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
  87      * @return a count of determination events
  88      */
  89     public int countDeterminations(SpecimenOrObservationBase occurence,TaxonBase taxonbase);
  90
  91     /**
  92      * Returns a List of determinations that have been made for a given occurence and for a given taxon concept
  93      *
  94          * @param occurence the occurence associated with these determinations (can be null for all occurrences)
  95          * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
  96          * @param pageSize The maximum number of determinations returned (can be null for all related determinations)
  97          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  98          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  99      * @return a List of determination instances
 100      */
 101         public List<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence,TaxonBase taxonbase, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 102
 103         /**
 104      * Returns a count of derivation events that have involved creating new DerivedUnits from this occurence
 105      *
 106          * @param occurence the occurence that was a source of these derivation events
 107      * @return a count of derivation events
 108      */
 109     public int countDerivationEvents(SpecimenOrObservationBase occurence);
 110
 111     /**
 112      * Returns a list of derivation events that have involved creating new DerivedUnits from this occurence
 113      *
 114          * @param occurence the occurence that was a source of these derivation events
 115          * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)
 116          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 117          * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 118      * @return a List of derivation events
 119      */
 120         public List<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 121
 122         public List<UuidAndTitleCache<FieldUnit>> getFieldUnitUuidAndTitleCache();
 123
 124         public List<UuidAndTitleCache<DerivedUnit>> getDerivedUnitUuidAndTitleCache();
 125
 126         /**
 127          * Lists all instances of {@link SpecimenOrObservationBase} which are associated with the <code>taxon</code> specified as parameter.
 128          * SpecimenOrObservationBase instances can be associated to taxa in multiple ways, all these possible relations are taken into account:
 129          * <ul>
 130          * <li>The {@link IndividualsAssociation} elements in a {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 131          * <li>{@link SpecimenTypeDesignation}s may be associated with any {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 132          * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent} of the {@link SpecimenOrObservationBase}</li>
 133          * </ul>
 134          *
 135          * @param <T>
 136          * @param type
 137          * @param associatedTaxon
 138          * @param limit
 139          * @param start
 140          * @param orderHints
 141          * @param propertyPaths
 142          * @return
 143          */
 144         public <T extends SpecimenOrObservationBase> List<T> listByAssociatedTaxon(Class<T> type, Taxon associatedTaxon,
 145                         Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 146
 147
 148
 149 }