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
.DefinedTerm
;
22 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
23 import eu
.etaxonomy
.cdm
.model
.common
.MarkerType
;
24 import eu
.etaxonomy
.cdm
.model
.common
.TermVocabulary
;
25 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionBase
;
26 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionElementBase
;
27 import eu
.etaxonomy
.cdm
.model
.description
.Feature
;
28 import eu
.etaxonomy
.cdm
.model
.description
.FeatureTree
;
29 import eu
.etaxonomy
.cdm
.model
.description
.PresenceAbsenceTermBase
;
30 import eu
.etaxonomy
.cdm
.model
.description
.TaxonDescription
;
31 import eu
.etaxonomy
.cdm
.model
.description
.TaxonNameDescription
;
32 import eu
.etaxonomy
.cdm
.model
.location
.NamedArea
;
33 import eu
.etaxonomy
.cdm
.model
.location
.NamedAreaLevel
;
34 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
35 import eu
.etaxonomy
.cdm
.model
.name
.TaxonNameBase
;
36 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
37 import eu
.etaxonomy
.cdm
.persistence
.dao
.IBeanInitializer
;
38 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
40 public interface IDescriptionService
extends IIdentifiableEntityService
<DescriptionBase
> {
45 * @deprecated use TermService#getVocabulary(VocabularyType) instead
48 public TermVocabulary
<Feature
> getDefaultFeatureVocabulary();
51 * @deprecated use TermService#getVocabulary(VocabularyType) instead
54 public TermVocabulary
<Feature
> getFeatureVocabulary(UUID uuid
);
57 * Gets a DescriptionElementBase instance matching the supplied uuid
59 * @param uuid the uuid of the DescriptionElement of interest
60 * @return a DescriptionElement, or null if the DescriptionElement does not exist
62 public DescriptionElementBase
getDescriptionElementByUuid(UUID uuid
);
65 * Loads and existing DescriptionElementBase instance matching the supplied uuid,
66 * and recursively initializes all bean properties given in the
67 * <code>propertyPaths</code> parameter.
69 * For detailed description and examples <b>please refer to:</b>
70 * {@link IBeanInitializer#initialize(Object, List)}
72 * @param uuid the uuid of the DescriptionElement of interest
73 * @return a DescriptionElement, or null if the DescriptionElement does not exist
75 public DescriptionElementBase
loadDescriptionElement(UUID uuid
,List
<String
> propertyPaths
);
78 * Persists a <code>DescriptionElementBase</code>
79 * @param descriptionElement
82 public UUID
saveDescriptionElement(DescriptionElementBase descriptionElement
);
85 * Persists a collection of <code>DescriptionElementBase</code>
86 * @param descriptionElements
89 public Map
<UUID
, DescriptionElementBase
> saveDescriptionElement(Collection
<DescriptionElementBase
> descriptionElements
);
92 * Delete an existing description element
94 * @param descriptionElement the description element to be deleted
95 * @return the unique identifier of the deleted entity
97 public UUID
deleteDescriptionElement(DescriptionElementBase descriptionElement
);
100 * List the descriptions of type <T>, filtered using the following parameters
102 * @param type The type of description returned (Taxon, TaxonName, or Specimen)
103 * @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)
104 * @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)
105 * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
106 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
107 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
108 * @param orderHints may be null
109 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
110 * @return a Pager containing DescriptionBase instances
112 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
);
115 * Count the descriptions of type <TYPE>, filtered using the following parameters
117 * @param type The type of description returned (Taxon, TaxonName, or Specimen)
118 * @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)
119 * @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)
120 * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
121 * @return a count of DescriptionBase instances
123 public int count(Class
<?
extends DescriptionBase
> type
, Boolean hasImages
, Boolean hasText
, Set
<Feature
> feature
);
126 * Returns description elements of type <TYPE>, belonging to a given
127 * description, optionally filtered by one or more features
130 * The description which these description elements belong to
131 * (can be null to count all description elements)
132 * @param descriptionType
133 * A filter DescriptionElements which belong to of a specific
134 * class of Descriptions
136 * Restrict the results to those description elements which are
137 * scoped by one of the Features passed (can be null or empty)
139 * A filter for DescriptionElements of a specific class
141 * The maximum number of description elements returned (can be
142 * null for all description elements)
144 * The offset (in pageSize chunks) from the start of the result
146 * @param propertyPaths
147 * Properties to initialize in the returned entities, following
148 * the syntax described in
149 * {@link IBeanInitializer#initialize(Object, List)}
150 * @return a Pager containing DescriptionElementBase instances
153 * {@link #pageDescriptionElements(DescriptionBase, Set, Class, Integer, Integer, List)}
157 public Pager
<DescriptionElementBase
> getDescriptionElements(DescriptionBase description
,Set
<Feature
> features
, Class
<?
extends DescriptionElementBase
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
161 * Returns description elements of type <TYPE>, belonging to a given
162 * description, optionally filtered by one or more features
165 * The description which these description elements belong to
166 * (can be null to count all description elements)
167 * @param descriptionType
168 * A filter DescriptionElements which belong to of a specific
169 * class of Descriptions
171 * Restrict the results to those description elements which are
172 * scoped by one of the Features passed (can be null or empty)
174 * A filter for DescriptionElements of a specific class
176 * The maximum number of description elements returned (can be
177 * null for all description elements)
179 * The offset (in pageSize chunks) from the start of the result
181 * @param propertyPaths
182 * Properties to initialize in the returned entities, following
183 * the syntax described in
184 * {@link IBeanInitializer#initialize(Object, List)}
186 * @return a Pager containing DescriptionElementBase instances
188 public Pager
<DescriptionElementBase
> pageDescriptionElements(DescriptionBase description
, Class
<?
extends DescriptionBase
> descriptionType
, Set
<Feature
> features
, Class
<?
extends DescriptionElementBase
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
191 * Returns description elements of type <TYPE>, belonging to a given
192 * description, optionally filtered by one or more features
195 * The description which these description elements belong to
196 * (can be null to count all description elements)
198 * Restrict the results to those description elements which are
199 * scoped by one of the Features passed (can be null or empty)
201 * A filter for DescriptionElements of a specific class
203 * The maximum number of description elements returned (can be
204 * null for all description elements)
206 * The offset (in pageSize chunks) from the start of the result
208 * @param propertyPaths
209 * Properties to initialize in the returned entities, following
210 * the syntax described in
211 * {@link IBeanInitializer#initialize(Object, List)}
212 * @return a List of DescriptionElementBase instances
213 * @deprecated use {@link #listDescriptionElements(DescriptionBase, Class, Set, Class, Integer, Integer, List)} instead
216 public List
<DescriptionElementBase
> listDescriptionElements(DescriptionBase description
,Set
<Feature
> features
, Class
<?
extends DescriptionElementBase
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
219 * Returns description elements of type <TYPE>, belonging to a given
220 * description, optionally filtered by one or more features
223 * The description which these description elements belong to
224 * (can be null to count all description elements)
226 * Restrict the results to those description elements which are
227 * scoped by one of the Features passed (can be null or empty)
229 * A filter DescriptionElements of a for specific class
231 * The maximum number of description elements returned (can be
232 * null for all description elements)
234 * The offset (in pageSize chunks) from the start of the result
236 * @param propertyPaths
237 * Properties to initialize in the returned entities, following
238 * the syntax described in
239 * {@link IBeanInitializer#initialize(Object, List)}
240 * @return a List of DescriptionElementBase instances
242 public List
<DescriptionElementBase
> listDescriptionElements(DescriptionBase description
, Class
<?
extends DescriptionBase
> descriptionType
, Set
<Feature
> features
, Class
<?
extends DescriptionElementBase
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
245 * Return a Pager containing Annotation entities belonging to the DescriptionElementBase instance supplied, optionally filtered by MarkerType
246 * @param annotatedObj The object that "owns" the annotations returned
247 * @param status Only return annotations which are marked with a Marker of this type (can be null to return all annotations)
248 * @param pageSize The maximum number of terms returned (can be null for all annotations)
249 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
250 * @param orderHints may be null
251 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
252 * @return a Pager of Annotation entities
254 public Pager
<Annotation
> getDescriptionElementAnnotations(DescriptionElementBase annotatedObj
, MarkerType status
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
258 * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
260 * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
261 * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
262 * @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)
263 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
264 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
265 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
266 * @return a Pager containing TaxonDescription instances
268 * @see #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)
270 public Pager
<TaxonDescription
> pageTaxonDescriptions(Taxon taxon
, Set
<DefinedTerm
> scopes
, Set
<NamedArea
> geographicalScope
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
273 * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
275 * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
276 * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
277 * @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)
278 * @param markerType Restrict the results to those descriptions which are marked as true by one of the given marker types (can be null or empty)
279 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
280 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
281 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
282 * @return a Pager containing TaxonDescription instances
284 public Pager
<TaxonDescription
> pageTaxonDescriptions(Taxon taxon
, Set
<DefinedTerm
> scopes
, Set
<NamedArea
> geographicalScope
, Set
<MarkerType
> markerTypes
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
287 * @see {@link #pageTaxonDescriptions(Taxon, Set, Set, Integer, Integer, List)}
291 * @param geographicalScope
294 * @param propertyPaths
297 public List
<TaxonDescription
> listTaxonDescriptions(Taxon taxon
, Set
<DefinedTerm
> scopes
, Set
<NamedArea
> geographicalScope
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
302 * @see {@link #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)}
306 * @param geographicalScope
309 * @param propertyPaths
312 public List
<TaxonDescription
> listTaxonDescriptions(Taxon taxon
, Set
<DefinedTerm
> scopes
, Set
<NamedArea
> geographicalScope
, Set
<MarkerType
> markerTypes
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
315 * Returns all {@link Media} attached to a taxon via TaxonDescription.elements.media.
316 * @param taxonUuid the taxons uuid, if null media for all taxa are returned
317 * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
318 * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
321 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
324 public List
<Media
> listTaxonDescriptionMedia(UUID taxonUuid
, boolean limitToGalleries
, Set
<MarkerType
> markerTypes
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
327 * Returns count for all {@link Media} attached to a taxon via TaxonDescription.elements.media.
328 * @param taxonUuid the taxons uuid, if null media for all taxa are returned
329 * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
330 * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
333 public int countTaxonDescriptionMedia(UUID taxonUuid
, boolean limitToGalleries
, Set
<MarkerType
> markerTypes
);
338 * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
340 * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
341 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
342 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
343 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
344 * @return a Pager containing TaxonNameBase instances
346 * FIXME candidate for harmonization - rename to pageTaxonNameDescriptions
348 public Pager
<TaxonNameDescription
> getTaxonNameDescriptions(TaxonNameBase name
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
352 * Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally
353 * filtered by a type of PresenceAbsenceTerm e.g. PRESENT / ABSENT / NATIVE / CULTIVATED etc)
355 * @param namedAreas The set of NamedArea instances
356 * @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)
357 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
358 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
359 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
360 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
361 * @return a Pager containing TaxonDescription instances
363 public Pager
<TaxonDescription
> searchDescriptionByDistribution(Set
<NamedArea
> namedAreas
, PresenceAbsenceTermBase presence
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
366 * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
368 * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
370 * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
371 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
373 * Supports path like <code>orderHints.propertyNames</code> which
374 * include *-to-one properties like createdBy.username or
375 * authorTeam.persistentTitleCache
376 * @param propertyPaths properties to be initialized
377 * @return a Pager DescriptionElementBase instances
378 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
380 public Pager
<DescriptionElementBase
> searchElements(Class
<?
extends DescriptionElementBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
383 * Returns a List of Media that are associated with a given description element
385 * @param descriptionElement the description element associated with these media
386 * @param pageSize The maximum number of media returned (can be null for all related media)
387 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
388 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
389 * @return a Pager containing media instances
391 * FIXME candidate for harmonization - rename to pageMedia
393 public Pager
<Media
> getMedia(DescriptionElementBase descriptionElement
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
396 * Provides access to all DescriptionElements associated with the given Taxon
397 * via a TaxonDescrition.
400 * The Taxon to return Description elements for
402 * Restrict the results to those description elements which are
403 * scoped by one of the Features passed (can be null or empty)
405 * A filter for DescriptionElements of a specific class
407 * The maximum number of description elements returned (can be
408 * null for all description elements)
410 * The offset (in pageSize chunks) from the start of the result
412 * @param propertyPaths
413 * Properties to initialize in the returned entities, following
414 * the syntax described in
415 * {@link IBeanInitializer#initialize(Object, List)}
416 * @return a List containing all matching DescriptionElementBase instances
418 * @deprecated use {@link #listDescriptionElementsForTaxon(Taxon, Set, Class, Integer, Integer, List)} instead
421 public <T
extends DescriptionElementBase
> List
<T
> getDescriptionElementsForTaxon(Taxon taxon
, Set
<Feature
> features
, Class
<T
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
424 * Provides access to all DescriptionElements associated with the given Taxon
425 * via a TaxonDescrition.
428 * The Taxon to return Description elements for
430 * Restrict the results to those description elements which are
431 * scoped by one of the Features passed (can be null or empty)
433 * A filter for DescriptionElements of a specific class
435 * The maximum number of description elements returned (can be
436 * null for all description elements)
438 * The offset (in pageSize chunks) from the start of the result
440 * @param propertyPaths
441 * Properties to initialize in the returned entities, following
442 * the syntax described in
443 * {@link IBeanInitializer#initialize(Object, List)}
444 * @return a List containing all matching DescriptionElementBase instances
447 public <T
extends DescriptionElementBase
> List
<T
> listDescriptionElementsForTaxon(Taxon taxon
, Set
<Feature
> features
, Class
<T
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
450 * Provides access to all DescriptionElements associated with the given Taxon
451 * via a TaxonDescrition.
454 * The Taxon to return Description elements for
456 * Restrict the results to those description elements which are
457 * scoped by one of the Features passed (can be null or empty)
459 * A filter for DescriptionElements of a specific class
461 * The maximum number of description elements returned
463 * The offset (in pageSize chunks) from the start of the result
465 * @param propertyPaths
466 * Properties to initialize in the returned entities, following
467 * the syntax described in
468 * {@link IBeanInitializer#initialize(Object, List)}
469 * @return a Pager for all matching DescriptionElementBase instances
472 public <T
extends DescriptionElementBase
> Pager
<T
> pageDescriptionElementsForTaxon(Taxon taxon
, Set
<Feature
> features
, Class
<T
> type
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
475 public DistributionTree
getOrderedDistributions(Set
<TaxonDescription
> taxonDescriptions
, Set
<NamedAreaLevel
> levels
, List
<String
> propertyPaths
);
478 * Generate a string representation of the structured <code>description</code> supplied in natural language
479 * The <code>featureTree</code> will be used to structure the NaturalLanguageDescription.
480 * This method does not require a initialization strategy so there is no <code>propertyPaths</code> parameter.
483 * @param preferredLanguages
487 public String
generateNaturalLanguageDescription(FeatureTree featureTree
,TaxonDescription description
, List
<Language
> preferredLanguages
, String separator
);
490 * Preliminary method to test whether a description contains structured data.
491 * @deprecated The means of determining this fact may change soon, so this method is
492 annotated as being deprecated.
497 public boolean hasStructuredData(DescriptionBase
<?
> description
);
500 * Add the collection of {@link DescriptionElementBase description elements} to the <code>targetDescription</code>.
501 * Remove the description elements from the description they are currently associated with.
503 * @param descriptionElements
504 * @param targetDescription
505 * @param isPaste if true, the elements are only copied (cloned) and not removed from the
508 public void moveDescriptionElementsToDescription(Collection
<DescriptionElementBase
> descriptionElements
, DescriptionBase targetDescription
, boolean isPaste
);