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