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

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