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

   1 /**
   2 * Copyright (C) 2009 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9
  10 package eu.etaxonomy.cdm.api.service;
  11
  12 import java.io.IOException;
  13 import java.util.Collection;
  14 import java.util.HashMap;
  15 import java.util.List;
  16 import java.util.Map;
  17 import java.util.Set;
  18 import java.util.UUID;
  19
  20 import org.apache.lucene.index.CorruptIndexException;
  21 import org.hibernate.search.spatial.impl.Rectangle;
  22 import org.springframework.transaction.annotation.Transactional;
  23
  24 import eu.etaxonomy.cdm.api.facade.DerivedUnitFacade;
  25 import eu.etaxonomy.cdm.api.facade.DerivedUnitFacadeNotSupportedException;
  26 import eu.etaxonomy.cdm.api.service.config.FindOccurrencesConfigurator;
  27 import eu.etaxonomy.cdm.api.service.config.IIdentifiableEntityServiceConfigurator;
  28 import eu.etaxonomy.cdm.api.service.config.SpecimenDeleteConfigurator;
  29 import eu.etaxonomy.cdm.api.service.dto.DerivedUnitDTO;
  30 import eu.etaxonomy.cdm.api.service.dto.FieldUnitDTO;
  31 import eu.etaxonomy.cdm.api.service.dto.SpecimenOrObservationBaseDTO;
  32 import eu.etaxonomy.cdm.api.service.pager.Pager;
  33 import eu.etaxonomy.cdm.api.service.search.LuceneParseException;
  34 import eu.etaxonomy.cdm.api.service.search.SearchResult;
  35 import eu.etaxonomy.cdm.api.service.util.TaxonRelationshipEdge;
  36 import eu.etaxonomy.cdm.model.common.Language;
  37 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  38 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  39 import eu.etaxonomy.cdm.model.description.IndividualsAssociation;
  40 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  41 import eu.etaxonomy.cdm.model.location.Country;
  42 import eu.etaxonomy.cdm.model.location.Point;
  43 import eu.etaxonomy.cdm.model.media.Media;
  44 import eu.etaxonomy.cdm.model.molecular.DnaSample;
  45 import eu.etaxonomy.cdm.model.molecular.Sequence;
  46 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  47 import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignation;
  48 import eu.etaxonomy.cdm.model.name.TaxonName;
  49 import eu.etaxonomy.cdm.model.occurrence.DerivationEvent;
  50 import eu.etaxonomy.cdm.model.occurrence.DerivedUnit;
  51 import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent;
  52 import eu.etaxonomy.cdm.model.occurrence.FieldUnit;
  53 import eu.etaxonomy.cdm.model.occurrence.GatheringEvent;
  54 import eu.etaxonomy.cdm.model.occurrence.MediaSpecimen;
  55 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase;
  56 import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationType;
  57 import eu.etaxonomy.cdm.model.taxon.Taxon;
  58 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  59 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  60 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
  61 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  62 import eu.etaxonomy.cdm.persistence.dto.SpecimenNodeWrapper;
  63 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  64 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  65
  66 /**
  67  * @author a.babadshanjan
  68  * @since 01.09.2008
  69  */
  70 public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenOrObservationBase> {
  71
  72     public Country getCountryByIso(String iso639);
  73
  74     public List<Country> getCountryByName(String name);
  75
  76     /**
  77      * Returns a paged list of occurrences that have been determined to belong
  78      * to the taxon concept determinedAs, optionally restricted to objects
  79      * belonging to a class that that extends SpecimenOrObservationBase. This
  80      * will also consider specimens that are determined as a taxon concept
  81      * belonging to the synonymy of the given taxon concept.
  82      * <p>
  83      * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this
  84      * method only takes SpecimenOrObservationBase instances into account which
  85      * are actually determined as the taxon specified by
  86      * <code>determinedAs</code>.
  87      *
  88      * @param type
  89      *            The type of entities to return (can be null to count all
  90      *            entities of type <T>)
  91      * @param determinedAs
  92      *            the taxon concept that the occurrences have been determined to
  93      *            belong to
  94      * @param pageSize
  95      *            The maximum number of objects returned (can be null for all
  96      *            matching objects)
  97      * @param pageNumber
  98      *            The offset (in pageSize chunks) from the start of the result
  99      *            set (0 - based, can be null, equivalent of starting at the
 100      *            beginning of the recordset)
 101      * @param orderHints
 102      *            Supports path like <code>orderHints.propertyNames</code> which
 103      *            include *-to-one properties like createdBy.username or
 104      *            authorTeam.persistentTitleCache
 105      * @param propertyPaths
 106      *            properties to be initialized
 107      * @return
 108      */
 109     public Pager<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonBase determinedAs, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 110
 111     /**
 112      * Returns a paged list of occurrences that have been determined to belong
 113      * to the taxon name determinedAs, optionally restricted to objects
 114      * belonging to a class that that extends SpecimenOrObservationBase.
 115      * <p>
 116      * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this
 117      * method only takes SpecimenOrObservationBase instances into account which
 118      * are actually determined as the taxon specified by
 119      * <code>determinedAs</code>.
 120      *
 121      * @param type
 122      *            The type of entities to return (can be null to count all
 123      *            entities of type <T>)
 124      * @param determinedAs
 125      *            the taxon name that the occurrences have been determined to
 126      *            belong to
 127      * @param pageSize
 128      *            The maximum number of objects returned (can be null for all
 129      *            matching objects)
 130      * @param pageNumber
 131      *            The offset (in pageSize chunks) from the start of the result
 132      *            set (0 - based, can be null, equivalent of starting at the
 133      *            beginning of the recordset)
 134      * @param orderHints
 135      *            Supports path like <code>orderHints.propertyNames</code> which
 136      *            include *-to-one properties like createdBy.username or
 137      *            authorTeam.persistentTitleCache
 138      * @param propertyPaths
 139      *            properties to be initialized
 140      * @return
 141      */
 142     public Pager<SpecimenOrObservationBase> list(Class<? extends SpecimenOrObservationBase> type, TaxonName determinedAs, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 143
 144     /**
 145      * Returns a List of Media that are associated with a given occurence
 146      *
 147      * @param occurence the occurence associated with these media
 148      * @param pageSize The maximum number of media returned (can be null for all related media)
 149      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 150      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 151      * @return a Pager of media instances
 152      */
 153     public Pager<Media> getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 154
 155     /**
 156      * Returns all media attached to this occurence and its children. Also takes
 157      * {@link MediaSpecimen} and molecular images into account.
 158      *
 159      * @param occurence the occurence and its children from which the media to get
 160      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 161      * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
 162      * @return a Pager of media instances
 163      */
 164     public Pager<Media> getMediainHierarchy(SpecimenOrObservationBase rootOccurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 165
 166     /**
 167      * Returns a count of determinations that have been made for a given occurence and for a given taxon concept
 168      *
 169      * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 170      * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 171      * @return a count of determination events
 172      */
 173     public long countDeterminations(SpecimenOrObservationBase occurence,TaxonBase taxonbase);
 174
 175     /**
 176      * Returns a List of determinations that have been made for a given occurence
 177      *
 178      * @param occurence the occurence associated with these determinations (can be null for all occurrences)
 179      * @param taxonbase the taxon concept associated with these determinations (can be null for all taxon concepts)
 180      * @param pageSize The maximum number of determinations returned (can be null for all related determinations)
 181      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 182      * @return a Pager of determination instances
 183      */
 184     public Pager<DeterminationEvent> getDeterminations(SpecimenOrObservationBase occurence, TaxonBase taxonBase, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 185
 186     /**
 187      * Returns a list of derivation events that have involved creating new DerivedUnits from this occurence
 188      *
 189      * @param occurence the occurence that was a source of these derivation events
 190      * @param pageSize The maximum number of derivation events returned (can be null for all related derivation events)
 191      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 192      * @return a Pager of derivation events
 193      */
 194     public Pager<DerivationEvent> getDerivationEvents(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 195
 196     /**
 197      * Returns a Paged List of SpecimenOrObservationBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 198      *
 199      * @param clazz filter the results by class (or pass null to return all SpecimenOrObservationBase instances)
 200      * @param queryString
 201      * @param pageSize The maximum number of occurrences returned (can be null for all matching occurrences)
 202      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 203      * @param orderHints
 204      *            Supports path like <code>orderHints.propertyNames</code> which
 205      *            include *-to-one properties like createdBy.username or
 206      *            authorTeam.persistentTitleCache
 207      * @param propertyPaths properties to be initialized
 208      * @return a Pager SpecimenOrObservationBase instances
 209      * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 210      */
 211     @Override
 212     public Pager<SpecimenOrObservationBase> search(Class<? extends SpecimenOrObservationBase> clazz, String query, Integer pageSize,Integer pageNumber, List<OrderHint> orderHints,List<String> propertyPaths);
 213
 214     /**
 215      * Retrieves the {@link UUID} and the string representation (title cache) of all
 216      * {@link FieldUnit}s found in the data base.
 217      * @return a list of {@link UuidAndTitleCache}
 218      */
 219     public List<UuidAndTitleCache<FieldUnit>> getFieldUnitUuidAndTitleCache();
 220
 221     /**
 222      * Retrieves the {@link UUID} and the string representation (title cache) of all
 223      * {@link DerivedUnit}s found in the data base.
 224      * @return a list of {@link UuidAndTitleCache}
 225      */
 226     public List<UuidAndTitleCache<DerivedUnit>> getDerivedUnitUuidAndTitleCache(Integer limit, String pattern);
 227
 228     public DerivedUnitFacade getDerivedUnitFacade(DerivedUnit derivedUnit, List<String> propertyPaths) throws DerivedUnitFacadeNotSupportedException;
 229
 230     public List<DerivedUnitFacade> listDerivedUnitFacades(DescriptionBase description, List<String> propertyPaths);
 231
 232     /**
 233      * Lists all instances of {@link SpecimenOrObservationBase} which are
 234      * associated with the <code>taxon</code> specified as parameter.
 235      * SpecimenOrObservationBase instances can be associated to taxa in multiple
 236      * ways, all these possible relations are taken into account:
 237      * <ul>
 238      * <li>The {@link IndividualsAssociation} elements in a
 239      * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 240      * <li>{@link SpecimenTypeDesignation}s may be associated with any
 241      * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 242      * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
 243      * of the {@link SpecimenOrObservationBase}</li>
 244      * </ul>
 245      * Further more there also can be taxa which are associated with the taxon
 246      * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
 247      * the parameter <code>includeRelationships</code> is containing elements,
 248      * these according {@TaxonRelationshipType}s and
 249      * directional information will be used to collect further
 250      * {@link SpecimenOrObservationBase} instances found this way.
 251      *
 252      * @param <T>
 253      * @param type
 254      * @param associatedTaxon
 255      * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
 256      * @param maxDepth TODO
 257      * @param pageSize
 258      * @param pageNumber
 259      * @param orderHints
 260      * @param propertyPaths
 261      * @return
 262      */
 263     public <T extends SpecimenOrObservationBase> List<T> listByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 264             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 265
 266     /**
 267      * The method will search for specimen associated with the taxon nodes.<br>
 268      * It will search for 3 possible association types: <br>
 269      * - via IndividualAssociations of the taxon<br>
 270      *  - via TypeDesignations of the taxon name<br>
 271      *  - via Determinations of the taxon or taxon name<br>
 272      * <br>
 273      * more are covered in
 274      * {@link IOccurrenceService#findByTitle(IIdentifiableEntityServiceConfigurator)}
 275      * @param taxonNodeUuids
 276      *            a list of {@link UUID}s of the taxon nodes
 277      * @param limit
 278      * @param start
 279      * @return a collection of {@link SpecimenNodeWrapper} containing the
 280      *         {@link TaxonNode} and the corresponding {@link UuidAndTitleCache}
 281      *         object for the specimen found for this taxon node
 282      */
 283     public Collection<SpecimenNodeWrapper> listUuidAndTitleCacheByAssociatedTaxon(List<UUID> taxonNodeUuids,
 284             Integer limit, Integer start);
 285
 286
 287     /**
 288      * Lists all instances of {@link FieldUnit} which are
 289      * associated <b>directly or indirectly</b>with the <code>taxon</code> specified
 290      * as parameter. "Indirectly" means that a sub derivate of the FieldUnit is
 291      * directly associated with the given taxon.
 292      * SpecimenOrObservationBase instances can be associated to taxa in multiple
 293      * ways, all these possible relations are taken into account:
 294      * <ul>
 295      * <li>The {@link IndividualsAssociation} elements in a
 296      * {@link TaxonDescription} contain {@link DerivedUnit}s</li>
 297      * <li>{@link SpecimenTypeDesignation}s may be associated with any
 298      * {@link HomotypicalGroup} related to the specific {@link Taxon}.</li>
 299      * <li>A {@link Taxon} may be referenced by the {@link DeterminationEvent}
 300      * of the {@link SpecimenOrObservationBase}</li>
 301      * </ul>
 302      * Further more there also can be taxa which are associated with the taxon
 303      * in question (parameter associatedTaxon) by {@link TaxonRelationship}s. If
 304      * the parameter <code>includeRelationships</code> is containing elements,
 305      * these according {@TaxonRelationshipType}s and
 306      * directional information will be used to collect further
 307      * {@link SpecimenOrObservationBase} instances found this way.
 308      *
 309      * @param <T>
 310      * @param type
 311      * @param associatedTaxon
 312      * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.
 313      * @param maxDepth TODO
 314      * @param pageSize
 315      * @param pageNumber
 316      * @param orderHints
 317      * @param propertyPaths
 318      * @return
 319      */
 320     public Collection<SpecimenOrObservationBase> listFieldUnitsByAssociatedTaxon(Taxon associatedTaxon, List<OrderHint> orderHints, List<String> propertyPaths);
 321
 322     /**
 323      * See {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)}
 324      */
 325     public Pager<SpecimenOrObservationBase> pageFieldUnitsByAssociatedTaxon(Set<TaxonRelationshipEdge> includeRelationships,
 326             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 327
 328     /**
 329      * See {@link #listByAssociatedTaxon(Class, Set, Taxon, Integer, Integer, Integer, List, List)}
 330      *
 331      * @param type
 332      * @param includeRelationships
 333      * @param associatedTaxon
 334      * @param maxDepth
 335      * @param pageSize
 336      * @param pageNumber
 337      * @param orderHints
 338      * @param propertyPaths
 339      * @return a Pager
 340      */
 341     public <T extends SpecimenOrObservationBase> Pager<T> pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 342             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 343
 344     /**
 345      * Retrieves all {@link FieldUnit}s for the {@link SpecimenOrObservationBase} with the given {@link UUID}.<br>
 346      * @param specimenUuid the UUID of the specimen
 347      * @param propertyPaths the property path
 348      * @return either a collection of FieldUnits this specimen was derived from, the FieldUnit itself
 349      * if this was a FieldUnit or an empty collection if no FieldUnits were found
 350      */
 351     public Collection<FieldUnit> findFieldUnits(UUID specimenUuid, List<String> propertyPaths);
 352
 353     /**
 354      * @param clazz
 355      * @param queryString
 356      * @param languages
 357      * @param highlightFragments
 358      * @param pageSize
 359      * @param pageNumber
 360      * @param orderHints
 361      * @param propertyPaths
 362      * @return
 363      * @throws CorruptIndexException
 364      * @throws IOException
 365      * @throws ParseException
 366      */
 367     Pager<SearchResult<SpecimenOrObservationBase>> findByFullText(Class<? extends SpecimenOrObservationBase> clazz,
 368             String queryString, Rectangle boundingBox, List<Language> languages, boolean highlightFragments,
 369             Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths)
 370             throws IOException, LuceneParseException;
 371     /**
 372      * See {@link #listByAssociatedTaxon(Class, Set, String, Integer, Integer, Integer, List, List)}
 373      *
 374      * @param type
 375      * @param includeRelationships
 376      * @param associatedTaxon
 377      * @param maxDepth
 378      * @param pageSize
 379      * @param pageNumber
 380      * @param orderHints
 381      * @param propertyPaths
 382      * @return a Pager
 383      */
 384     public <T extends SpecimenOrObservationBase> Pager<T>  pageByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,
 385             String taxonUUID, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 386
 387     /**
 388      * Moves the given {@link Sequence} from one {@link DnaSample} to another
 389      * @param from the DnaSample from which the sequence will be removed
 390      * @param to the DnaSample which to which the sequence will be added
 391      * @param sequence the Sequence to move
 392      * @return <code>true</code> if successfully moved, <code>false</code> otherwise
 393      */
 394     public UpdateResult moveSequence(DnaSample from, DnaSample to, Sequence sequence);
 395
 396
 397     /**
 398      * @param fromUuid
 399      * @param toUuid
 400      * @param sequenceUuid
 401      * @return
 402      */
 403     public UpdateResult moveSequence(UUID fromUuid, UUID toUuid, UUID sequenceUuid);
 404
 405     /**
 406      * Moves the given {@link DerivedUnit} from one {@link SpecimenOrObservationBase} to another.
 407      * @param from the SpecimenOrObservationBase from which the DerivedUnit will be removed
 408      * @param to the SpecimenOrObservationBase to which the DerivedUnit will be added
 409      * @param derivate the DerivedUnit to move
 410      * @return <code>true</code> if successfully moved, <code>false</code> otherwise
 411      */
 412     public UpdateResult moveDerivate(UUID specimenFromUuid, UUID specimenToUuid, UUID derivateUuid);
 413
 414     /**
 415      * @param from
 416      * @param to
 417      * @param derivate
 418      * @return
 419      */
 420     public boolean moveDerivate(SpecimenOrObservationBase<?> from, SpecimenOrObservationBase<?> to, DerivedUnit derivate);
 421
 422     /**
 423      * Assembles a {@link FieldUnitDTO} for the given field unit.<br>
 424      *
 425      * @param fieldUnit
 426      * @return a DTO with all the assembled information
 427      */
 428     public FieldUnitDTO assembleFieldUnitDTO(FieldUnit fieldUnit);
 429
 430     /**
 431      * Assembles a {@link DerivedUnitDTO} for the given derived unit.
 432      * @param derivedUnit
 433      * @return a DTO with all the assembled information
 434      */
 435     public DerivedUnitDTO assembleDerivedUnitDTO(DerivedUnit derivedUnit);
 436
 437     /**
 438      * Deletes the specified specimen according to the setting in the {@link SpecimenDeleteConfigurator}.<br>
 439      * @param specimen the specimen which shoul be deleted
 440      * @param config specifies options if and how the specimen should be deleted like e.g. including all
 441      * of its children
 442      * @return the {@link DeleteResult} which holds information about the outcome of this operation
 443      */
 444     public DeleteResult delete(SpecimenOrObservationBase<?> specimen, SpecimenDeleteConfigurator config);
 445
 446     /**
 447      * Deletes the specified specimen belonging to the given {@link UUID}
 448      * according to the setting in the {@link SpecimenDeleteConfigurator}.
 449      *
 450      * @param specimen
 451      *            the specimen which shoul be deleted
 452      * @param config
 453      *            specifies options if and how the specimen should be deleted
 454      *            like e.g. including all of its children
 455      * @return the {@link DeleteResult} which holds information about the
 456      *         outcome of this operation
 457      */
 458     public DeleteResult delete(UUID specimenUuid, SpecimenDeleteConfigurator config);
 459
 460     /**
 461      * Retrieves all {@link IndividualsAssociation} with the given specimen.<br>
 462      * @param specimen the specimen for which the associations are retrieved
 463      * @param limit
 464      * @param start
 465      * @param orderHints
 466      * @param propertyPaths
 467      * @return collection of all associations
 468      */
 469     public Collection<IndividualsAssociation> listIndividualsAssociations(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 470
 471
 472     /**
 473      * Retrieves all taxa linked via {@link IndividualsAssociation} with the given specimen.<br>
 474      * @param specimen the specimen which is linked to the taxa
 475      * @param limit
 476      * @param start
 477      * @param orderHints
 478      * @param propertyPaths
 479      * @return a collection of associated taxa
 480      */
 481     public Collection<TaxonBase<?>> listIndividualsAssociationTaxa(SpecimenOrObservationBase<?> specimen,
 482             Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 483     /**
 484       * @see #listIndividualsAssociationTaxa(SpecimenOrObservationBase, Integer, Integer, List, List)
 485       */
 486     public Collection<TaxonBase<?>> listIndividualsAssociationTaxa(SpecimenOrObservationBase<?> specimen, boolean includeUnpublished,
 487             Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 488
 489     /**
 490      * Retrieves all associated taxa for the given specimen (via type designations, determination, individuals associations)
 491      * @param specimen
 492      * @param limit
 493      * @param start
 494      * @param orderHints
 495      * @param propertyPaths
 496      * @return
 497      */
 498     public Collection<TaxonBase<?>> listAssociatedTaxa(SpecimenOrObservationBase<?> specimen, boolean includeUnpublished,
 499             Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 500     /**
 501      * @see #listAssociatedTaxa(SpecimenOrObservationBase, Integer, Integer, List, List)axa
 502      */
 503     public Collection<TaxonBase<?>> listAssociatedTaxa(SpecimenOrObservationBase<?> specimen,
 504             Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 505
 506     /**
 507      * Retrieves all taxa that the given specimen is determined as
 508      * @param specimen
 509      * @param limit
 510      * @param start
 511      * @param orderHints
 512      * @param propertyPaths
 513      * @return collection of all taxa the given specimen is determined as
 514      */
 515     public Collection<TaxonBase<?>> listDeterminedTaxa(SpecimenOrObservationBase<?> specimen, boolean includeUnpublished,
 516             Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 517     /**
 518      * @see #listDeterminedTaxa(SpecimenOrObservationBase, Integer, Integer, List, List)
 519      */
 520     public Collection<TaxonBase<?>> listDeterminedTaxa(SpecimenOrObservationBase<?> specimen,
 521             Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 522
 523     /**
 524      * Retrieves all {@link DeterminationEvent}s which have the given specimen set as identified unit.
 525      * @param specimen
 526      * @param limit
 527      * @param start
 528      * @param orderHints
 529      * @param propertyPaths
 530      * @return collection of all determination events with the given specimen
 531      */
 532     public Collection<DeterminationEvent> listDeterminationEvents(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 533
 534     /**
 535      * Retrieves all taxa with a {@link SpecimenTypeDesignation} with the given specimen as a type specimen.
 536      * @param specimen the type specimen
 537      * @param specimen
 538      * @param limit
 539      * @param start
 540      * @param orderHints
 541      * @param propertyPaths
 542      * @return a collection of all taxa where the given specimen is the type specimen
 543      */
 544     public Collection<TaxonBase<?>> listTypeDesignationTaxa(DerivedUnit specimen,
 545             Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 546     /**
 547      * @see #listTypeDesignationTaxa(DerivedUnit, Integer, Integer, List, List)a
 548      */
 549     public Collection<TaxonBase<?>> listTypeDesignationTaxa(DerivedUnit specimen, boolean includeUnpublished,
 550             Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 551
 552     /**
 553      * Retrieves all {@link SpecimenTypeDesignation}s which have the given specimens as a type specimen.
 554      * @param specimens the type specimens
 555      * @param limit
 556      * @param start
 557      * @param orderHints
 558      * @param propertyPaths
 559      * @return map of all designations with the given type specimens
 560      */
 561     public Map<DerivedUnit, Collection<SpecimenTypeDesignation>> listTypeDesignations(Collection<DerivedUnit> specimens, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 562
 563     /**
 564      * Retrieves all {@link SpecimenTypeDesignation}s which have the given specimen as a type specimen.
 565      * @param specimen the type specimen
 566      * @param limit
 567      * @param start
 568      * @param orderHints
 569      * @param propertyPaths
 570      * @return collection of all designations with the given type specimen
 571      */
 572     public Collection<SpecimenTypeDesignation> listTypeDesignations(DerivedUnit specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 573
 574     /**
 575      * Retrieves all {@link DescriptionBase}s that have the given specimen set as described specimen.
 576      * @param specimen the described specimen
 577      * @param limit
 578      * @param start
 579      * @param orderHints
 580      * @param propertyPaths
 581      * @return collection of all descriptions with the given described specimen
 582      */
 583     public Collection<DescriptionBase<?>> listDescriptionsWithDescriptionSpecimen(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 584
 585     /**
 586      * Gets all description elements that are used for describing the character
 587      * states of the given specimen
 588      *
 589      * @param specimenUuid
 590      *            the specimen {@link UUID} for which the character state description
 591      *            elements should be retrieved
 592      * @return a collection of all character state description elements for this
 593      *         specimen
 594      */
 595     public Collection<DescriptionElementBase> getCharacterDataForSpecimen(UUID specimenUuid);
 596
 597     /**
 598      * Returns the most significant identifier for the given {@link DerivedUnit}.
 599      * @param derivedUnit the derived unit to check
 600      * @return the identifier string
 601      * @deprecated use {@link DerivedUnit#getMostSignificantIdentifier()} instead
 602      */
 603     @Deprecated
 604     public String getMostSignificantIdentifier(DerivedUnit derivedUnit);
 605
 606     /**
 607      * Returns the number of specimens that match the given parameters
 608      * <br>
 609      * <b>NOTE - issue #6484:</b> the parameters {@link FindOccurrencesConfigurator#getAssignmentStatus()}
 610      * and {@link FindOccurrencesConfigurator#isRetrieveIndirectlyAssociatedSpecimens()} are not evaluated
 611      * in the count method
 612      * @param clazz the class to match
 613      * @param queryString the queryString to match
 614      * @param type the {@link SpecimenOrObservationType} to match
 615      * @param associatedTaxon the taxon these specimens are in any way associated to via
 616      * determination, type designations, individuals associations, etc.
 617      * @param matchmode determines how the query string should be matched
 618      * @param limit
 619      *            the maximum number of entities returned (can be null to return
 620      *            all entities)
 621      * @param start
 622      * @param orderHints
 623      *            Supports path like <code>orderHints.propertyNames</code> which
 624      *            include *-to-one properties like createdBy.username or
 625      *            authorTeam.persistentTitleCache
 626      * @return the number of found specimens
 627      */
 628     public long countOccurrences(IIdentifiableEntityServiceConfigurator<SpecimenOrObservationBase> config);
 629
 630     /**
 631      * Return the all {@link SpecimenOrObservationBase}s of the complete
 632      * derivative hierarchy i.e. all parent and child derivatives and the given
 633      * specimen itself.
 634      *
 635      * @param specimen
 636      *            a specimen or observation
 637      * @return the derivative hierarchy as an unordered list of all specimens or observation
 638      */
 639     public List<SpecimenOrObservationBase<?>> getAllHierarchyDerivatives(SpecimenOrObservationBase<?> specimen);
 640
 641     /**
 642      * Returns all child derivatives of the given specimen.
 643      * @param specimen a specimen or observation
 644      * @return an unordered list of all child derivatives
 645      */
 646     public List<DerivedUnit> getAllChildDerivatives(SpecimenOrObservationBase<?> specimen);
 647
 648     /**
 649      * Returns all child derivatives of the given specimen.
 650      * @param specimen the UUID of a specimen or observation
 651      * @return an unordered list of all child derivatives
 652      */
 653     public List<DerivedUnit> getAllChildDerivatives(UUID specimenUuid);
 654
 655     /**
 656      * Returns all {@link FieldUnit}s that are referencing this {@link GatheringEvent}
 657      * @param gatheringEventUuid the {@link UUID} of the gathering event
 658      * @return a list of field units referencing the gathering event
 659      */
 660     public List<FieldUnit> findFieldUnitsForGatheringEvent(UUID gatheringEventUuid);
 661
 662
 663     /**
 664      * Returns a list of {@link UuidAndTitleCache} for the specimens found with the
 665      * given configurator
 666      * @param config the configurator for the search
 667      * @return a list of UuidAndTitleCache object
 668      */
 669     @Transactional(readOnly = true)
 670     public Pager<UuidAndTitleCache<SpecimenOrObservationBase>> findByTitleUuidAndTitleCache(
 671             FindOccurrencesConfigurator config);
 672
 673     /**
 674      * Returns a list of {@link DerivedUnitDTO} for the specimens found with the
 675      * given configurator
 676      * @param config the configurator for the search
 677      * @return a list of {@link DerivedUnitDTO} object
 678      */
 679     @Transactional(readOnly = true)
 680     public List<DerivedUnitDTO> findByTitleDerivedUnitDTO(
 681             FindOccurrencesConfigurator config);
 682
 683
 684     FieldUnitDTO findByAccessionNumber(
 685              String accessionNumberString, List<OrderHint> orderHints,
 686             List<String> propertyPaths);
 687
 688
 689     List<FieldUnitDTO> findFieldUnitDTOByAssociatedTaxon(Set<TaxonRelationshipEdge> includedRelationships,
 690             UUID associatedTaxonUuid, List<String> propertyPaths);
 691
 692     FieldUnitDTO findFieldUnitDTO(DerivedUnitDTO derivedUnitDTO, Collection<FieldUnitDTO> fieldUnits,
 693             HashMap<UUID, SpecimenOrObservationBaseDTO> alreadyCollectedSpecimen);
 694
 695
 696     public List<Point> findPointsForFieldUnitList(List<UUID> fieldUnitUuids);
 697
 698     /**
 699      * Load the FieldUnitDTO for the given <code>derivedUnitUuid</code> with all intermediate derivatives and {@link eu.etaxonomy.cdm.api.service.dto.GatheringEventDTO}
 700
 701      * @param derivedUnitUuid
 702      * @return
 703      */
 704     FieldUnitDTO loadFieldUnitDTO(UUID derivedUnitUuid);
 705
 706 }