ref #9389 ref #9415 improving information assembly in derivation bouquet by recursion...
[cdmlib.git] / cdmlib-services / src / main / java / eu / etaxonomy / cdm / api / service / IOccurrenceService.java
index d6392dc0b949e3838f3268191649d02295dab815..7723fd0272eb30d8b8c3c50cd97d366de591af90 100644 (file)
@@ -11,7 +11,6 @@ package eu.etaxonomy.cdm.api.service;
 \r
 import java.io.IOException;\r
 import java.util.Collection;\r
-import java.util.HashMap;\r
 import java.util.List;\r
 import java.util.Map;\r
 import java.util.Set;\r
@@ -26,9 +25,9 @@ import eu.etaxonomy.cdm.api.facade.DerivedUnitFacadeNotSupportedException;
 import eu.etaxonomy.cdm.api.service.config.FindOccurrencesConfigurator;\r
 import eu.etaxonomy.cdm.api.service.config.IIdentifiableEntityServiceConfigurator;\r
 import eu.etaxonomy.cdm.api.service.config.SpecimenDeleteConfigurator;\r
-import eu.etaxonomy.cdm.api.service.dto.SpecimenOrObservationBaseDTO;\r
-import eu.etaxonomy.cdm.api.service.dto.FieldUnitDTO;\r
 import eu.etaxonomy.cdm.api.service.dto.DerivedUnitDTO;\r
+import eu.etaxonomy.cdm.api.service.dto.FieldUnitDTO;\r
+import eu.etaxonomy.cdm.api.service.dto.SpecimenOrObservationBaseDTO;\r
 import eu.etaxonomy.cdm.api.service.pager.Pager;\r
 import eu.etaxonomy.cdm.api.service.search.LuceneParseException;\r
 import eu.etaxonomy.cdm.api.service.search.SearchResult;\r
@@ -38,7 +37,6 @@ import eu.etaxonomy.cdm.model.description.DescriptionBase;
 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;\r
 import eu.etaxonomy.cdm.model.description.IndividualsAssociation;\r
 import eu.etaxonomy.cdm.model.description.TaxonDescription;\r
-import eu.etaxonomy.cdm.model.location.Country;\r
 import eu.etaxonomy.cdm.model.location.Point;\r
 import eu.etaxonomy.cdm.model.media.Media;\r
 import eu.etaxonomy.cdm.model.molecular.DnaSample;\r
@@ -67,11 +65,8 @@ import eu.etaxonomy.cdm.persistence.query.OrderHint;
  * @author a.babadshanjan\r
  * @since 01.09.2008\r
  */\r
