X-Git-Url: https://dev.e-taxonomy.eu/gitweb/cdmlib.git/blobdiff_plain/7b121d03e41b7fac4c4cf629f422973a3631a6de..f6740b16c884bfa711f29e982cb7d1eac563ea05:/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IOccurrenceService.java diff --git a/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IOccurrenceService.java b/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IOccurrenceService.java index 0013ba550d..7723fd0272 100644 --- a/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IOccurrenceService.java +++ b/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IOccurrenceService.java @@ -1,4 +1,3 @@ -// $Id$ /** * Copyright (C) 2009 EDIT * European Distributed Institute of Taxonomy @@ -13,62 +12,68 @@ package eu.etaxonomy.cdm.api.service; import java.io.IOException; import java.util.Collection; import java.util.List; +import java.util.Map; import java.util.Set; import java.util.UUID; import org.apache.lucene.index.CorruptIndexException; -import org.apache.lucene.queryParser.ParseException; import org.hibernate.search.spatial.impl.Rectangle; +import org.springframework.transaction.annotation.Transactional; import eu.etaxonomy.cdm.api.facade.DerivedUnitFacade; import eu.etaxonomy.cdm.api.facade.DerivedUnitFacadeNotSupportedException; +import eu.etaxonomy.cdm.api.service.config.FindOccurrencesConfigurator; import eu.etaxonomy.cdm.api.service.config.IIdentifiableEntityServiceConfigurator; import eu.etaxonomy.cdm.api.service.config.SpecimenDeleteConfigurator; +import eu.etaxonomy.cdm.api.service.dto.DerivedUnitDTO; import eu.etaxonomy.cdm.api.service.dto.FieldUnitDTO; -import eu.etaxonomy.cdm.api.service.dto.PreservedSpecimenDTO; +import eu.etaxonomy.cdm.api.service.dto.SpecimenOrObservationBaseDTO; import eu.etaxonomy.cdm.api.service.pager.Pager; +import eu.etaxonomy.cdm.api.service.search.LuceneParseException; import eu.etaxonomy.cdm.api.service.search.SearchResult; import eu.etaxonomy.cdm.api.service.util.TaxonRelationshipEdge; -import eu.etaxonomy.cdm.model.common.CdmBase; -import eu.etaxonomy.cdm.model.common.ICdmBase; import eu.etaxonomy.cdm.model.common.Language; import eu.etaxonomy.cdm.model.description.DescriptionBase; import eu.etaxonomy.cdm.model.description.DescriptionElementBase; import eu.etaxonomy.cdm.model.description.IndividualsAssociation; import eu.etaxonomy.cdm.model.description.TaxonDescription; -import eu.etaxonomy.cdm.model.location.Country; +import eu.etaxonomy.cdm.model.location.Point; import eu.etaxonomy.cdm.model.media.Media; import eu.etaxonomy.cdm.model.molecular.DnaSample; import eu.etaxonomy.cdm.model.molecular.Sequence; import eu.etaxonomy.cdm.model.name.HomotypicalGroup; import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignation; +import eu.etaxonomy.cdm.model.name.TaxonName; import eu.etaxonomy.cdm.model.occurrence.DerivationEvent; import eu.etaxonomy.cdm.model.occurrence.DerivedUnit; import eu.etaxonomy.cdm.model.occurrence.DeterminationEvent; import eu.etaxonomy.cdm.model.occurrence.FieldUnit; +import eu.etaxonomy.cdm.model.occurrence.GatheringEvent; +import eu.etaxonomy.cdm.model.occurrence.MediaSpecimen; import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationBase; import eu.etaxonomy.cdm.model.occurrence.SpecimenOrObservationType; import eu.etaxonomy.cdm.model.taxon.Taxon; import eu.etaxonomy.cdm.model.taxon.TaxonBase; +import eu.etaxonomy.cdm.model.taxon.TaxonNode; import eu.etaxonomy.cdm.model.taxon.TaxonRelationship; import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer; +import eu.etaxonomy.cdm.persistence.dto.SpecimenNodeWrapper; import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache; import eu.etaxonomy.cdm.persistence.query.OrderHint; /** * @author a.babadshanjan - * @created 01.09.2008 + * @since 01.09.2008 */ -public interface IOccurrenceService extends IIdentifiableEntityService { - - public Country getCountryByIso(String iso639); - - public List getCountryByName(String name); +public interface IOccurrenceService + extends IIdentifiableEntityService { /** * Returns a paged list of occurrences that have been determined to belong * to the taxon concept determinedAs, optionally restricted to objects - * belonging to a class that that extends SpecimenOrObservationBase. + * belonging to a class that that extends SpecimenOrObservationBase. This + * will also consider specimens that are determined as a taxon concept + * belonging to the synonymy of the given taxon concept. *

