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.dto.DerivateHierarchyDTO;
  26 import eu.etaxonomy.cdm.api.service.pager.Pager;
  27 import eu.etaxonomy.cdm.api.service.search.SearchResult;
  28 import eu.etaxonomy.cdm.api.service.util.TaxonRelationshipEdge;
  29 import eu.etaxonomy.cdm.model.common.Language;
  30 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  31 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  32 import eu.etaxonomy.cdm.model.description.IndividualsAssociation;
  33 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  34 import eu.etaxonomy.cdm.model.location.Country;
  35 import eu.etaxonomy.cdm.model.media.Media;
  36 import eu.etaxonomy.cdm.model.molecular.DnaSample;
  37 import eu.etaxonomy.cdm.model.molecular.Sequence;
  38 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  39 import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignation;
  40 import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;
  41 import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;
  42 import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;
  43 import eu.etaxonomy.cdm.model.occurrence.FieldUnit;
  44 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;
  45 import eu.etaxonomy.cdm.model.taxon.Taxon;
  46 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  47 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  48 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  49 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  50
  51 /**
  52  * @author a.babadshanjan
  53  * @created 01.09.2008
  54  */
  55 public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenOrObservationBase> {
  56
  57     public Country getCountryByIso(String iso639);
  58
  59     public List<Country> getCountryByName(String name);
  60
  61     /**
  62      * Returns a paged list of occurrences that have been determined to belong
  63      * to the taxon concept determinedAs, optionally restricted to objects
  64      * belonging to a class that that extends SpecimenOrObservationBase.
  65      * <p>
  66      * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this
  67      * method only takes SpecimenOrObservationBase instances into account which
  68      * are actually determined as the taxon specified by
  69      * <code>determinedAs</code>.
  70      *
  71      * @param type
  72      *            The type of entities to return (can be null to count all
  73      *            entities of type <T>)
  74      * @param determinedAs
  75      *            the taxon concept that the occurrences have been determined to
  76      *            belong to
  77      * @param pageSize
  78      *            The maximum number of objects returned (can be null for all
  79      *            matching objects)
  80      * @param pageNumber
  81      *            The offset (in pageSize chunks) from the start of the result
  82      *            set (0 - based, can be null, equivalent of starting at the
  83      *            beginning of the recordset)
  84      * @param orderHints
  85      *            Supports path like <code>orderHints.propertyNames</code> which
  86      *            include *-to-one properties like createdBy.username or
  87      *            authorTeam.persistentTitleCache
  88      * @param propertyPaths
  89      *            properties to be initialized
  90      * @return
  91      */
  92     public Pager<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonBase determinedAs, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
  93
  94     /**
  95      * Returns a List of Media that are associated with a given occurence
  96      *
  97      * @param occurence the occurence associated with these media
  98      * @param pageSize The maximum number of media returned (can be null for all related media)
  99      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 100      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 101      * @return a Pager of media instances
 102      */
 103     public Pager<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 104
 105     /**
 106      * Returns a count of determinations that have been made for a given occurence and for a given taxon concept
 107      *
 108      * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 109      * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 110      * @return a count of determination events
 111      */
 112     public int countDeterminations(SpecimenOrObservationBase occurence,TaxonBase taxonbase);
 113
 114     /**
 115      * Returns a List of determinations that have been made for a given occurence
 116      *
 117      * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 118      * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 119      * @param pageSize The maximum number of determinations returned (can be null for all related determinations)
 120      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 121      * @return a Pager of determination instances
 122      */
 123     public Pager<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence, TaxonBase taxonBase, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 124
 125     /**
 126      * Returns a list of derivation events that have involved creating new DerivedUnits from this occurence
 127      *
 128      * @param occurence the occurence that was a source of these derivation events
 129      * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)
 130      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 131      * @return a Pager of derivation events
 132      */
 133     public Pager<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 134
 135     /**
 136      * Returns a Paged List of SpecimenOrObservationBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 137      *
 138      * @param clazz filter the results by class (or pass null to return all SpecimenOrObservationBase instances)
 139      * @param queryString
 140      * @param pageSize The maximum number of occurrences returned (can be null for all matching occurrences)
 141      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 142      * @param orderHints
 143      *            Supports path like <code>orderHints.propertyNames</code> which
 144      *            include *-to-one properties like createdBy.username or
 145      *            authorTeam.persistentTitleCache
 146      * @param propertyPaths properties to be initialized
 147      * @return a Pager SpecimenOrObservationBase instances
 148      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 149      */
 150     @Override
 151     public Pager<SpecimenOrObservationBase> search(Class<? extends SpecimenOrObservationBase> clazz, String query, Integer pageSize,Integer pageNumber, List<OrderHint> orderHints,List<String> propertyPaths);
 152
 153     /**
 154      * Retrieves the {@link UUID} and the string representation (title cache) of all
 155      * {@link FieldUnit}s found in the data base.
 156      * @return a list of {@link UuidAndTitleCache}
 157      */
 158     public List<UuidAndTitleCache<FieldUnit>> getFieldUnitUuidAndTitleCache();
 159
 160     /**
 161      * Retrieves the {@link UUID} and the string representation (title cache) of all
 162      * {@link DerivedUnit}s found in the data base.
 163      * @return a list of {@link UuidAndTitleCache}
 164      */
 165     public List<UuidAndTitleCache<DerivedUnit>> getDerivedUnitUuidAndTitleCache();
 166
 167     public DerivedUnitFacade getDerivedUnitFacade(DerivedUnit derivedUnit, List<String> propertyPaths) throws DerivedUnitFacadeNotSupportedException;
 168
 169     public List<DerivedUnitFacade> listDerivedUnitFacades(DescriptionBase description, List<String> propertyPaths);
 170
 171     /**
 172      * Lists all instances of {@link SpecimenOrObservationBase} which are
 173      * associated with the <code>taxon</code> specified as parameter.
 174      * SpecimenOrObservationBase instances can be associated to taxa in multiple
 175      * ways, all these possible relations are taken into account:
 176      * <ul>
 177      * <li>The {@link IndividualsAssociation} elements in a
 178      * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 179      * <li>{@link SpecimenTypeDesignation}s may be associated with any
 180      * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 181      * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
 182      * of the {@link SpecimenOrObservationBase}</li>
 183      * </ul>
 184      * Further more there also can be taxa which are associated with the taxon
 185      * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
 186      * the parameter <code>includeRelationships</code> is containing elements,
 187      * these according {@TaxonRelationshipType}s and
 188      * directional information will be used to collect further
 189      * {@link SpecimenOrObservationBase} instances found this way.
 190      *
 191      * @param <T>
 192      * @param type
 193      * @param associatedTaxon
 194      * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
 195      * @param maxDepth TODO
 196      * @param pageSize
 197      * @param pageNumber
 198      * @param orderHints
 199      * @param propertyPaths
 200      * @return
 201      */
 202     public <T extends SpecimenOrObservationBase> List<T> listByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 203             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 204
 205     /**
 206      * Lists all instances of {@link FieldUnit} which are
 207      * associated <b>directly or indirectly</b>with the <code>taxon</code> specified
 208      * as parameter. "Indirectly" means that a sub derivate of the FieldUnit is
 209      * directly associated with the given taxon.
 210      * SpecimenOrObservationBase instances can be associated to taxa in multiple
 211      * ways, all these possible relations are taken into account:
 212      * <ul>
 213      * <li>The {@link IndividualsAssociation} elements in a
 214      * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 215      * <li>{@link SpecimenTypeDesignation}s may be associated with any
 216      * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 217      * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
 218      * of the {@link SpecimenOrObservationBase}</li>
 219      * </ul>
 220      * Further more there also can be taxa which are associated with the taxon
 221      * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
 222      * the parameter <code>includeRelationships</code> is containing elements,
 223      * these according {@TaxonRelationshipType}s and
 224      * directional information will be used to collect further
 225      * {@link SpecimenOrObservationBase} instances found this way.
 226      *
 227      * @param <T>
 228      * @param type
 229      * @param associatedTaxon
 230      * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
 231      * @param maxDepth TODO
 232      * @param pageSize
 233      * @param pageNumber
 234      * @param orderHints
 235      * @param propertyPaths
 236      * @return
 237      */
 238     public Collection<FieldUnit> listFieldUnitsByAssociatedTaxon(Set<TaxonRelationshipEdge> includeRelationships,
 239             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 240
 241     /**
 242      * Assembles a {@link DerivateHierarchyDTO} for each "associated" {@link FieldUnit} found for the given {@link Taxon}.<br>
 243      * <br>
 244      * See also {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)}
 245      * @param includeRelationships
 246      * @param associatedTaxon
 247      * @param maxDepth
 248      * @param pageSize
 249      * @param pageNumber
 250      * @param orderHints
 251      * @param propertyPaths
 252      * @return
 253      */
 254     public Collection<DerivateHierarchyDTO> listDerivateHierarchyDTOsByAssociatedTaxon(Set<TaxonRelationshipEdge> includeRelationships,
 255             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 256
 257     /**
 258      * See {@link #listByAssociatedTaxon(Class, Set, Taxon, Integer, Integer, Integer, List, List)}
 259      *
 260      * @param type
 261      * @param includeRelationships
 262      * @param associatedTaxon
 263      * @param maxDepth
 264      * @param pageSize
 265      * @param pageNumber
 266      * @param orderHints
 267      * @param propertyPaths
 268      * @return a Pager
 269      */
 270     public <T extends SpecimenOrObservationBase> Pager<T> pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 271             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 272
 273     /**
 274      * Retrieves all {@link FieldUnit}s for the {@link SpecimenOrObservationBase} with the given {@link UUID}.<br>
 275      * @param specimenUuid the UUID of the specimen
 276      * @return either a collection of FieldUnits this specimen was derived from, the FieldUnit itself
 277      * if this was a FieldUnit or an empty collection if no FieldUnits were found
 278      */
 279     public Collection<FieldUnit> getFieldUnits(UUID specimenUuid);
 280
 281     /**
 282      * @param clazz
 283      * @param queryString
 284      * @param languages
 285      * @param highlightFragments
 286      * @param pageSize
 287      * @param pageNumber
 288      * @param orderHints
 289      * @param propertyPaths
 290      * @return
 291      * @throws CorruptIndexException
 292      * @throws IOException
 293      * @throws ParseException
 294      */
 295     Pager<SearchResult<SpecimenOrObservationBase>> findByFullText(Class<? extends SpecimenOrObservationBase> clazz,
 296             String queryString, Rectangle boundingBox, List<Language> languages, boolean highlightFragments, Integer pageSize,
 297             Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws CorruptIndexException,
 298             IOException, ParseException;
 299     /**
 300      * See {@link #listByAssociatedTaxon(Class, Set, String, Integer, Integer, Integer, List, List)}
 301      *
 302      * @param type
 303      * @param includeRelationships
 304      * @param associatedTaxon
 305      * @param maxDepth
 306      * @param pageSize
 307      * @param pageNumber
 308      * @param orderHints
 309      * @param propertyPaths
 310      * @return a Pager
 311      */
 312     public <T extends SpecimenOrObservationBase> Pager<T>  pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 313             String taxonUUID, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 314
 315     /**
 316      * Moves the given {@link Sequence} from one {@link DnaSample} to another
 317      * @param from the DnaSample from which the sequence will be removed
 318      * @param to the DnaSample which to which the sequence will be added
 319      * @param sequence the Sequence to move
 320      * @return <code>true</code> if successfully moved, <code>false</code> otherwise
 321      */
 322     public boolean moveSequence(DnaSample from, DnaSample to, Sequence sequence);
 323
 324     /**
 325      * Moves the given {@link DerivedUnit} from one {@link SpecimenOrObservationBase} to another.
 326      * @param from the SpecimenOrObservationBase from which the DerivedUnit will be removed
 327      * @param to the SpecimenOrObservationBase to which the DerivedUnit will be added
 328      * @param derivate the DerivedUnit to move
 329      * @return <code>true</code> if successfully moved, <code>false</code> otherwise
 330      */
 331     public boolean moveDerivate(SpecimenOrObservationBase<?> from, SpecimenOrObservationBase<?> to, DerivedUnit derivate);
 332
 333 }