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.io.IOException;
  14 import java.util.List;
  15 import java.util.Set;
  16
  17 import org.apache.lucene.index.CorruptIndexException;
  18 import org.apache.lucene.queryParser.ParseException;
  19 import org.hibernate.search.spatial.impl.Rectangle;
  20
  21 import eu.etaxonomy.cdm.api.facade.DerivedUnitFacade;
  22 import eu.etaxonomy.cdm.api.facade.DerivedUnitFacadeNotSupportedException;
  23 import eu.etaxonomy.cdm.api.service.pager.Pager;
  24 import eu.etaxonomy.cdm.api.service.search.SearchResult;
  25 import eu.etaxonomy.cdm.api.service.util.TaxonRelationshipEdge;
  26 import eu.etaxonomy.cdm.model.common.Language;
  27 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  28 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  29 import eu.etaxonomy.cdm.model.description.IndividualsAssociation;
  30 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  31 import eu.etaxonomy.cdm.model.location.Country;
  32 import eu.etaxonomy.cdm.model.media.Media;
  33 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  34 import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignation;
  35 import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;
  36 import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;
  37 import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;
  38 import eu.etaxonomy.cdm.model.occurrence.FieldUnit;
  39 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;
  40 import eu.etaxonomy.cdm.model.taxon.Taxon;
  41 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  42 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  43 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  44 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  45
  46 /**
  47  * @author a.babadshanjan
  48  * @created 01.09.2008
  49  */
  50 public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenOrObservationBase> {
  51
  52     public Country getCountryByIso(String iso639);
  53
  54     public List<Country> getCountryByName(String name);
  55
  56     /**
  57      * Returns a paged list of occurrences that have been determined to belong
  58      * to the taxon concept determinedAs, optionally restricted to objects
  59      * belonging to a class that that extends SpecimenOrObservationBase.
  60      * <p>
  61      * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this
  62      * method only takes SpecimenOrObservationBase instances into account which
  63      * are actually determined as the taxon specified by
  64      * <code>determinedAs</code>.
  65      *
  66      * @param type
  67      *            The type of entities to return (can be null to count all
  68      *            entities of type <T>)
  69      * @param determinedAs
  70      *            the taxon concept that the occurrences have been determined to
  71      *            belong to
  72      * @param pageSize
  73      *            The maximum number of objects returned (can be null for all
  74      *            matching objects)
  75      * @param pageNumber
  76      *            The offset (in pageSize chunks) from the start of the result
  77      *            set (0 - based, can be null, equivalent of starting at the
  78      *            beginning of the recordset)
  79      * @param orderHints
  80      *            Supports path like <code>orderHints.propertyNames</code> which
  81      *            include *-to-one properties like createdBy.username or
  82      *            authorTeam.persistentTitleCache
  83      * @param propertyPaths
  84      *            properties to be initialized
  85      * @return
  86      */
  87     public Pager<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonBase determinedAs, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  88
  89     /**
  90      * Returns a List of Media that are associated with a given occurence
  91      *
  92      * @param occurence the occurence associated with these media
  93      * @param pageSize The maximum number of media returned (can be null for all related media)
  94      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
  95      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
  96      * @return a Pager of media instances
  97      */
  98     public Pager<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
  99
 100     /**
 101      * Returns a List of determinations that have been made for a given occurence
 102      *
 103      * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 104      * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 105      * @param pageSize The maximum number of determinations returned (can be null for all related determinations)
 106      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 107      * @return a Pager of determination instances
 108      */
 109     public Pager<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence, TaxonBase taxonBase, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 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      * @return a Pager of derivation events
 118      */
 119     public Pager<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 120
 121     /**
 122      * Returns a Paged List of SpecimenOrObservationBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 123      *
 124      * @param clazz filter the results by class (or pass null to return all SpecimenOrObservationBase instances)
 125      * @param queryString
 126      * @param pageSize The maximum number of occurrences returned (can be null for all matching occurrences)
 127      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 128      * @param orderHints
 129      *            Supports path like <code>orderHints.propertyNames</code> which
 130      *            include *-to-one properties like createdBy.username or
 131      *            authorTeam.persistentTitleCache
 132      * @param propertyPaths properties to be initialized
 133      * @return a Pager SpecimenOrObservationBase instances
 134      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 135      */
 136     @Override
 137     public Pager<SpecimenOrObservationBase> search(Class<? extends SpecimenOrObservationBase> clazz, String query, Integer pageSize,Integer pageNumber, List<OrderHint> orderHints,List<String> propertyPaths);
 138
 139     public List<UuidAndTitleCache<FieldUnit>> getFieldUnitUuidAndTitleCache();
 140
 141     public List<UuidAndTitleCache<DerivedUnit>> getDerivedUnitUuidAndTitleCache();
 142
 143     public DerivedUnitFacade getDerivedUnitFacade(DerivedUnit derivedUnit, List<String> propertyPaths) throws DerivedUnitFacadeNotSupportedException;
 144
 145     public List<DerivedUnitFacade> listDerivedUnitFacades(DescriptionBase description, List<String> propertyPaths);
 146
 147     /**
 148      * Lists all instances of {@link SpecimenOrObservationBase} which are
 149      * associated with the <code>taxon</code> specified as parameter.
 150      * SpecimenOrObservationBase instances can be associated to taxa in multiple
 151      * ways, all these possible relations are taken into account:
 152      * <ul>
 153      * <li>The {@link IndividualsAssociation} elements in a
 154      * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 155      * <li>{@link SpecimenTypeDesignation}s may be associated with any
 156      * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 157      * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
 158      * of the {@link SpecimenOrObservationBase}</li>
 159      * </ul>
 160      * Further more there also can be taxa which are associated with the taxon
 161      * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
 162      * the parameter <code>includeRelationships</code> is containing elements,
 163      * these according {@TaxonRelationshipType}s and
 164      * directional information will be used to collect further
 165      * {@link SpecimenOrObservationBase} instances found this way.
 166      *
 167      * @param <T>
 168      * @param type
 169      * @param associatedTaxon
 170      * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
 171      * @param maxDepth TODO
 172      * @param pageSize
 173      * @param pageNumber
 174      * @param orderHints
 175      * @param propertyPaths
 176      * @return
 177      */
 178     public <T extends SpecimenOrObservationBase> List<T> listByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 179             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 180
 181     /**
 182      * See {@link #listByAssociatedTaxon(Class, Set, Taxon, Integer, Integer, Integer, List, List)}
 183      *
 184      * @param type
 185      * @param includeRelationships
 186      * @param associatedTaxon
 187      * @param maxDepth
 188      * @param pageSize
 189      * @param pageNumber
 190      * @param orderHints
 191      * @param propertyPaths
 192      * @return a Pager
 193      */
 194     public <T extends SpecimenOrObservationBase> Pager<T> pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 195             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 196
 197     /**
 198      * @param clazz
 199      * @param queryString
 200      * @param languages
 201      * @param highlightFragments
 202      * @param pageSize
 203      * @param pageNumber
 204      * @param orderHints
 205      * @param propertyPaths
 206      * @return
 207      * @throws CorruptIndexException
 208      * @throws IOException
 209      * @throws ParseException
 210      */
 211     Pager<SearchResult<SpecimenOrObservationBase>> findByFullText(Class<? extends SpecimenOrObservationBase> clazz,
 212             String queryString, Rectangle boundingBox, List<Language> languages, boolean highlightFragments, Integer pageSize,
 213             Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException,
 214             IOException, ParseException;
 215
 216
 217 }