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

   1 package eu.etaxonomy.cdm.api.service;
   2
   3 import java.util.ArrayList;
   4 import java.util.Collection;
   5 import java.util.List;
   6 import java.util.Map;
   7 import java.util.Set;
   8 import java.util.UUID;
   9
  10 import eu.etaxonomy.cdm.api.service.config.DescriptionAggregationConfiguration;
  11 import eu.etaxonomy.cdm.api.service.dto.RowWrapperDTO;
  12 import eu.etaxonomy.cdm.api.service.dto.SpecimenRowWrapperDTO;
  13 import eu.etaxonomy.cdm.api.service.dto.TaxonRowWrapperDTO;
  14 import eu.etaxonomy.cdm.common.monitor.IProgressMonitor;
  15 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  16 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  17 import eu.etaxonomy.cdm.model.description.DescriptionType;
  18 import eu.etaxonomy.cdm.model.description.DescriptiveDataSet;
  19 import eu.etaxonomy.cdm.model.description.DescriptiveSystemRole;
  20 import eu.etaxonomy.cdm.model.description.Feature;
  21 import eu.etaxonomy.cdm.model.description.SpecimenDescription;
  22 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  23 import eu.etaxonomy.cdm.model.taxon.TaxonNode;
  24 import eu.etaxonomy.cdm.persistence.dto.SpecimenNodeWrapper;
  25 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
  26
  27
  28 public interface IDescriptiveDataSetService extends IIdentifiableEntityService<DescriptiveDataSet> {
  29         /**
  30          * Returns a Map of descriptions each with the description elements that match
  31          * the supplied features (or all description elements if no features are supplied)
  32          *
  33          * @param descriptiveDataSet the data set which the descriptions belong to
  34          * @param features restrict the returned description elements to those which have features in this set
  35          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions that belong to the data set)
  36          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based,
  37          *                   can be null, equivalent of starting at the beginning of the recordset). Descriptions are sorted by titleCache
  38          * @param propertyPaths properties to be initialized (applied to the descriptionElements)
  39          * @return
  40          */
  41         public Map<DescriptionBase, Set<DescriptionElementBase>> getDescriptionElements(DescriptiveDataSet descriptiveDataSet, Set<Feature> features, Integer pageSize, Integer pageNumber,     List<String> propertyPaths);
  42
  43         public <T extends DescriptionElementBase> Map<UuidAndTitleCache, Map<UUID, Set<T>>> getTaxonFeatureDescriptionElementMap(Class<T> clazz, UUID descriptiveDataSetUuid, DescriptiveSystemRole role);
  44
  45     /**
  46      * Returns a list of {@link UuidAndTitleCache} elements for all {@link DescriptiveDataSet}s in the data base
  47      * @param limitOfInitialElements
  48      * @param pattern
  49      * @return a list of UuidAndTitleCache element
  50      */
  51     public List<UuidAndTitleCache<DescriptiveDataSet>> getDescriptiveDataSetUuidAndTitleCache(Integer limitOfInitialElements, String pattern);
  52
  53     /**
  54      * Returns a collection of {@link RowWrapperDTO} objects for the given {@link DescriptiveDataSet}.<br>
  55      * A RowWrapper represents on row in the character matrix.
  56      * @param descriptiveDataSetUuid the working set for which the row wrapper objects should be fetched
  57      * @param the progress monitor
  58      * @return a list of row wrapper objects
  59      */
  60     public ArrayList<RowWrapperDTO> getRowWrapper(UUID descriptiveDataSetUuid, IProgressMonitor monitor);
  61
  62     /**
  63      * Loads all available specimens wrapped in a {@link SpecimenNodeWrapper} object for
  64      * a given {@link DescriptiveDataSet} according to the filters set in the working set
  65      * @param descriptiveDataSet the data set for which the specimens should be fetched
  66      * @return a collection of wrapper objects
  67      */
  68     public Collection<SpecimenNodeWrapper> loadSpecimens(DescriptiveDataSet descriptiveDataSet);
  69
  70     /**
  71      * Lists all taxon nodes that match the filter set defined in the
  72      * {@link DescriptiveDataSet} given.
  73      * @param the data set which defined the taxon node filter
  74      * @return a list of {@link UUID}s from the filtered nodes
  75      *
  76      */
  77     public List<UUID> findFilteredTaxonNodes(DescriptiveDataSet descriptiveDataSet);
  78
  79     /**
  80      * Creates a specimen row wrapper object for the given description
  81      * @param description the specimen description for which the wrapper should be created
  82      * @param descriptiveDataSet the data set it should be used in
  83      * @return the created row wrapper
  84      */
  85     public SpecimenRowWrapperDTO createSpecimenRowWrapper(SpecimenDescription description, DescriptiveDataSet descriptiveDataSet);
  86
  87     /**
  88      * Returns a {@link TaxonDescription} for a given taxon node with corresponding
  89      * features according to the {@link DescriptiveDataSet} and the having the given {@link DescriptionType}.<br>
  90      * @param descriptiveDataSetUuid the uuid of the dataset defining the features
  91      * @param taxonNodeUuid the uuid of the taxon node that links to the taxon
  92      * @param descriptionType the {@link DescriptionType} that the description should have
  93      * @return the found taxon description or <code>null</code>
  94      */
  95     public TaxonDescription findTaxonDescriptionByDescriptionType(UUID dataSetUuid, UUID taxonNodeUuid, DescriptionType descriptionType);
  96
  97     /**
  98      * Creates a taxon row wrapper object for the given description
  99      * @param taxonDescriptionUuid the taxon description for which the wrapper should be created
 100      * @param descriptiveDataSet the data set it should be used in
 101      * @return the created row wrapper
 102      */
 103     public TaxonRowWrapperDTO createTaxonRowWrapper(UUID taxonDescriptionUuid, UUID descriptiveDataSetUuid);
 104
 105     /**
 106      * Returns a {@link SpecimenDescription} for a given specimen with corresponding
 107      * features according to the {@link DescriptiveDataSet}.<br>
 108      * If a description is found that matches all features of the data set this description
 109      * will be returned. A new one will be created otherwise.
 110      * @param descriptiveDataSetUuid the uuid of the dataset defining the features
 111      * @param specimenUuid the uuid of the specimen
 112      * @param addDatasetSource if <code>true</code> the source(s) of the descriptive dataset
 113      * will be added to the description <b>if</b> a new one is created
 114      * @return either the found specimen description or a newly created one
 115      */
 116     public SpecimenDescription findSpecimenDescription(UUID descriptiveDataSetUuid, UUID specimenUuid, boolean addDatasetSource);
 117
 118     /**
 119      * Creates a new taxon description with the features defined in the dataset for the
 120      * taxon associated with the given taxon node.
 121      * @param descriptiveDataSetUuid the uuid of the dataset defining the features
 122      * @param taxonNodeUuid the uuid of the taxon node that links to the taxon
 123      * @param descriptionType the type of the description
 124      * @return a taxon row wrapper of the description with the features defined in the data set
 125      */
 126     public TaxonRowWrapperDTO createTaxonDescription(UUID dataSetUuid, UUID taxonNodeUuid, DescriptionType descriptionType);
 127
 128     /**
 129      * Removes the description specified by the given {@link UUID} from the given {@link DescriptiveDataSet}.
 130      * @param descriptionUuid the UUID of the description to delete
 131      * @param descriptiveDataSetUuid the UUID of the data set to delete
 132      * @return the result of the operation
 133      */
 134     public DeleteResult removeDescription(UUID descriptionUuid, UUID descriptiveDataSetUuid);
 135
 136     /**
 137      * Loads all taxon nodes that match the filter set defined in the
 138      * {@link DescriptiveDataSet} given.
 139      * @param the data set which defined the taxon node filter
 140      * @return a list of {@link TaxonNode}s from the filtered nodes
 141      *
 142      */
 143     public List<TaxonNode> loadFilteredTaxonNodes(DescriptiveDataSet descriptiveDataSet, List<String> propertyPaths);
 144
 145     /**
 146      * Aggregates the character data of the given {@link DescriptiveDataSet}.<br>
 147      * <br>
 148      * For all {@link SpecimenDescription}s belonging to this data set new,
 149      * aggregated {@link TaxonDescription}s are created for every taxon the specimens are
 150      * directly associated with.
 151      * @param descriptiveDataSetUuid the uuid of the descriptive data set to which the
 152      * aggregated descriptions will be added to
 153      * @param config the aggregation configuration
 154      * @param monitor the progress monitor
 155      * @return the result of the operation
 156      */
 157     public UpdateResult aggregate(UUID descriptiveDataSetUuid,  DescriptionAggregationConfiguration config, IProgressMonitor monitor);
 158
 159 }