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