cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IOccurrenceService.java

   1 // $Id$
   2 /**
   3 * Copyright (C) 2009 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10
  11 package eu.etaxonomy.cdm.api.service;
  12
  13 import java.util.List;
  14
  15 import eu.etaxonomy.cdm.api.facade.DerivedUnitFacade;
  16 import eu.etaxonomy.cdm.api.facade.DerivedUnitFacadeNotSupportedException;
  17 import eu.etaxonomy.cdm.api.service.pager.Pager;
  18 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  19 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  20 import eu.etaxonomy.cdm.model.description.IndividualsAssociation;
  21 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  22 import eu.etaxonomy.cdm.model.location.WaterbodyOrCountry;
  23 import eu.etaxonomy.cdm.model.media.Media;
  24 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  25 import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignation;
  26 import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;
  27 import eu.etaxonomy.cdm.model.occurrence.DerivedUnitBase;
  28 import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;
  29 import eu.etaxonomy.cdm.model.occurrence.FieldObservation;
  30 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;
  31 import eu.etaxonomy.cdm.model.taxon.Taxon;
  32 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  33 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  34 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  35
  36 /**
  37  * @author a.babadshanjan
  38  * @created 01.09.2008
  39  */
  40 public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenOrObservationBase> {
  41
  42         public WaterbodyOrCountry getCountryByIso(String iso639);
  43
  44         public List<WaterbodyOrCountry> getWaterbodyOrCountryByName(String name);
  45
  46         /**
  47          * Returns a paged list of occurrences that have been determined to belong
  48          * to the taxon concept determinedAs, optionally restricted to objects
  49          * belonging to a class that that extends SpecimenOrObservationBase.
  50          * <p>
  51          * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this
  52          * method only takes SpecimenOrObservationBase instances into account which
  53          * are actually determined as the taxon specified by
  54          * <code>determinedAs</code>.
  55          *
  56          * @param type
  57          *            The type of entities to return (can be null to count all
  58          *            entities of type <T>)
  59          * @param determinedAs
  60          *            the taxon concept that the occurrences have been determined to
  61          *            belong to
  62          * @param pageSize
  63          *            The maximum number of objects returned (can be null for all
  64          *            matching objects)
  65          * @param pageNumber
  66          *            The offset (in pageSize chunks) from the start of the result
  67          *            set (0 - based, can be null, equivalent of starting at the
  68          *            beginning of the recordset)
  69          * @param orderHints
  70          *            Supports path like <code>orderHints.propertyNames</code> which
  71          *            include *-to-one properties like createdBy.username or
  72          *            authorTeam.persistentTitleCache
  73          * @param propertyPaths
  74          *            properties to be initialized
  75          * @return
  76          */
  77         public Pager<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonBase determinedAs, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  78
  79         /**
  80      * Returns a List of Media that are associated with a given occurence
  81      *
  82          * @param occurence the occurence associated with these media
  83          * @param pageSize The maximum number of media returned (can be null for all related media)
  84          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  85          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
  86      * @return a Pager of media instances
  87      */
  88         public Pager<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  89
  90         /**
  91      * Returns a List of determinations that have been made for a given occurence
  92      *
  93          * @param occurence the occurence associated with these determinations (can be null for all occurrences)
  94          * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
  95          * @param pageSize The maximum number of determinations returned (can be null for all related determinations)
  96          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  97      * @return a Pager of determination instances
  98      */
  99         public Pager<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence, TaxonBase taxonBase, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 100
 101         /**
 102      * Returns a list of derivation events that have involved creating new DerivedUnits from this occurence
 103      *
 104          * @param occurence the occurence that was a source of these derivation events
 105          * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)
 106          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 107      * @return a Pager of derivation events
 108      */
 109         public Pager<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 110
 111         /**
 112          * Returns a Paged List of SpecimenOrObservationBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 113          *
 114          * @param clazz filter the results by class (or pass null to return all SpecimenOrObservationBase instances)
 115          * @param queryString
 116          * @param pageSize The maximum number of occurrences returned (can be null for all matching occurrences)
 117          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 118          * @param orderHints
 119          *            Supports path like <code>orderHints.propertyNames</code> which
 120          *            include *-to-one properties like createdBy.username or
 121          *            authorTeam.persistentTitleCache
 122          * @param propertyPaths properties to be initialized
 123          * @return a Pager SpecimenOrObservationBase instances
 124          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 125          */
 126         public Pager<SpecimenOrObservationBase> search(Class<? extends SpecimenOrObservationBase> clazz, String query, Integer pageSize,Integer pageNumber, List<OrderHint> orderHints,List<String> propertyPaths);
 127
 128         public List<UuidAndTitleCache<FieldObservation>> getFieldObservationUuidAndTitleCache();
 129
 130         public List<UuidAndTitleCache<DerivedUnitBase>> getDerivedUnitBaseUuidAndTitleCache();
 131
 132         public DerivedUnitFacade getDerivedUnitFacade(DerivedUnitBase derivedUnit, List<String> propertyPaths) throws DerivedUnitFacadeNotSupportedException;
 133
 134         public List<DerivedUnitFacade> listDerivedUnitFacades(DescriptionBase description, List<String> propertyPaths);
 135
 136         /**
 137          * Lists all instances of {@link SpecimenOrObservationBase} which are associated with the <code>taxon</code> specified as parameter.
 138          * SpecimenOrObservationBase instances can be associated to taxa in multiple ways, all these possible relations are taken into account:
 139          * <ul>
 140          * <li>The {@link IndividualsAssociation} elements in a {@link TaxonDescription} contain {@link DerivedUnitBase}s</li>
 141          * <li>{@link SpecimenTypeDesignation}s may be associated with any {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 142          * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent} of the {@link SpecimenOrObservationBase}</li>
 143          * </ul>
 144          *
 145          * @param <T>
 146          * @param type
 147          * @param associatedTaxon
 148          * @param limit
 149          * @param start
 150          * @param orderHints
 151          * @param propertyPaths
 152          * @return
 153          */
 154         public <T extends SpecimenOrObservationBase> List<T> listByAnyAssociation(Class<T> type,
 155                         Taxon associatedTaxon, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 156
 157 }