3 * Copyright (C) 2007 EDIT
4 * European Distributed Institute of Taxonomy
5 * http://www.e-taxonomy.eu
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.
11 package eu
.etaxonomy
.cdm
.api
.service
;
13 import java
.util
.Collection
;
14 import java
.util
.List
;
17 import java
.util
.UUID
;
19 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
20 import eu
.etaxonomy
.cdm
.model
.common
.Annotation
;
21 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
22 import eu
.etaxonomy
.cdm
.model
.common
.MarkerType
;
23 import eu
.etaxonomy
.cdm
.model
.common
.TermVocabulary
;
24 import eu
.etaxonomy
.cdm
.model
.common
.VersionableEntity
;
25 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionBase
;
26 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionElementBase
;
27 import eu
.etaxonomy
.cdm
.model
.description
.Distribution
;
28 import eu
.etaxonomy
.cdm
.model
.description
.Feature
;
29 import eu
.etaxonomy
.cdm
.model
.description
.FeatureNode
;
30 import eu
.etaxonomy
.cdm
.model
.description
.FeatureTree
;
31 import eu
.etaxonomy
.cdm
.model
.description
.PresenceAbsenceTermBase
;
32 import eu
.etaxonomy
.cdm
.model
.description
.Scope
;
33 import eu
.etaxonomy
.cdm
.model
.description
.TaxonDescription
;
34 import eu
.etaxonomy
.cdm
.model
.description
.TaxonNameDescription
;
35 import eu
.etaxonomy
.cdm
.model
.location
.NamedArea
;
36 import eu
.etaxonomy
.cdm
.model
.location
.NamedAreaLevel
;
37 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
38 import eu
.etaxonomy
.cdm
.model
.name
.TaxonNameBase
;
39 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
40 import eu
.etaxonomy
.cdm
.persistence
.dao
.BeanInitializer
;
41 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
43 public interface IDescriptionService
extends IIdentifiableEntityService
<DescriptionBase
> {
48 * @deprecated use TermService#getVocabulary(VocabularyType) instead
50 public TermVocabulary
<Feature
> getDefaultFeatureVocabulary();
53 * @deprecated use TermService#getVocabulary(VocabularyType) instead
55 public TermVocabulary
<Feature
> getFeatureVocabulary(UUID uuid
);
58 * Gets a DescriptionElementBase instance matching the supplied uuid
60 * @param uuid the uuid of the DescriptionElement of interest
61 * @return a DescriptionElement, or null if the DescriptionElement does not exist
63 public DescriptionElementBase
getDescriptionElementByUuid(UUID uuid
);
66 * Loads and existing DescriptionElementBase instance matching the supplied uuid,
67 * and recursively initializes all bean properties given in the
68 * <code>propertyPaths</code> parameter.
70 * For detailed description and examples <b>please refer to:</b>
71 * {@link BeanInitializer#initialize(Object, List)}
73 * @param uuid the uuid of the DescriptionElement of interest
74 * @return a DescriptionElement, or null if the DescriptionElement does not exist
76 public DescriptionElementBase
loadDescriptionElement(UUID uuid
,List
<String
> propertyPaths
);
79 * Persists a <code>DescriptionElementBase</code>
80 * @param descriptionElement
83 public UUID
saveDescriptionElement(DescriptionElementBase descriptionElement
);
86 * Persists a collection of <code>DescriptionElementBase</code>
87 * @param descriptionElements
90 public Map
<UUID
, DescriptionElementBase
> saveDescriptionElement(Collection
<DescriptionElementBase
> descriptionElements
);
93 * Delete an existing description element
95 * @param descriptionElement the description element to be deleted
96 * @return the unique identifier of the deleted entity
98 public UUID
deleteDescriptionElement(DescriptionElementBase descriptionElement
);
101 * List the descriptions of type <T>, filtered using the following parameters
103 * @param type The type of description returned (Taxon, TaxonName, or Specimen)
104 * @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)
105 * @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)
106 * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
107 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
108 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
109 * @param orderHints may be null
110 * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
111 * @return a Pager containing DescriptionBase instances
113 public Pager
<DescriptionBase
> page(Class
<?
extends DescriptionBase
> type
, Boolean hasMedia
, Boolean hasText
, Set
<Feature
> feature
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
116 * Count the descriptions of type <TYPE>, filtered using the following parameters
118 * @param type The type of description returned (Taxon, TaxonName, or Specimen)
119 * @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)
120 * @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)
121 * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
122 * @return a count of DescriptionBase instances
124 public int count(Class
<?
extends DescriptionBase
> type
, Boolean hasImages
, Boolean hasText
, Set
<Feature
> feature
);
127 * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
129 * @param description The description which these description elements belong to (can be null to count all description elements)
130 * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
131 * @param type The type of description
133 * @param pageSize The maximum number of description elements returned (can be null for all description elements)
134 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
135 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
136 * @return a Pager containing DescriptionElementBase instances
138 public Pager
<DescriptionElementBase
> getDescriptionElements(DescriptionBase description
,Set
<Feature
> features
, Class
<?
extends DescriptionElementBase
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
141 * Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features
143 * @param description The description which these description elements belong to (can be null to count all description elements)
144 * @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)
145 * @param type The type of description
147 * @param pageSize The maximum number of description elements returned (can be null for all description elements)
148 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
149 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
150 * @return a List containing DescriptionElementBase instances
152 public List
<DescriptionElementBase
> listDescriptionElements(DescriptionBase description
,Set
<Feature
> features
, Class
<?
extends DescriptionElementBase
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
155 * Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType
156 * @param annotatedObj The object that "owns" the annotations returned
157 * @param status Only return annotations which are marked with a Marker of this type (can be null to return all annotations)
158 * @param pageSize The maximum number of terms returned (can be null for all annotations)
159 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
160 * @param orderHints may be null
161 * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
162 * @return a Pager of Annotation entities
164 public Pager
<Annotation
> getDescriptionElementAnnotations(DescriptionElementBase annotatedObj
, MarkerType status
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
168 * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
170 * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
171 * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
172 * @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)
173 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
174 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
175 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
176 * @return a Pager containing TaxonDescription instances
178 public Pager
<TaxonDescription
> getTaxonDescriptions(Taxon taxon
, Set
<Scope
> scopes
, Set
<NamedArea
> geographicalScope
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
181 * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
183 * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
184 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
185 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
186 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
187 * @return a Pager containing TaxonNameBase instances
189 public Pager
<TaxonNameDescription
> getTaxonNameDescriptions(TaxonNameBase name
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
192 * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
193 * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
195 * @param namedAreas The set of NamedArea instances
196 * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
197 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
198 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
199 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
200 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
201 * @return a Pager containing TaxonDescription instances
203 public Pager
<TaxonDescription
> searchDescriptionByDistribution(Set
<NamedArea
> namedAreas
, PresenceAbsenceTermBase presence
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
206 * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
208 * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
210 * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
211 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
213 * Supports path like <code>orderHints.propertyNames</code> which
214 * include *-to-one properties like createdBy.username or
215 * authorTeam.persistentTitleCache
216 * @param propertyPaths properties to be initialized
217 * @return a Pager DescriptionElementBase instances
218 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
220 public Pager
<DescriptionElementBase
> searchElements(Class
<?
extends DescriptionElementBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
223 * Returns a List of Media that are associated with a given description element
225 * @param descriptionElement the description element associated with these media
226 * @param pageSize The maximum number of media returned (can be null for all related media)
227 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
228 * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
229 * @return a Pager containing media instances
231 public Pager
<Media
> getMedia(DescriptionElementBase descriptionElement
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
233 public List
<DescriptionElementBase
> getDescriptionElementsForTaxon(Taxon taxon
, Set
<Feature
> features
, Class
<?
extends DescriptionElementBase
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
235 public DistributionTree
getOrderedDistributions(Set
<TaxonDescription
> taxonDescriptions
, Set
<NamedAreaLevel
> levels
, List
<String
> propertyPaths
);
238 * Generate a string representation of the structured <code>description</code> supplied in natural language
239 * The <code>featureTree</code> will be used to structure the NaturalLanguageDescription.
240 * This method does not require a initialization strategy so there is no <code>propertyPaths</code> parameter.
243 * @param preferredLanguages
247 public String
generateNaturalLanguageDescription(FeatureTree featureTree
,TaxonDescription description
, List
<Language
> preferredLanguages
, String separator
);
250 * Preliminary method to test whether a description contains structured data.
251 * @deprecated The means of determining this fact may change soon, so this method is annotated a beeing deprecated.
256 public boolean hasStructuredData(DescriptionBase
<?
> description
);