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

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