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