* In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this * method only takes SpecimenOrObservationBase instances into account which @@ -98,6 +103,39 @@ public interface IOccurrenceService extends IIdentifiableEntityService list(Class type, TaxonBase determinedAs, Integer limit, Integer start, List orderHints, List propertyPaths); + /** + * Returns a paged list of occurrences that have been determined to belong + * to the taxon name determinedAs, optionally restricted to objects + * belonging to a class that that extends SpecimenOrObservationBase. + *

+ * In contrast to {@link #listByAnyAssociation(Class, Taxon, List)} this + * method only takes SpecimenOrObservationBase instances into account which + * are actually determined as the taxon specified by + * determinedAs. + * + * @param type + * The type of entities to return (can be null to count all + * entities of type ) + * @param determinedAs + * the taxon name that the occurrences have been determined to + * belong to + * @param pageSize + * The maximum number of objects returned (can be null for all + * matching objects) + * @param pageNumber + * The offset (in pageSize chunks) from the start of the result + * set (0 - based, can be null, equivalent of starting at the + * beginning of the recordset) + * @param orderHints + * Supports path like orderHints.propertyNames which + * include *-to-one properties like createdBy.username or + * authorTeam.persistentTitleCache + * @param propertyPaths + * properties to be initialized + * @return + */ + public Pager list(Class type, TaxonName determinedAs, Integer limit, Integer start, List orderHints, List propertyPaths); + /** * Returns a List of Media that are associated with a given occurence * @@ -109,6 +147,17 @@ public interface IOccurrenceService extends IIdentifiableEntityService getMedia(SpecimenOrObservationBase occurence, Integer pageSize, Integer pageNumber, List propertyPaths); + /** + * Returns all media attached to this occurence and its children. Also takes + * {@link MediaSpecimen} and molecular images into account. + * + * @param occurence the occurence and its children from which the media to get + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based) + * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)} + * @return a Pager of media instances + */ + public Pager getMediainHierarchy(SpecimenOrObservationBase rootOccurence, Integer pageSize, Integer pageNumber, List propertyPaths); + /** * Returns a count of determinations that have been made for a given occurence and for a given taxon concept * @@ -116,7 +165,7 @@ public interface IOccurrenceService extends IIdentifiableEntityService> getDerivedUnitUuidAndTitleCache(); + public List> getDerivedUnitUuidAndTitleCache(Integer limit, String pattern); public DerivedUnitFacade getDerivedUnitFacade(DerivedUnit derivedUnit, List propertyPaths) throws DerivedUnitFacadeNotSupportedException; @@ -210,7 +259,28 @@ public interface IOccurrenceService extends IIdentifiableEntityService orderHints, List propertyPaths); /** - * Lists all instances of {@link FieldUnit} which are + * The method will search for specimen associated with the taxon nodes.
+ * It will search for 3 possible association types:
+ * - via IndividualAssociations of the taxon
+ * - via TypeDesignations of the taxon name
+ * - via Determinations of the taxon or taxon name
+ *
+ * more are covered in + * {@link IOccurrenceService#findByTitle(IIdentifiableEntityServiceConfigurator)} + * @param taxonNodeUuids + * a list of {@link UUID}s of the taxon nodes + * @param limit + * @param start + * @return a collection of {@link SpecimenNodeWrapper} containing the + * {@link TaxonNode} and the corresponding {@link UuidAndTitleCache} + * object for the specimen found for this taxon node + */ + public Collection listUuidAndTitleCacheByAssociatedTaxon(List taxonNodeUuids, + Integer limit, Integer start); + + + /** + * Lists all root units which are * associated directly or indirectlywith the taxon specified * as parameter. "Indirectly" means that a sub derivate of the FieldUnit is * directly associated with the given taxon. @@ -233,6 +303,7 @@ public interface IOccurrenceService extends IIdentifiableEntityService * @param type + * Restriction to a specific subtype, may be null. * @param associatedTaxon * @param Set includeRelationships. TaxonRelationships will not be taken into account if this is NULL. * @param maxDepth TODO @@ -242,18 +313,26 @@ public interface IOccurrenceService extends IIdentifiableEntityService listFieldUnitsByAssociatedTaxon(Taxon associatedTaxon, List orderHints, List propertyPaths); + public Collection listRootUnitsByAssociatedTaxon(Class type, Taxon associatedTaxon, List orderHints, List propertyPaths); + + + /** + * @deprecated replace by {@link #listRootUnitsByAssociatedTaxon(Class, Taxon, List, List)} + */ + @Deprecated + public Collection listFieldUnitsByAssociatedTaxon(Taxon associatedTaxon, List orderHints, List propertyPaths); /** * See {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)} */ - public Pager pageFieldUnitsByAssociatedTaxon(Set includeRelationships, + public Pager pageRootUnitsByAssociatedTaxon(Class type, Set includeRelationships, Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List orderHints, List propertyPaths); /** * See {@link #listByAssociatedTaxon(Class, Set, Taxon, Integer, Integer, Integer, List, List)} * * @param type + * Restriction to subtype of SpecimenOrObservationBase, can be NULL. * @param includeRelationships * @param associatedTaxon * @param maxDepth @@ -269,10 +348,23 @@ public interface IOccurrenceService extends IIdentifiableEntityService * @param specimenUuid the UUID of the specimen + * @param propertyPaths the property path * @return either a collection of FieldUnits this specimen was derived from, the FieldUnit itself * if this was a FieldUnit or an empty collection if no FieldUnits were found */ - public Collection getFieldUnits(UUID specimenUuid); + public Collection findFieldUnits(UUID specimenUuid, List propertyPaths); + + /** + * Retrieves top most originals for a {@link SpecimenOrObservationBase} in the derivation graph by recursively + * walking all {@link DerivationEvent}s. + * In most cases item in the returned collection will be {@link FieldUnit FieldUnits} but also DerivedUnits are possible, in + * cases where no FieledUnit exists. + * + * @param specimenUuid the UUID of the specimen + * @param propertyPaths the property path + * @return either a collection of root units + */ + public Collection findRootUnits(UUID specimenUuid, List propertyPaths); /** * @param clazz @@ -289,9 +381,9 @@ public interface IOccurrenceService extends IIdentifiableEntityService> findByFullText(Class clazz, - String queryString, Rectangle boundingBox, List languages, boolean highlightFragments, Integer pageSize, - Integer pageNumber, List orderHints, List propertyPaths) throws CorruptIndexException, - IOException, ParseException; + String queryString, Rectangle boundingBox, List languages, boolean highlightFragments, + Integer pageSize, Integer pageNumber, List orderHints, List propertyPaths) + throws IOException, LuceneParseException; /** * See {@link #listByAssociatedTaxon(Class, Set, String, Integer, Integer, Integer, List, List)} * @@ -315,7 +407,16 @@ public interface IOccurrenceService extends IIdentifiableEntityServicetrue if successfully moved, false otherwise */ - public boolean moveSequence(DnaSample from, DnaSample to, Sequence sequence); + public UpdateResult moveSequence(DnaSample from, DnaSample to, Sequence sequence); + + + /** + * @param fromUuid + * @param toUuid + * @param sequenceUuid + * @return + */ + public UpdateResult moveSequence(UUID fromUuid, UUID toUuid, UUID sequenceUuid); /** * Moves the given {@link DerivedUnit} from one {@link SpecimenOrObservationBase} to another. @@ -324,31 +425,30 @@ public interface IOccurrenceService extends IIdentifiableEntityServicetrue if successfully moved, false otherwise */ + public UpdateResult moveDerivate(UUID specimenFromUuid, UUID specimenToUuid, UUID derivateUuid); + + /** + * @param from + * @param to + * @param derivate + * @return + */ public boolean moveDerivate(SpecimenOrObservationBase from, SpecimenOrObservationBase to, DerivedUnit derivate); /** - * Assembles a {@link FieldUnitDTO} for the given field unit uuid which is associated to the {@link Taxon}.
- *
- * For the meaning of "associated" see also {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)} + * Assembles a {@link FieldUnitDTO} for the given field unit.
+ * * @param fieldUnit - * @param associatedTaxonUuid * @return a DTO with all the assembled information */ - public FieldUnitDTO assembleFieldUnitDTO(FieldUnit fieldUnit, UUID associatedTaxonUuid); + public FieldUnitDTO assembleFieldUnitDTO(FieldUnit fieldUnit); /** - * Assembles a {@link PreservedSpecimenDTO} for the given derived unit. + * Assembles a {@link DerivedUnitDTO} for the given derived unit. * @param derivedUnit * @return a DTO with all the assembled information */ - public PreservedSpecimenDTO assemblePreservedSpecimenDTO(DerivedUnit derivedUnit); - - /** - * Returns a collection of {@link ICdmBase}s that are not persisted via cascading when saving the given specimen (mostly DefinedTerms). - * @param specimen the specimen that is checked for non-cascaded elements. - * @return collection of non-cascaded element associated with the specimen - */ - public Collection getNonCascadedAssociatedElements(SpecimenOrObservationBase specimen); + public DerivedUnitDTO assembleDerivedUnitDTO(DerivedUnit derivedUnit); /** * Deletes the specified specimen according to the setting in the {@link SpecimenDeleteConfigurator}.
@@ -360,13 +460,18 @@ public interface IOccurrenceService extends IIdentifiableEntityService specimen, SpecimenDeleteConfigurator config); /** - * Deletes the specified specimen and all sub derivates.
- * Note: Be sure to allow child deletion in the config. - * @param from the specimen which should be deleted with all its sub derivates - * @param config the {@link SpecimenDeleteConfigurator} to specify how the deletion should be handled - * @return the {@link DeleteResult} which holds information about the outcome of this operation + * Deletes the specified specimen belonging to the given {@link UUID} + * according to the setting in the {@link SpecimenDeleteConfigurator}. + * + * @param specimen + * the specimen which shoul be deleted + * @param config + * specifies options if and how the specimen should be deleted + * like e.g. including all of its children + * @return the {@link DeleteResult} which holds information about the + * outcome of this operation */ - public DeleteResult deleteDerivateHierarchy(CdmBase from, SpecimenDeleteConfigurator config); + public DeleteResult delete(UUID specimenUuid, SpecimenDeleteConfigurator config); /** * Retrieves all {@link IndividualsAssociation} with the given specimen.
@@ -379,6 +484,98 @@ public interface IOccurrenceService extends IIdentifiableEntityService listIndividualsAssociations(SpecimenOrObservationBase specimen, Integer limit, Integer start, List orderHints, List propertyPaths); + + /** + * Retrieves all taxa linked via {@link IndividualsAssociation} with the given specimen.
+ * @param specimen the specimen which is linked to the taxa + * @param limit + * @param start + * @param orderHints + * @param propertyPaths + * @return a collection of associated taxa + */ + public Collection> listIndividualsAssociationTaxa(SpecimenOrObservationBase specimen, + Integer limit, Integer start, List orderHints, List propertyPaths); + /** + * @see #listIndividualsAssociationTaxa(SpecimenOrObservationBase, Integer, Integer, List, List) + */ + public Collection> listIndividualsAssociationTaxa(SpecimenOrObservationBase specimen, boolean includeUnpublished, + Integer limit, Integer start, List orderHints, List propertyPaths); + + /** + * Retrieves all associated taxa for the given specimen (via type designations, determination, individuals associations) + * @param specimen + * @param limit + * @param start + * @param orderHints + * @param propertyPaths + * @return + */ + public Collection> listAssociatedTaxa(SpecimenOrObservationBase specimen, boolean includeUnpublished, + Integer limit, Integer start, List orderHints, List propertyPaths); + /** + * @see #listAssociatedTaxa(SpecimenOrObservationBase, Integer, Integer, List, List)axa + */ + public Collection> listAssociatedTaxa(SpecimenOrObservationBase specimen, + Integer limit, Integer start, List orderHints, List propertyPaths); + + /** + * Retrieves all taxa that the given specimen is determined as + * @param specimen + * @param limit + * @param start + * @param orderHints + * @param propertyPaths + * @return collection of all taxa the given specimen is determined as + */ + public Collection> listDeterminedTaxa(SpecimenOrObservationBase specimen, boolean includeUnpublished, + Integer limit, Integer start, List orderHints, List propertyPaths); + /** + * @see #listDeterminedTaxa(SpecimenOrObservationBase, Integer, Integer, List, List) + */ + public Collection> listDeterminedTaxa(SpecimenOrObservationBase specimen, + Integer limit, Integer start, List orderHints, List propertyPaths); + + /** + * Retrieves all {@link DeterminationEvent}s which have the given specimen set as identified unit. + * @param specimen + * @param limit + * @param start + * @param orderHints + * @param propertyPaths + * @return collection of all determination events with the given specimen + */ + public Collection listDeterminationEvents(SpecimenOrObservationBase specimen, Integer limit, Integer start, List orderHints, List propertyPaths); + + /** + * Retrieves all taxa with a {@link SpecimenTypeDesignation} with the given specimen as a type specimen. + * @param specimen the type specimen + * @param specimen + * @param limit + * @param start + * @param orderHints + * @param propertyPaths + * @return a collection of all taxa where the given specimen is the type specimen + */ + public Collection> listTypeDesignationTaxa(DerivedUnit specimen, + Integer limit, Integer start, List orderHints, List propertyPaths); + /** + * @see #listTypeDesignationTaxa(DerivedUnit, Integer, Integer, List, List)a + */ + public Collection> listTypeDesignationTaxa(DerivedUnit specimen, boolean includeUnpublished, + Integer limit, Integer start, List orderHints, List propertyPaths); + + /** + * Retrieves all {@link SpecimenTypeDesignation}s which have the given specimens as a type specimen. + * @param specimens the type specimens + * @param limit + * @param start + * @param orderHints + * @param propertyPaths + * @return map of all designations with the given type specimens + */ + public Map> listTypeDesignations(Collection specimens, Integer limit, Integer start, List orderHints, List propertyPaths); + /** * Retrieves all {@link SpecimenTypeDesignation}s which have the given specimen as a type specimen. * @param specimen the type specimen @@ -388,7 +585,7 @@ public interface IOccurrenceService extends IIdentifiableEntityService listTypeDesignations(SpecimenOrObservationBase specimen, Integer limit, Integer start, List orderHints, List propertyPaths); + public Collection listTypeDesignations(DerivedUnit specimen, Integer limit, Integer start, List orderHints, List propertyPaths); /** * Retrieves all {@link DescriptionBase}s that have the given specimen set as described specimen. @@ -401,18 +598,6 @@ public interface IOccurrenceService extends IIdentifiableEntityService> listDescriptionsWithDescriptionSpecimen(SpecimenOrObservationBase specimen, Integer limit, Integer start, List orderHints, List propertyPaths); - /** - * Gets all description elements that are used for describing the character - * states of the given specimen - * - * @param specimen - * the specimen for which the character state description - * elements should be retrieved - * @return a collection of all character state description elements for this - * specimen - */ - public Collection getCharacterDataForSpecimen(SpecimenOrObservationBase specimen); - /** * Gets all description elements that are used for describing the character * states of the given specimen @@ -429,11 +614,17 @@ public interface IOccurrenceService extends IIdentifiableEntityService + * NOTE - issue #6484: the parameters {@link FindOccurrencesConfigurator#getAssignmentStatus()} + * and {@link FindOccurrencesConfigurator#isRetrieveIndirectlyAssociatedSpecimens()} are not evaluated + * in the count method * @param clazz the class to match * @param queryString the queryString to match * @param type the {@link SpecimenOrObservationType} to match @@ -450,7 +641,7 @@ public interface IOccurrenceService extends IIdentifiableEntityService config); + public long countOccurrences(IIdentifiableEntityServiceConfigurator config); /** * Return the all {@link SpecimenOrObservationBase}s of the complete @@ -470,5 +661,61 @@ public interface IOccurrenceService extends IIdentifiableEntityService getAllChildDerivatives(SpecimenOrObservationBase specimen); + /** + * Returns all child derivatives of the given specimen. + * @param specimen the UUID of a specimen or observation + * @return an unordered list of all child derivatives + */ + public List getAllChildDerivatives(UUID specimenUuid); + + /** + * Returns all {@link FieldUnit}s that are referencing this {@link GatheringEvent} + * @param gatheringEventUuid the {@link UUID} of the gathering event + * @return a list of field units referencing the gathering event + */ + public List findFieldUnitsForGatheringEvent(UUID gatheringEventUuid); + + + /** + * Returns a list of {@link UuidAndTitleCache} for the specimens found with the + * given configurator + * @param config the configurator for the search + * @return a list of UuidAndTitleCache object + */ + @Transactional(readOnly = true) + public Pager> findByTitleUuidAndTitleCache( + FindOccurrencesConfigurator config); + + /** + * Returns a list of {@link DerivedUnitDTO} for the specimens found with the + * given configurator + * @param config the configurator for the search + * @return a list of {@link DerivedUnitDTO} object + */ + @Transactional(readOnly = true) + public List findByTitleDerivedUnitDTO( + FindOccurrencesConfigurator config); + + + /** + * Collects the FieldUnits which are at the root of the derivation event + * graph in which the {@link DerivedUnit} with the specified findByAccessionNumber + * is found. + */ + SpecimenOrObservationBaseDTO findByAccessionNumber(String accessionNumberString, List orderHints); + + + List listRootUnitDTOsByAssociatedTaxon(Set includedRelationships, + UUID associatedTaxonUuid, List propertyPaths); + + public List findPointsForFieldUnitList(List fieldUnitUuids); + + /** + * Load the FieldUnitDTO for the given derivedUnitUuid with all intermediate derivatives and {@link eu.etaxonomy.cdm.api.service.dto.GatheringEventDTO} + + * @param derivedUnitUuid + * @return + */ + FieldUnitDTO loadFieldUnitDTO(UUID derivedUnitUuid); }