2 * Copyright (C) 2007 EDIT
3 * European Distributed Institute of Taxonomy
4 * http://www.e-taxonomy.eu
6 * The contents of this file are subject to the Mozilla Public License Version 1.1
7 * See LICENSE.TXT at the top of this package for the full license terms.
9 package eu
.etaxonomy
.cdm
.api
.service
;
11 import java
.util
.Collection
;
12 import java
.util
.List
;
14 import java
.util
.UUID
;
16 import eu
.etaxonomy
.cdm
.api
.service
.dto
.TaxonDistributionDTO
;
17 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
18 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
19 import eu
.etaxonomy
.cdm
.model
.common
.MarkerType
;
20 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionBase
;
21 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionElementBase
;
22 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionType
;
23 import eu
.etaxonomy
.cdm
.model
.description
.Distribution
;
24 import eu
.etaxonomy
.cdm
.model
.description
.Feature
;
25 import eu
.etaxonomy
.cdm
.model
.description
.TaxonDescription
;
26 import eu
.etaxonomy
.cdm
.model
.description
.TaxonNameDescription
;
27 import eu
.etaxonomy
.cdm
.model
.location
.NamedArea
;
28 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
29 import eu
.etaxonomy
.cdm
.model
.name
.TaxonName
;
30 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
31 import eu
.etaxonomy
.cdm
.model
.term
.DefinedTerm
;
32 import eu
.etaxonomy
.cdm
.model
.term
.TermTree
;
33 import eu
.etaxonomy
.cdm
.model
.term
.TermVocabulary
;
34 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
35 import eu
.etaxonomy
.cdm
.persistence
.dto
.DescriptionBaseDto
;
36 import eu
.etaxonomy
.cdm
.persistence
.dto
.MergeResult
;
37 import eu
.etaxonomy
.cdm
.persistence
.dto
.TaxonNodeDto
;
38 import eu
.etaxonomy
.cdm
.persistence
.dto
.TermDto
;
39 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
41 public interface IDescriptionService
extends IIdentifiableEntityService
<DescriptionBase
> {
45 * @deprecated use TermService#getVocabulary(VocabularyType) instead
48 public TermVocabulary
<Feature
> getDefaultFeatureVocabulary();
51 * List the descriptions of type <T>, filtered using the following parameters
53 * @param type The type of description returned (Taxon, TaxonName, or Specimen)
54 * @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)
55 * @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)
56 * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
57 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
58 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
59 * @param orderHints may be null
60 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
61 * @return a Pager containing DescriptionBase instances
63 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
);
66 * Count the descriptions of type <TYPE>, filtered using the following parameters
68 * @param type The type of description returned (Taxon, TaxonName, or Specimen)
69 * @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)
70 * @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)
71 * @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)
72 * @return a count of DescriptionBase instances
74 public long count(Class
<?
extends DescriptionBase
> type
, Boolean hasImages
, Boolean hasText
, Set
<Feature
> feature
);
77 * Returns description elements of type <TYPE>, belonging to a given
78 * description, optionally filtered by one or more features
81 * The description which these description elements belong to
82 * (can be null to count all description elements)
83 * @param descriptionType
84 * A filter DescriptionElements which belong to of a specific
85 * class of Descriptions
87 * Restrict the results to those description elements which are
88 * scoped by one of the Features passed (can be null or empty)
90 * A filter for DescriptionElements of a specific class
92 * The maximum number of description elements returned (can be
93 * null for all description elements)
95 * The offset (in pageSize chunks) from the start of the result
97 * @param propertyPaths
98 * Properties to initialize in the returned entities, following
99 * the syntax described in
100 * {@link IBeanInitializer#initialize(Object, List)}
102 * @return a Pager containing DescriptionElementBase instances
104 public <T
extends DescriptionElementBase
> Pager
<T
> pageDescriptionElements(
105 DescriptionBase description
, Class
<?
extends DescriptionBase
> descriptionType
,
106 Set
<Feature
> features
, Class
<T
> type
, boolean includeUnpublished
,
107 Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
110 * Returns description elements of type <TYPE>, belonging to a given
111 * description, optionally filtered by one or more features
114 * The description which these description elements belong to
115 * (can be null to count all description elements)
117 * Restrict the results to those description elements which are
118 * scoped by one of the Features passed (can be null or empty)
120 * A filter DescriptionElements of a specific class
122 * The maximum number of description elements returned (can be
123 * null for all description elements)
125 * The offset (in pageSize chunks) from the start of the result
127 * @param propertyPaths
128 * Properties to initialize in the returned entities, following
129 * the syntax described in
130 * {@link IBeanInitializer#initialize(Object, List)}
131 * @return a List of DescriptionElementBase instances
133 public <T
extends DescriptionElementBase
> List
<T
> listDescriptionElements(
134 DescriptionBase description
, Class
<?
extends DescriptionBase
> descriptionType
,
135 Set
<Feature
> features
, Class
<T
> type
, boolean includeUnpublished
,
136 Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
140 * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
142 * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
143 * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
144 * @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)
145 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
146 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
147 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
148 * @return a Pager containing TaxonDescription instances
150 * @see #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)
152 public Pager
<TaxonDescription
> pageTaxonDescriptions(Taxon taxon
, Set
<DefinedTerm
> scopes
, Set
<NamedArea
> geographicalScope
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
155 * Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method
157 * @param taxon The taxon which the description refers to (can be null for all TaxonDescription instances)
158 * @param scopes Restrict the results to those descriptions which are scoped by one of the Scope instances passed (can be null or empty)
159 * @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)
160 * @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)
161 * @param descriptionTypes Restrict the results to those descriptions of the given types (can be null or empty)
162 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
163 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
164 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
165 * @return a Pager containing TaxonDescription instances
167 public Pager
<TaxonDescription
> pageTaxonDescriptions(Taxon taxon
, Set
<DefinedTerm
> scopes
, Set
<NamedArea
> geographicalScope
, Set
<MarkerType
> markerTypes
, Set
<DescriptionType
> descriptionTypes
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
171 * @see {@link #pageTaxonDescriptions(Taxon, Set, Set, Integer, Integer, List)}
175 * @param geographicalScope
178 * @param propertyPaths
181 public List
<TaxonDescription
> listTaxonDescriptions(Taxon taxon
, Set
<DefinedTerm
> scopes
, Set
<NamedArea
> geographicalScope
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
186 * @see {@link #pageMarkedTaxonDescriptions(Taxon, Set, Set, Set, Integer, Integer, List)}
190 * @param geographicalScope
193 * @param propertyPaths
196 public List
<TaxonDescription
> listTaxonDescriptions(Taxon taxon
, Set
<DefinedTerm
> scopes
, Set
<NamedArea
> geographicalScope
, Set
<MarkerType
> markerTypes
, Set
<DescriptionType
> descriptionTypes
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
199 * Returns all {@link Media} attached to a taxon via TaxonDescription.elements.media.
200 * @param taxonUuid the taxons uuid, if null media for all taxa are returned
201 * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
202 * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
205 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
208 public List
<Media
> listTaxonDescriptionMedia(UUID taxonUuid
, boolean limitToGalleries
, Set
<MarkerType
> markerTypes
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
211 * Returns count for all {@link Media} attached to a taxon via TaxonDescription.elements.media.
212 * @param taxonUuid the taxons uuid, if null media for all taxa are returned
213 * @param limitToGalleries if true only media in TaxonDescriptions with imageGallery flag=true are returned
214 * @param markerTypes only media for TaxonDescriptions with marker of type markerType and marker.flag=true are returned, one matching marker type is sufficient
217 public int countTaxonDescriptionMedia(UUID taxonUuid
, boolean limitToGalleries
, Set
<MarkerType
> markerTypes
);
222 * Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to
224 * @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)
225 * @param pageSize The maximum number of descriptions returned (can be null for all descriptions)
226 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
227 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
228 * @return a Pager containing TaxonName instances
230 * FIXME candidate for harmonization - rename to pageTaxonNameDescriptions
232 public Pager
<TaxonNameDescription
> getTaxonNameDescriptions(TaxonName name
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
235 * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
237 * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)
239 * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)
240 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
242 * Supports path like <code>orderHints.propertyNames</code> which
243 * include *-to-one properties like createdBy.username or
244 * authorTeam.persistentTitleCache
245 * @param propertyPaths properties to be initialized
246 * @return a Pager DescriptionElementBase instances
247 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
249 public <S
extends DescriptionElementBase
> Pager
<S
> searchElements(Class
<S
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
252 * Returns a List of Media that are associated with a given description element
254 * @param descriptionElement the description element associated with these media
255 * @param pageSize The maximum number of media returned (can be null for all related media)
256 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
257 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
258 * @return a Pager containing media instances
260 * FIXME candidate for harmonization - rename to pageMedia
262 public Pager
<Media
> getMedia(DescriptionElementBase descriptionElement
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
265 * Provides access to all DescriptionElements associated with the given Taxon
266 * via a TaxonDescrition.
269 * The Taxon to return Description elements for
271 * Restrict the results to those description elements which are
272 * scoped by one of the Features passed (can be null or empty)
274 * A filter for DescriptionElements of a specific class
276 * The maximum number of description elements returned (can be
277 * null for all description elements)
279 * The offset (in pageSize chunks) from the start of the result
281 * @param propertyPaths
282 * Properties to initialize in the returned entities, following
283 * the syntax described in
284 * {@link IBeanInitializer#initialize(Object, List)}
285 * @return a List containing all matching DescriptionElementBase instances
287 * @deprecated use {@link #listDescriptionElementsForTaxon(Taxon, Set, Class, Integer, Integer, List)} instead
290 public <T
extends DescriptionElementBase
> List
<T
> getDescriptionElementsForTaxon(
291 Taxon taxon
, Set
<Feature
> features
, Class
<T
> type
, boolean includeUnpublished
,
292 Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
295 * Provides access to all DescriptionElements associated with the given Taxon
296 * via a TaxonDescrition.
299 * The Taxon to return Description elements for
301 * Restrict the results to those description elements which are
302 * scoped by one of the Features passed (can be null or empty)
304 * A filter for DescriptionElements of a specific class
305 * @param includeUnpublished
306 * If true factual data in a description not being published
309 * The maximum number of description elements returned (can be
310 * null for all description elements)
312 * The offset (in pageSize chunks) from the start of the result
314 * @param propertyPaths
315 * Properties to initialize in the returned entities, following
316 * the syntax described in
317 * {@link IBeanInitializer#initialize(Object, List)}
318 * @return a List containing all matching DescriptionElementBase instances
321 public <T
extends DescriptionElementBase
> List
<T
> listDescriptionElementsForTaxon(
322 Taxon taxon
, Set
<Feature
> features
, Class
<T
> type
, boolean includePublished
,
323 Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
326 * Provides access to all DescriptionElements associated with the given Taxon
327 * via a TaxonDescrition.
330 * The Taxon to return Description elements for
332 * Restrict the results to those description elements which are
333 * scoped by one of the Features passed (can be null or empty)
335 * A filter for DescriptionElements of a specific class
336 * @param includeUnpublished
337 * If true factual data in a description not being published
340 * The maximum number of description elements returned
342 * The offset (in pageSize chunks) from the start of the result
344 * @param propertyPaths
345 * Properties to initialize in the returned entities, following
346 * the syntax described in
347 * {@link IBeanInitializer#initialize(Object, List)}
348 * @return a Pager for all matching DescriptionElementBase instances
351 public <T
extends DescriptionElementBase
> Pager
<T
> pageDescriptionElementsForTaxon(
352 Taxon taxon
, Set
<Feature
> features
, Class
<T
> type
, boolean includeUnpublished
,
353 Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
356 * Generate a string representation of the structured <code>description</code> supplied in natural language
357 * The <code>featureTree</code> will be used to structure the NaturalLanguageDescription.
358 * This method does not require a initialization strategy so there is no <code>propertyPaths</code> parameter.
360 public String
generateNaturalLanguageDescription(TermTree featureTree
,TaxonDescription description
, List
<Language
> preferredLanguages
, String separator
);
363 * Preliminary method to test whether a description contains structured data.
364 * @deprecated The means of determining this fact may change soon, so this method is
365 annotated as being deprecated.
369 public boolean hasStructuredData(DescriptionBase
<?
> description
);
372 * Add the collection of {@link DescriptionElementBase description elements} to the <code>targetDescription</code>.
373 * Remove the description elements from the description they are currently associated with.
375 * @param descriptionElements
376 * @param targetDescription
377 * @param isPaste if true, the elements are only copied (cloned) and not removed from the
381 public UpdateResult
moveDescriptionElementsToDescription(Collection
<DescriptionElementBase
> descriptionElements
, DescriptionBase targetDescription
, boolean isPaste
, boolean setNameInSource
);
384 * Pager method to get all {@link NamedAreas} instances which are currently used
385 * by {@link Distribution} elements.
388 * The maximum number of description elements returned
390 * The offset (in pageSize chunks) from the start of the result
392 * @param propertyPaths
393 * Properties to initialize in the returned entities, following
394 * the syntax described in
395 * {@link IBeanInitializer#initialize(Object, List)}
396 * @return a Pager for all NamedAreas instances which are currently in use.
399 public Pager
<TermDto
> pageNamedAreasInUse(boolean includeAllParents
, Integer pageSize
,
403 * Deletes the description and prior removes it from taxon, specimen or descriptive dataset.
405 public DeleteResult
deleteDescription(DescriptionBase
<?
> description
);
407 public DeleteResult
deleteDescription(UUID descriptionUuid
);
409 public UpdateResult
moveTaxonDescriptions(Taxon sourceTaxon
, Taxon targetTaxon
, boolean setNameInSource
);
411 public UpdateResult
moveTaxonDescriptions(UUID sourceTaxonUuid
, UUID targetTaxonUuid
, boolean setNameInSource
);
413 public UpdateResult
moveDescriptionElementsToDescription(Set
<UUID
> descriptionElementUUIDs
, UUID targetDescriptionUuid
,
414 boolean isCopy
, boolean setNameInSource
);
416 public UpdateResult
moveDescriptionElementsToDescription(Set
<UUID
> descriptionElementUUIDs
, UUID targetTaxonUuid
,
417 String moveMessage
, boolean isCopy
, boolean setNameInSource
, boolean useDefaultDescription
, boolean createNewCurrentDeterminations
);
419 public UpdateResult
moveTaxonDescription(UUID descriptionUuid
, UUID targetTaxonUuid
, boolean setNameInSource
);
421 public List
<MergeResult
<DescriptionBase
>> mergeDescriptionElements(Collection
<TaxonDistributionDTO
> descriptionElements
,
422 boolean returnTransientEntity
);
424 public UpdateResult
mergeDescriptions(Collection
<DescriptionBaseDto
> descriptions
, UUID descriptiveDataSetUuid
);
426 public UpdateResult
moveDescriptionElementsToDescription(Set
<UUID
> descriptionElementUUIDs
,
427 DescriptionBase targetDescription
, boolean isCopy
, boolean setNameInSource
);
429 public DeleteResult
isDeletable(UUID descriptionUuid
);
431 public DescriptionBaseDto
loadDto(UUID descriptionUuid
);
432 public List
<DescriptionBaseDto
> loadDtos(Set
<UUID
> descriptionUuid
);
434 public List
<DescriptionBaseDto
> loadDtosForTaxon(UUID taxonUuid
);
437 * Find the taxon node for the taxon associated to the specimen in classification with classificationUuid
439 public TaxonNodeDto
findTaxonNodeDtoForIndividualAssociation(UUID specimenUuid
, UUID classificationUuid
);