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