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

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 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.util.Collection;
  14 import java.util.List;
  15 import java.util.Map;
  16 import java.util.Set;
  17 import java.util.UUID;
  18
  19 import eu.etaxonomy.cdm.api.service.pager.Pager;
  20 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  21 import eu.etaxonomy.cdm.model.common.VersionableEntity;
  22 import eu.etaxonomy.cdm.model.description.DescriptionBase;
  23 import eu.etaxonomy.cdm.model.description.DescriptionElementBase;
  24 import eu.etaxonomy.cdm.model.description.Feature;
  25 import eu.etaxonomy.cdm.model.description.FeatureNode;
  26 import eu.etaxonomy.cdm.model.description.FeatureTree;
  27 import eu.etaxonomy.cdm.model.description.PresenceAbsenceTermBase;
  28 import eu.etaxonomy.cdm.model.description.Scope;
  29 import eu.etaxonomy.cdm.model.description.TaxonDescription;
  30 import eu.etaxonomy.cdm.model.description.TaxonNameDescription;
  31 import eu.etaxonomy.cdm.model.description.TextData;
  32 import eu.etaxonomy.cdm.model.location.NamedArea;
  33 import eu.etaxonomy.cdm.model.media.Media;
  34 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  35 import eu.etaxonomy.cdm.model.taxon.Taxon;
  36 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  37 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  38
  39 public interface IDescriptionService extends IIdentifiableEntityService<DescriptionBase> {
  40
  41         /**
  42          * @return
  43          */
  44         // FIXME candidate for harmonization? findByUuid
  45         public DescriptionBase getDescriptionBaseByUuid(UUID uuid);
  46
  47         /**
  48          * Persists a <code>Description</code>
  49           * @param description
  50          * @return
  51          */
  52         // FIXME candidate for harmonization? save
  53         public UUID saveDescription(DescriptionBase description);
  54
  55         /**
  56          * Persists a <code>FeatureTree</code>
  57          * @param tree
  58          * @return
  59          */
  60         public UUID saveFeatureTree(FeatureTree tree);
  61         // FIXME could you handle the feature data elements using @Cascade?
  62         public void saveFeatureDataAll(Collection<VersionableEntity> featureData);
  63         public Map<UUID, FeatureTree> saveFeatureTreeAll(Collection<FeatureTree> trees);
  64         public Map<UUID, FeatureNode> saveFeatureNodeAll(Collection<FeatureNode> nodes);
  65
  66         /**
  67          * Gets a FeatureTree instance matching the supplied uuid
  68          *
  69          * @param uuid the uuid of the FeatureTree of interest
  70          * @return a FeatureTree, or null if the FeatureTree does not exist
  71          */
  72         public FeatureTree getFeatureTreeByUuid(UUID uuid);
  73
  74         /**
  75          * Finds the feature tree specified by the <code>uuid</code> parameter and
  76          * recursively initializes all bean properties given in the
  77          * <code>propertyPaths</code> parameter.
  78          * <p>
  79          * For detailed description and examples <b>please refer to:</b>
  80          * {@link BeanInitializer#initialize(Object, List)}
  81          *
  82          * @param uuid
  83          * @param propertyPaths properties to initialize
  84          * @return
  85          */
  86         public FeatureTree loadFeatureTree(UUID uuid, List<String> propertyPaths);
  87
  88         /**
  89          * Finds the feature node specified by the <code>uuid</code> parameter and
  90          * recursively initializes all bean properties given in the
  91          * <code>propertyPaths</code> parameter.
  92          * <p>
  93          * For detailed description and examples <b>please refer to:</b>
  94          * {@link BeanInitializer#initialize(Object, List)}
  95          *
  96          * @param uuid
  97          * @param propertyPaths properties to initialize
  98          * @return
  99          */
 100         public FeatureNode loadFeatureNode(UUID uuid, List<String> propertyPaths);
 101         public List<FeatureNode> getFeatureNodesAll();
 102         public List<Feature> getFeaturesAll();
 103
 104         public List<FeatureTree> getFeatureTreesAll(List<String> propertyPaths);
 105         public List<FeatureNode> getFeatureNodesAll(List<String> propertyPaths);
 106         public List<Feature> getFeaturesAll(List<String> propertyPaths);
 107
 108
 109         public TermVocabulary<Feature> getDefaultFeatureVocabulary();
 110         //public TermVocabulary<Feature> getFeatureVocabulary();
 111         public TermVocabulary<Feature> getFeatureVocabulary(UUID uuid);
 112
 113         /**
 114          * Gets a DescriptionElementBase instance matching the supplied uuid
 115          *
 116          * @param uuid the uuid of the DescriptionElement of interest
 117          * @return a DescriptionElement, or null if the DescriptionElement does not exist
 118          */
 119         public DescriptionElementBase getDescriptionElementByUuid(UUID uuid);
 120
 121         /**
 122          * Loads and existing DescriptionElementBase instance matching the supplied uuid,
 123          * and recursively initializes all bean properties given in the
 124          * <code>propertyPaths</code> parameter.
 125          * <p>
 126          * For detailed description and examples <b>please refer to:</b>
 127          * {@link BeanInitializer#initialize(Object, List)}
 128          *
 129          * @param uuid the uuid of the DescriptionElement of interest
 130          * @return a DescriptionElement, or null if the DescriptionElement does not exist
 131          */
 132         public DescriptionElementBase loadDescriptionElement(UUID uuid,List<String> propertyPaths);
 133
 134         /**
 135          * Persists a <code>DescriptionElementBase</code>
 136          * @param descriptionElement
 137          * @return
 138          */
 139         public UUID saveDescriptionElement(DescriptionElementBase descriptionElement);
 140
 141         /**
 142          * Delete an existing description element
 143          *
 144          * @param descriptionElement the description element to be deleted
 145          * @return the unique identifier of the deleted entity
 146          */
 147         public UUID deleteDescriptionElement(DescriptionElementBase descriptionElement);
 148
 149         /**
 150          * List the descriptions of type <TYPE>, filtered using the following parameters
 151          *
 152          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 153          * @param hasMedia Restrict the description to those that do (true) or don't (false) contain <i>elements</i> that have one or more media (can be null)
 154          * @param hasText Restrict the description to those that do (true) or don't (false) contain TextData <i>elements</i> that have some textual content (can be null)
 155          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 156          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 157          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 158          * @param orderHints may be null
 159          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 160          * @return a Pager containing DescriptionBase instances
 161          */
 162         public <TYPE extends DescriptionBase> Pager<TYPE> listDescriptions(Class<TYPE> type, Boolean hasMedia, Boolean hasText, Set<Feature> feature, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 163
 164         /**
 165          * Count the descriptions of type <TYPE>, filtered using the following parameters
 166          *
 167          * @param type The type of description returned (Taxon, TaxonName, or Specimen)
 168          * @param hasMedia Restrict the description to those that do (true) or don't (false) contain <i>elements</i> that have one or more media (can be null)
 169          * @param hasText Restrict the description to those that do (true) or don't (false) contain TextData <i>elements</i> that have some textual content (can be null)
 170          * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
 171          * @return a count of DescriptionBase instances
 172          */
 173         public <TYPE extends DescriptionBase> int countDescriptions(Class<TYPE> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);
 174
 175         /**
 176          * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
 177          *
 178          * @param description The description which these description elements belong to (can be null to count all description elements)
 179          * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
 180          * @param type The type of description
 181          * @param pageSize The maximum number of description elements returned (can be null for all description elements)
 182          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 183          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 184          * @return a Pager containing DescriptionElementBase instances
 185          */
 186         public <TYPE extends DescriptionElementBase> Pager<TYPE> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<TYPE> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 187
 188         /**
 189          * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
 190          *
 191          * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
 192          * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
 193          * @param geographicalScope Restrict the results to those descriptions which have a geographical scope that overlaps with the NamedArea instances passed (can be null or empty)
 194          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 195          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 196          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 197          * @return a Pager containing TaxonDescription instances
 198          */
 199         public Pager<TaxonDescription> getTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 200
 201         /**
 202          * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
 203          *
 204          * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
 205          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 206          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 207          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 208          * @return a Pager containing TaxonNameBase instances
 209          */
 210         public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 211
 212         /**
 213          * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
 214          * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
 215          *
 216          * @param namedAreas The set of NamedArea instances
 217          * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
 218          * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
 219          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 220          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 221          * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
 222          * @return a Pager containing TaxonDescription instances
 223          */
 224         public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 225
 226         /**
 227          * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 228          *
 229          * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
 230          * @param queryString
 231          * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
 232          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 233          * @param orderHints
 234          *            Supports path like <code>orderHints.propertyNames</code> which
 235          *            include *-to-one properties like createdBy.username or
 236          *            authorTeam.persistentTitleCache
 237          * @param propertyPaths properties to be initialized
 238          * @return a Pager DescriptionElementBase instances
 239          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 240          */
 241         public Pager<DescriptionElementBase> search(Class<? extends DescriptionElementBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 242
 243         /**
 244      * Returns a List of Media that are associated with a given description element
 245      *
 246          * @param descriptionElement the description element associated with these media
 247          * @param pageSize The maximum number of media returned (can be null for all related media)
 248          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 249          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 250      * @return a Pager containing media instances
 251      */
 252     public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 253 }