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