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