-public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenOrObservationBase> {\r
-\r
-    public Country getCountryByIso(String iso639);\r
-\r
-    public List<Country> getCountryByName(String name);\r
+public interface IOccurrenceService\r
+        extends IIdentifiableEntityService<SpecimenOrObservationBase> {\r
 \r
     /**\r
      * Returns a paged list of occurrences that have been determined to belong\r
@@ -285,7 +280,7 @@ public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenO
 \r
 \r
     /**\r
-     * Lists all instances of {@link FieldUnit} which are\r
+     * Lists all root units which are\r
      * associated <b>directly or indirectly</b>with the <code>taxon</code> specified\r
      * as parameter. "Indirectly" means that a sub derivate of the FieldUnit is\r
      * directly associated with the given taxon.\r
@@ -308,6 +303,7 @@ public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenO
      *\r
      * @param <T>\r
      * @param type\r
+     *  Restriction to a specific subtype, may be null.\r
      * @param associatedTaxon\r
      * @param Set<TaxonRelationshipVector> includeRelationships. TaxonRelationships will not be taken into account if this is <code>NULL</code>.\r
      * @param maxDepth TODO\r
@@ -317,18 +313,26 @@ public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenO
      * @param propertyPaths\r
      * @return\r
      */\r
-    public Collection<SpecimenOrObservationBase> listFieldUnitsByAssociatedTaxon(Taxon associatedTaxon, List<OrderHint> orderHints, List<String> propertyPaths);\r
+    public <T extends SpecimenOrObservationBase> Collection<T> listRootUnitsByAssociatedTaxon(Class<T> type, Taxon associatedTaxon, List<OrderHint> orderHints, List<String> propertyPaths);\r
+\r
+\r
+    /**\r
+     * @deprecated replace by {@link #listRootUnitsByAssociatedTaxon(Class, Taxon, List, List)}\r
+     */\r
+    @Deprecated\r
+    public Collection<FieldUnit> listFieldUnitsByAssociatedTaxon(Taxon associatedTaxon, List<OrderHint> orderHints, List<String> propertyPaths);\r
 \r
     /**\r
      * See {@link #listFieldUnitsByAssociatedTaxon(Set, Taxon, Integer, Integer, Integer, List, List)}\r
      */\r
-    public Pager<SpecimenOrObservationBase> pageFieldUnitsByAssociatedTaxon(Set<TaxonRelationshipEdge> includeRelationships,\r
+    public <T extends SpecimenOrObservationBase> Pager<T> pageRootUnitsByAssociatedTaxon(Class<T> type, Set<TaxonRelationshipEdge> includeRelationships,\r
             Taxon associatedTaxon, Integer maxDepth, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
 \r
     /**\r
      * See {@link #listByAssociatedTaxon(Class, Set, Taxon, Integer, Integer, Integer, List, List)}\r
      *\r
      * @param type\r
+     *  Restriction to subtype of <code>SpecimenOrObservationBase</code>, can be NULL.\r
      * @param includeRelationships\r
      * @param associatedTaxon\r
      * @param maxDepth\r
@@ -350,6 +354,18 @@ public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenO
      */\r
     public Collection<FieldUnit> findFieldUnits(UUID specimenUuid, List<String> propertyPaths);\r
 \r
+    /**\r
+     * Retrieves top most originals for a {@link SpecimenOrObservationBase} in the derivation graph by recursively\r
+     * walking all {@link DerivationEvent}s.\r
+     * In most cases item in the returned collection will be {@link FieldUnit FieldUnits} but also DerivedUnits are possible, in\r
+     * cases where no FieledUnit exists.\r
+     *\r
+     * @param specimenUuid the UUID of the specimen\r
+     * @param propertyPaths the property path\r
+     * @return either a collection of root units\r
+     */\r
+    public Collection<SpecimenOrObservationBase> findRootUnits(UUID specimenUuid, List<String> propertyPaths);\r
+\r
     /**\r
      * @param clazz\r
      * @param queryString\r
@@ -432,7 +448,7 @@ public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenO
      * @param derivedUnit\r
      * @return a DTO with all the assembled information\r
      */\r
-    public DerivedUnitDTO assemblePreservedSpecimenDTO(DerivedUnit derivedUnit);\r
+    public DerivedUnitDTO assembleDerivedUnitDTO(DerivedUnit derivedUnit);\r
 \r
     /**\r
      * Deletes the specified specimen according to the setting in the {@link SpecimenDeleteConfigurator}.<br>\r
@@ -582,18 +598,6 @@ public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenO
      */\r
     public Collection<DescriptionBase<?>> listDescriptionsWithDescriptionSpecimen(SpecimenOrObservationBase<?> specimen, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);\r
 \r
-    /**\r
-     * Gets all description elements that are used for describing the character\r
-     * states of the given specimen\r
-     *\r
-     * @param specimen\r
-     *            the specimen for which the character state description\r
-     *            elements should be retrieved\r
-     * @return a collection of all character state description elements for this\r
-     *         specimen\r
-     */\r
-    public Collection<DescriptionElementBase> getCharacterDataForSpecimen(SpecimenOrObservationBase<?> specimen);\r
-\r
     /**\r
      * Gets all description elements that are used for describing the character\r
      * states of the given specimen\r
@@ -610,7 +614,9 @@ public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenO
      * Returns the most significant identifier for the given {@link DerivedUnit}.\r
      * @param derivedUnit the derived unit to check\r
      * @return the identifier string\r
+     * @deprecated use {@link DerivedUnit#getMostSignificantIdentifier()} instead\r
      */\r
+    @Deprecated\r
     public String getMostSignificantIdentifier(DerivedUnit derivedUnit);\r
 \r
     /**\r
@@ -687,50 +693,26 @@ public interface IOccurrenceService extends IIdentifiableEntityService<SpecimenO
      * @return a list of {@link DerivedUnitDTO} object\r
      */\r
     @Transactional(readOnly = true)\r
-    public List<DerivedUnitDTO> findByTitlePreservedSpecimenDTO(\r
+    public List<DerivedUnitDTO> findByTitleDerivedUnitDTO(\r
             FindOccurrencesConfigurator config);\r
 \r
-    /**\r
-     * @param queryString\r
-     * @param propertyPaths\r
-     * @return\r
-     * @throws IOException\r
-     */\r
-    FieldUnitDTO findByAccessionNumber(\r
-             String accessionNumberString, List<OrderHint> orderHints,\r
-            List<String> propertyPaths);\r
 \r
     /**\r
-     * @param includedRelationships\r
-     * @param associatedTaxon\r
-     * @param maxDepth\r
-     * @param pageSize\r
-     * @param pageNumber\r
-     * @param orderHints\r
-     * @param propertyPaths\r
-     * @return\r
-     */\r
-    List<FieldUnitDTO> findFieldUnitDTOByAssociatedTaxon(Set<TaxonRelationshipEdge> includedRelationships,\r
-            UUID associatedTaxonUuid, List<String> propertyPaths);\r
-\r
-    /**\r
-     * @param derivedUnitUuid\r
-     * @param propertyPaths\r
-     * @return\r
+     * Collects the <code>FieldUnits</code> which are at the root of the derivation event\r
+     * graph in which the {@link DerivedUnit} with the specified <code>findByAccessionNumber</code>\r
+     * is found.\r
      */\r
+    SpecimenOrObservationBaseDTO findByAccessionNumber(String accessionNumberString, List<OrderHint> orderHints);\r
 \r
-    FieldUnitDTO findFieldUnitDTO(SpecimenOrObservationBaseDTO derivedUnitDTO, Collection<FieldUnitDTO> fieldUnits,\r
-            HashMap<UUID, SpecimenOrObservationBaseDTO> alreadyCollectedSpecimen);\r
 \r
+    List<SpecimenOrObservationBaseDTO> listRootUnitDTOsByAssociatedTaxon(Set<TaxonRelationshipEdge> includedRelationships,\r
+            UUID associatedTaxonUuid, List<String> propertyPaths);\r
 \r
-    /**\r
-     * @param fieldUnitUuids\r
-     * @return\r
-     */\r
     public List<Point> findPointsForFieldUnitList(List<UUID> fieldUnitUuids);\r
 \r
     /**\r
      * Load the FieldUnitDTO for the given <code>derivedUnitUuid</code> with all intermediate derivatives and {@link eu.etaxonomy.cdm.api.service.dto.GatheringEventDTO}\r
+\r
      * @param derivedUnitUuid\r
      * @return\r
      */\r