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.
10 package eu
.etaxonomy
.cdm
.api
.service
;
12 import java
.io
.IOException
;
13 import java
.util
.EnumSet
;
14 import java
.util
.List
;
16 import java
.util
.UUID
;
18 import eu
.etaxonomy
.cdm
.api
.service
.config
.IFindTaxaAndNamesConfigurator
;
19 import eu
.etaxonomy
.cdm
.api
.service
.config
.IncludedTaxonConfiguration
;
20 import eu
.etaxonomy
.cdm
.api
.service
.config
.MatchingTaxonConfigurator
;
21 import eu
.etaxonomy
.cdm
.api
.service
.config
.SynonymDeletionConfigurator
;
22 import eu
.etaxonomy
.cdm
.api
.service
.config
.TaxonDeletionConfigurator
;
23 import eu
.etaxonomy
.cdm
.api
.service
.dto
.IdentifiedEntityDTO
;
24 import eu
.etaxonomy
.cdm
.api
.service
.dto
.IncludedTaxaDTO
;
25 import eu
.etaxonomy
.cdm
.api
.service
.dto
.MarkedEntityDTO
;
26 import eu
.etaxonomy
.cdm
.api
.service
.exception
.DataChangeNoRollbackException
;
27 import eu
.etaxonomy
.cdm
.api
.service
.exception
.HomotypicalGroupChangeException
;
28 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
29 import eu
.etaxonomy
.cdm
.api
.service
.search
.LuceneMultiSearchException
;
30 import eu
.etaxonomy
.cdm
.api
.service
.search
.LuceneParseException
;
31 import eu
.etaxonomy
.cdm
.api
.service
.search
.SearchResult
;
32 import eu
.etaxonomy
.cdm
.api
.service
.util
.TaxonRelationshipEdge
;
33 import eu
.etaxonomy
.cdm
.model
.common
.DefinedTerm
;
34 import eu
.etaxonomy
.cdm
.model
.common
.IdentifiableEntity
;
35 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
36 import eu
.etaxonomy
.cdm
.model
.common
.MarkerType
;
37 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionElementBase
;
38 import eu
.etaxonomy
.cdm
.model
.description
.Feature
;
39 import eu
.etaxonomy
.cdm
.model
.description
.PresenceAbsenceTerm
;
40 import eu
.etaxonomy
.cdm
.model
.location
.NamedArea
;
41 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
42 import eu
.etaxonomy
.cdm
.model
.media
.MediaRepresentation
;
43 import eu
.etaxonomy
.cdm
.model
.name
.HomotypicalGroup
;
44 import eu
.etaxonomy
.cdm
.model
.name
.Rank
;
45 import eu
.etaxonomy
.cdm
.model
.name
.TaxonName
;
46 import eu
.etaxonomy
.cdm
.model
.reference
.Reference
;
47 import eu
.etaxonomy
.cdm
.model
.taxon
.Classification
;
48 import eu
.etaxonomy
.cdm
.model
.taxon
.Synonym
;
49 import eu
.etaxonomy
.cdm
.model
.taxon
.SynonymType
;
50 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
51 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonBase
;
52 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonNode
;
53 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationship
;
54 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationshipType
;
55 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
56 import eu
.etaxonomy
.cdm
.persistence
.dto
.UuidAndTitleCache
;
57 import eu
.etaxonomy
.cdm
.persistence
.query
.MatchMode
;
58 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
59 import eu
.etaxonomy
.cdm
.persistence
.query
.TaxonTitleType
;
62 public interface ITaxonService
63 extends IIdentifiableEntityService
<TaxonBase
>, IPublishableService
<TaxonBase
>{
68 * NOTE: Also taxa with <code>publish=false</code> are returned.
71 public TaxonBase
load(UUID uuid
, List
<String
> propertyPaths
);
74 * Returns a list of taxa that matches the name string and the sec reference
75 * @param name the name string to search for
76 * @param sec the taxons sec reference
77 * @return a list of taxa matching the name and the sec reference
79 public List
<TaxonBase
> searchByName(String name
, boolean includeUnpublished
, Reference sec
);
82 * Swaps given synonym and accepted taxon.
85 * <li>A new accepted taxon with the synonyms name is created</li>
86 * <li>The synonym is deleted from the old accepted taxons synonym list</li>
87 * <li>A new synonym with the name of the old accepted taxon is created</li>
88 * <li>The newly created synonym get related to the newly created accepted taxon</li>
92 * @param acceptedTaxon
95 public UpdateResult
swapSynonymAndAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
);
98 * Changes a synonym into an accepted taxon and removes
99 * the synonym relationship to the given accepted taxon.
100 * Other synonyms homotypic to the synonym to change are
101 * moved to the same new accepted taxon as homotypic
102 * synonyms. The new accepted taxon has the same name and
103 * the same sec reference as the old synonym.<BR>
104 * If the given accepted taxon and the synonym are homotypic
105 * to each other an exception may be thrown as taxonomically it doesn't
106 * make sense to have two accepted taxa in the same homotypic group
107 * but also it is than difficult to decide how to handle other names
108 * in the homotypic group. It is up to the implementing class to
109 * handle this situation via an exception or in another way.
113 * the synonym to change into an accepted taxon
114 * @param acceptedTaxon
115 * an accepted taxon, the synonym had a relationship to
116 * @param deleteSynonym
117 * if true the method tries to delete the old synonym from the database
119 * the newly created accepted taxon
120 * @throws IllegalArgumentException
121 * if the given accepted taxon and the synonym are homotypic
122 * to each other an exception may be thrown as taxonomically it doesn't
123 * make sense to have two accepted taxa in the same homotypic group
124 * but also it is than difficult to decide how to handle other names
125 * in the homotypic group. It is up to the implementing class to
126 * handle this situation via an exception or in another way.
128 public UpdateResult
changeSynonymToAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
, boolean deleteSynonym
) throws HomotypicalGroupChangeException
;
132 * @param acceptedTaxonUuid
133 * @param newParentNodeUuid
134 * @param deleteSynonym
136 * @throws HomotypicalGroupChangeException
138 public UpdateResult
changeSynonymToAcceptedTaxon(UUID synonymUuid
, UUID acceptedTaxonUuid
, UUID newParentNodeUuid
,
139 boolean deleteSynonym
)
140 throws HomotypicalGroupChangeException
;
143 * Change a synonym into a related concept
146 * the synonym to change into the concept taxon
148 * the taxon the newly created concept should be related to
149 * @param taxonRelationshipType
150 * the type of relationship
152 * @param microReference
154 * update result with the newly created concept
156 public UpdateResult
changeSynonymToRelatedTaxon(Synonym synonym
, Taxon toTaxon
, TaxonRelationshipType taxonRelationshipType
, Reference reference
, String microReference
);
160 * Change a related concept into synonym
163 * the concept taxon to change into a synonym
165 * the taxon the newly created synonym should be related to
166 * @param oldRelationshipType
167 * the type of old concept relationship
168 * @param synonymRelationshipType
169 * the type of new synonym relationship
172 * update result with the newly created synonym
173 * @throws DataChangeNoRollbackException
175 public UpdateResult
changeRelatedTaxonToSynonym(Taxon fromTaxon
, Taxon toTaxon
,
176 TaxonRelationshipType oldRelationshipType
,
177 SynonymType synonymType
) throws DataChangeNoRollbackException
;
180 * Changes the homotypic group of a synonym into the new homotypic group.
181 * All relations to taxa are updated correctly depending on the homotypic
182 * group of the accepted taxon. <BR>
183 * All existing basionym relationships to and from this name are removed.<BR>
184 * If the parameter <code>targetTaxon</code> is defined, the synonym is
185 * added to this taxon irrespctive of if it has been related to this
187 * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
188 * between the existing basionym(s) of the new homotypic group and the synonyms name
192 * @param newHomotypicalGroup
194 * @param setBasionymRelationIfApplicable
196 public void changeHomotypicalGroupOfSynonym(Synonym synonym
, HomotypicalGroup newHomotypicalGroup
,
197 Taxon targetTaxon
, boolean setBasionymRelationIfApplicable
);
200 * See {@link #moveSynonymToAnotherTaxon(Synonym, Taxon, boolean, SynonymType, Reference, String, boolean)}
203 * @param moveHomotypicGroup
204 * @param newSynonymType
206 * @throws HomotypicalGroupChangeException
208 public UpdateResult
moveSynonymToAnotherTaxon(Synonym oldSynonym
, Taxon newTaxon
, boolean moveHomotypicGroup
,
209 SynonymType newSynonymType
) throws HomotypicalGroupChangeException
;
213 * Moves a synonym to another taxon and removes the old synonym relationship.
215 * @param oldSynonym the old synonym to move.
216 * @param newTaxon the taxon the synonym will be moved to
217 * @param moveHomotypicGroup if the synonym belongs to a homotypic group with other synonyms and
218 * <code>moveHomotypicGroup</code> is <code>true</code> all these synonyms are moved to the new taxon,
219 * if <code>false</code> a {@link HomotypicalGroupChangeException} is thrown.
220 * <code>moveHomotypicGroup</code> has no effect if the synonym is the only synonym in it's homotypic group.
221 * @param newSynonymType the synonym type of the new synonyms. Default is
222 * {@link SynonymType#HETEROTYPIC_SYNONYM_OF() heterotypic}.
223 * @param newSecundum The secundum for the new synonyms).
224 * @param newSecundumDetail The secundum micro reference for the new synonym(s).
225 * @param keepSecundumIfUndefined if no <code>newSecundum</code> and/or no <code>newSecundumDetail</code>
226 * is defined they are taken from the old synonym(s) if <code>keepSecundumIfUndefined</code> is
227 * <code>true</code>. If <code>false</code> the secundum and the secundum detail will be taken
228 * only from the <code>newSecundum</code> and <code>newSecundumDetail</code> even if they are
229 * undefined (<code>null</code>).
230 * @return The new synonym relationship. If <code>moveHomotypicGroup</code> is <code>true</code> additionally
231 * created new synonym relationships must be retrieved separately from the new taxon.
232 * @throws HomotypicalGroupChangeException Exception is thrown if (1) synonym is homotypic to the old accepted taxon or
233 * (2) synonym is in homotypic group with other synonyms and <code>moveHomotypicGroup</code> is false
235 public UpdateResult
moveSynonymToAnotherTaxon(Synonym oldSynonym
, Taxon newTaxon
, boolean moveHomotypicGroup
,
236 SynonymType newSynonymType
, Reference newSecundum
,
237 String newSecundumDetail
, boolean keepSecundumIfUndefined
) throws HomotypicalGroupChangeException
;
242 * @param newTaxonUUID
243 * @param moveHomotypicGroup
244 * @param newSynonymType
246 * @param referenceDetail
247 * @param keepReference
249 * @throws HomotypicalGroupChangeException
251 * @see {@link #moveSynonymToAnotherTaxon(Synonym, Taxon, boolean, SynonymType, Reference, String, boolean)}
253 public UpdateResult
moveSynonymToAnotherTaxon(Synonym oldSynonym
,
254 UUID newTaxonUUID
, boolean moveHomotypicGroup
,
255 SynonymType newSynonymType
,
256 Reference newSecundum
, String newSecundumDetail
, boolean keepSecundumIfUndefined
)
257 throws HomotypicalGroupChangeException
;
260 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
261 * where the supplied taxon is relatedTo.
263 * @param taxon The taxon that is relatedTo
264 * @param type The type of TaxonRelationship (can be null)
265 * @param includeUnpublished should unpublished related taxa also be returned?
266 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
267 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
268 * @param orderHints Properties to order by
269 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
270 * @return a List of TaxonRelationship instances
272 public List
<TaxonRelationship
> listToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
,
273 boolean includeUnpublished
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
277 * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
278 * where the supplied taxon is relatedTo.
280 * @param taxon The taxon that is relatedTo
281 * @param type The type of TaxonRelationship (can be null)
282 * @param includeUnpublished should unpublished related taxa also be returned?
283 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
284 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
285 * @param orderHints Properties to order by
286 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
287 * @return a Pager of TaxonRelationship instances
289 public Pager
<TaxonRelationship
> pageToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
,
290 boolean includeUnpublished
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
293 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
294 * where the supplied taxon is relatedFrom.
296 * @param taxon The taxon that is relatedFrom
297 * @param type The type of TaxonRelationship (can be null)
298 * @param includeUnpublished should unpublished related taxa also be returned?
299 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
300 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
301 * @param orderHints Properties to order by
302 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
303 * @return a List of TaxonRelationship instances
305 public List
<TaxonRelationship
> listFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
,
306 boolean includeUnpublished
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
310 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
311 * where the supplied taxon is relatedFrom.
313 * @param taxon The taxon that is relatedFrom
314 * @param type The type of TaxonRelationship (can be null)
315 * @param includeUnpublished should unpublished related taxa also be returned?
316 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
317 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
318 * @param orderHints Properties to order by
319 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
320 * @return a Pager of TaxonRelationship instances
322 public Pager
<TaxonRelationship
> pageFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
,
323 boolean includeUnpublished
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
326 * lists all taxa which are related to the <code>taxon</code> given as
330 * @param includeRelationships
332 * <code>1</code> for one level, <code>null</code> for infinite
333 * depth, <code>0</code> will completely omit collecting related taxa.
336 * @param propertyPaths
339 public Set
<Taxon
> listRelatedTaxa(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, Integer maxDepth
,
340 boolean includeUnpublished
, Integer limit
, Integer start
, List
<String
> propertyPaths
);
344 * Returns all or a page of all taxon concept relationships in the database.
345 * The result can be filtered by relationship types.
347 * @param types The taxon relationship type filter, if <code>null</code> no filter is set, if empty the result will also be empty
348 * @param pageSize the page size
349 * @param pageStart the number of the start page
350 * @param orderHints the order hints
351 * @param propertyPaths the property path to initialize the resulting objects
352 * @return list of taxon relationships matching the filter criteria
354 public List
<TaxonRelationship
> listTaxonRelationships(Set
<TaxonRelationshipType
> types
,
355 Integer pageSize
, Integer pageStart
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
358 * Lists all classifications the given taxon/synonym is used in{@link Synonym}
363 * @param propertyPaths
366 public List
<Classification
> listClassifications(TaxonBase taxonBase
, Integer limit
, Integer start
, List
<String
> propertyPaths
);
369 * Returns the Synonyms (with the given synonym relationship type, if this argument is supplied)
370 * that do have the supplied taxon as accepted taxon.
372 * @param taxon The accepted taxon
373 * @param type The type of Synonym (can be null)
374 * @param pageSize The maximum number of synonyms returned (can be null for returning synonyms)
375 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
376 * * @param orderHints Properties to order by
377 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
378 * @return a Pager of {@link Synonym} instances
380 public Pager
<Synonym
> getSynonyms(Taxon taxon
, SynonymType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
383 * This method returns in the first entry the list of synonyms of the
384 * homotypic group of the accepted taxon. All other entries represent the lists of heterotypic
385 * synonym groups. For detailed information about these 2 groups see
386 * {@link #getHomotypicSynonymsByHomotypicGroup(Taxon, List)} and
387 * {@link #getHeterotypicSynonymyGroups(Taxon, List)}
389 * @see #getSynonyms()
390 * @see SynonymType#HETEROTYPIC_SYNONYM_OF()
391 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
393 * @param taxon the accepted taxon
394 * @param propertyPaths the property path
395 * @return the list of groups of synonyms
397 public List
<List
<Synonym
>> getSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
401 * Returns the list of all synonyms that share the same homotypical group with the given taxon.
402 * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
404 * @param propertyPaths
407 public List
<Synonym
> getHomotypicSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
410 * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
411 * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
412 * {@link eu.etaxonomy.cdm.model.name.TaxonName Taxon names} of heterotypic synonyms
413 * belong to a homotypical group which cannot be the homotypical group to which the
414 * taxon name of the given taxon belongs. This method does not return the homotypic group the given
415 * taxon belongs to.<BR>
416 * This method does neglect the type of synonym relationship that is defined between the given taxon
417 * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
418 * in one of the result lists as long as the synonym does not belong to the same homotypic group as
419 * the given taxon.<BR>
420 * The list returned is ordered according to the date of publication of the
421 * first published name within each homotypical group.
423 * @see #getHeterotypicSynonymyGroups()
424 * @see #getSynonyms()
425 * @see SynonymType#HETEROTYPIC_SYNONYM_OF()
426 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
429 * @param propertyPaths
432 public List
<List
<Synonym
>> getHeterotypicSynonymyGroups(Taxon taxon
, List
<String
> propertyPaths
);
435 * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
437 * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
439 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
440 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
442 * Supports path like <code>orderHints.propertyNames</code> which
443 * include *-to-one properties like createdBy.username or
444 * authorTeam.persistentTitleCache
445 * @param propertyPaths properties to be initialized
446 * @return a Pager Taxon instances
447 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
450 public Pager
<TaxonBase
> search(Class
<?
extends TaxonBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
453 * Returns a list of TaxonBase instances where the
454 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
455 * <i>null</i> will search for those taxa with a value of null in that field
457 * @param clazz optionally filter by class (can be null to return all taxa)
459 * @param infragenericEpithet
460 * @param specificEpithet
461 * @param infraspecificEpithet
463 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
464 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
465 * @return a list of TaxonBase instances
467 public Pager
<TaxonBase
> findTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, String authorship
, Rank rank
, Integer pageSize
, Integer pageNumber
);
470 * Returns a list of TaxonBase instances where the
471 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
472 * <i>null</i> will search for those taxa with a value of null in that field
474 * @param clazz optionally filter by class
476 * @param infragenericEpithet
477 * @param specificEpithet
478 * @param infraspecificEpithet
480 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
481 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
482 * @return a List of TaxonBase instances
484 public List
<TaxonBase
> listTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, String authorship
, Rank rank
, Integer pageSize
, Integer pageNumber
);
487 * Returns a list of IdentifiableEntity instances (in particular, TaxonName and TaxonBase instances)
488 * that match the properties specified in the configurator.
489 * @param configurator
492 public Pager
<IdentifiableEntity
> findTaxaAndNames(IFindTaxaAndNamesConfigurator configurator
);
495 * performes a union searches for TaxonBase instances on all available
496 * free text indexes. At the time of writing this documentation it combines
497 * {@link #findByDescriptionElementFullText(Class, String, Classification, List, List, boolean, Integer, Integer, List, List)}
498 * and {@link #findByFullText(Class, String, Classification, List, boolean, Integer, Integer, List, List)
502 * @param classification
503 * Additional filter criterion: If a taxonomic classification
504 * three is specified here the result set will only contain taxa
505 * of the given classification
507 * Additional filter criterion: Search only in these languages.
508 * Not all text fields in the cdm model are multilingual, thus
509 * this setting will only apply to the multilingiual fields.
510 * Other fields are searched nevertheless if this parameter is
512 * @param highlightFragments
515 * The maximum number of objects returned (can be null for all
518 * The offset (in pageSize chunks) from the start of the result
521 * Supports path like <code>orderHints.propertyNames</code> which
522 * include *-to-one properties like createdBy.username or
523 * authorTeam.persistentTitleCache
524 * @param propertyPaths
525 * properties to initialize - see
526 * {@link IBeanInitializer#initialize(Object, List)}
527 * @return a paged list of instances of type T matching the queryString and
528 * the additional filter criteria
530 * @throws LuceneCorruptIndexException
531 * @throws IOException
532 * @throws LuceneParseException
533 * @throws LuceneMultiSearchException
534 * @deprecated this search should fully be covered by the new method
535 * {@link #findTaxaAndNamesByFullText(EnumSet, String, Classification, Set, List, boolean, Integer, Integer, List, List)}
536 * , maybe we should rename this latter method to give it a more meaningful name
539 public Pager
<SearchResult
<TaxonBase
>> findByEverythingFullText(String queryString
,
540 Classification classification
, boolean includeUnpublished
, List
<Language
> languages
, boolean highlightFragments
,
541 Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws IOException
, LuceneParseException
, LuceneMultiSearchException
;
544 * Searches for TaxonBase instances using the TaxonBase free text index.
546 * <h4>This is an experimental feature, it may be moved, modified, or even
547 * removed in future releases!!!</h4>
550 * Additional filter criterion: The specific TaxonBase subclass
554 * @param classification
555 * Additional filter criterion: If a taxonomic classification
556 * three is specified here the result set will only contain taxa
557 * of the given classification
559 * Additional filter criterion: Search only in these languages.
560 * Not all text fields in the cdm model are multilingual, thus
561 * this setting will only apply to the multilingiual fields.
562 * Other fields are searched nevertheless if this parameter is
564 * @param highlightFragments
567 * The maximum number of objects returned (can be null for all
570 * The offset (in pageSize chunks) from the start of the result
573 * Supports path like <code>orderHints.propertyNames</code> which
574 * include *-to-one properties like createdBy.username or
575 * authorTeam.persistentTitleCache
576 * @param propertyPaths
577 * properties to initialize - see
578 * {@link IBeanInitializer#initialize(Object, List)}
579 * @return a paged list of instances of type T matching the queryString and
580 * the additional filter criteria
581 * @throws LuceneCorruptIndexException
582 * @throws IOException
583 * @throws LuceneParseException
585 public Pager
<SearchResult
<TaxonBase
>> findByFullText(Class
<?
extends TaxonBase
> clazz
, String queryString
,
586 Classification classification
, boolean includeUnpublished
, List
<Language
> languages
,
587 boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
588 List
<String
> propertyPaths
) throws IOException
, LuceneParseException
;
593 * @param statusFilter
594 * @param classification
595 * Additional filter criterion: If a taxonomic classification
596 * three is specified here the result set will only contain taxa
597 * of the given classification
598 * @param highlightFragments
600 * The maximum number of objects returned (can be null for all
603 * The offset (in pageSize chunks) from the start of the result
606 * Supports path like <code>orderHints.propertyNames</code> which
607 * include *-to-one properties like createdBy.username or
608 * authorTeam.persistentTitleCache
609 * @param propertyPath
610 * Common properties to initialize the instances of the
611 * CDM types ({@link Taxon} and {@link Synonym}
612 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
613 * @return a paged list of instances of {@link Taxon} instances
614 * @throws IOException
615 * @throws LuceneParseException
617 public Pager
<SearchResult
<TaxonBase
>> findByDistribution(List
<NamedArea
> areaFilter
, List
<PresenceAbsenceTerm
> statusFilter
,
618 Classification classification
,
619 Integer pageSize
, Integer pageNumber
,
620 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws IOException
, LuceneParseException
;
623 * Searches for TaxonBase instances using the TaxonBase free text index.
627 * <h4>This is an experimental feature, it may be moved, modified, or even
628 * removed in future releases!!!</h4>
630 * Additional filter criterion: defaults to [doTaxa] if set null
633 * @param classification
634 * Additional filter criterion: If a taxonomic classification
635 * three is specified here the result set will only contain taxa
636 * of the given classification
639 * Additional filter criterion: Search only in these languages.
640 * Not all text fields in the cdm model are multilingual, thus
641 * this setting will only apply to the multilingiual fields.
642 * Other fields are searched nevertheless if this parameter is
644 * @param highlightFragments
647 * The maximum number of objects returned (can be null for all
650 * The offset (in pageSize chunks) from the start of the result
653 * Supports path like <code>orderHints.propertyNames</code> which
654 * include *-to-one properties like createdBy.username or
655 * authorTeam.persistentTitleCache
656 * @param propertyPath
657 * Common properties to initialize the instances of the
658 * CDM types ({@link Taxon} and {@link Synonym}
659 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
660 * @return a paged list of instances of {@link Taxon}, {@link Synonym}, matching the queryString and
661 * the additional filter criteria
662 * @throws LuceneCorruptIndexException
663 * @throws IOException
664 * @throws LuceneParseException
665 * @throws LuceneMultiSearchException
667 public Pager
<SearchResult
<TaxonBase
>> findTaxaAndNamesByFullText(
668 EnumSet
<TaxaAndNamesSearchMode
> searchModes
,
669 String queryString
, Classification classification
, Set
<NamedArea
> namedAreas
, Set
<PresenceAbsenceTerm
> distributionStatus
,
670 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
671 List
<String
> propertyPaths
) throws IOException
, LuceneParseException
, LuceneMultiSearchException
;
674 * Searches for TaxonBase instances by using the DescriptionElement free text index.
676 * <h4>This is an experimental feature, it may be moved, modified, or even
677 * removed in future releases!!!</h4>
680 * Additional filter criterion:
682 * the query string to filter by
683 * @param classification
684 * Additional filter criterion: If a taxonomic classification
685 * three is specified here the result set will only contain taxa
686 * of the given classification
690 * Additional filter criterion: Search only in these languages.
691 * Not all text fields in the cdm model are multilingual, thus
692 * this setting will only apply to the multilingiual fields.
693 * Other fields are searched nevertheless if this parameter is
695 * @param highlightFragments
698 * The maximum number of objects returned (can be null for all
701 * The offset (in pageSize chunks) from the start of the result
704 * Supports path like <code>orderHints.propertyNames</code> which
705 * include *-to-one properties like createdBy.username or
706 * authorTeam.persistentTitleCache
707 * @param propertyPaths
708 * properties to initialize - see
709 * {@link IBeanInitializer#initialize(Object, List)}
710 * @return a paged list of instances of type T matching the queryString and
711 * the additional filter criteria
712 * @throws IOException
713 * @throws LuceneCorruptIndexException
714 * @throws LuceneParseException
716 public Pager
<SearchResult
<TaxonBase
>> findByDescriptionElementFullText(Class
<?
extends DescriptionElementBase
> clazz
, String queryString
, Classification classification
, List
<Feature
> features
, List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws IOException
, LuceneParseException
;
724 * @param widthOrDuration
728 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
731 public List
<MediaRepresentation
> getAllMedia(Taxon taxon
, int size
, int height
, int widthOrDuration
, String
[] mimeTypes
);
735 * Lists all Media found in an any TaxonDescription associated with this
739 * @param includeRelationships
740 * the given list of TaxonRelationshipEdges will be taken into
741 * account when retrieving media associated with the given taxon.
743 * @param limitToGalleries
744 * whether to take only TaxonDescription into account which are
747 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
750 public List
<Media
> listTaxonDescriptionMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, boolean limitToGalleries
, List
<String
> propertyPath
);
753 * Lists all Media found in an any TaxonDescription, NameDescription,
754 * SpecimenOrObservationBase, DnaSample Chromatograms, etc. associated with this taxon.
757 * @param includeRelationships
758 * the given list of TaxonRelationshipEdges will be taken into
759 * account when retrieving media associated with the given taxon.
761 * @param limitToGalleries
762 * whether to take only descriptions into account which are
763 * marked as gallery, can be NULL
764 * @param includeTaxonDescriptions
765 * whether to take TaxonDescriptions into account, can be NULL
766 * @param includeOccurrences
767 * whether to take TaxonDescriptions into account, can be NULL
768 * @param includeTaxonNameDescriptions
769 * whether to take TaxonNameDescriptions into account, can be NULL
770 * @param propertyPath
773 public List
<Media
> listMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
,
774 Boolean limitToGalleries
, Boolean includeTaxonDescriptions
, Boolean includeOccurrences
,
775 Boolean includeTaxonNameDescriptions
, List
<String
> propertyPath
);
777 public List
<TaxonBase
> findTaxaByID(Set
<Integer
> listOfIDs
);
780 * Returns the TaxonBase with the given UUID
781 * using the given match mode and initialization strategy
784 * @param propertyPaths
787 public TaxonBase
findTaxonByUuid(UUID uuid
, List
<String
> propertyPaths
);
790 * Counts the number of synonyms
791 * @param onlyAttachedToTaxon if <code>true</code> only those synonyms being attached to
792 * an accepted taxon are counted
793 * @return the number of synonyms
795 public int countSynonyms(boolean onlyAttachedToTaxon
);
797 public List
<TaxonName
> findIdenticalTaxonNames(List
<String
> propertyPath
);
799 public List
<TaxonName
> findIdenticalTaxonNameIds(List
<String
> propertyPath
);
801 // public String getPhylumName(TaxonName name);
804 * Returns all {@link Taxon taxa} which are {@link TaxonRelationshipType#CONGRUENT_TO() congruent} or
805 * {@link TaxonRelationshipType#INCLUDES() included} in the taxon represented by the given taxon uuid.
806 * The result also returns the path to these taxa represented by the uuids of
807 * the {@link TaxonRelationshipType taxon relationships types} and doubtful information.
808 * If classificationUuids is set only taxa of classifications are returned which are included
809 * in the given {@link Classification classifications}. ALso the path to these taxa may not include
810 * taxa from other classifications.
811 * @param taxonUuid uuid of the original taxon
812 * @param classificationUuids List of uuids of classifications used as a filter
813 * @param includeDoubtful set to <code>true</code> if also doubtfully included taxa should be included in the result
814 * @return a DTO which includes a list of taxa with the pathes from the original taxon to the given taxon as well
815 * as doubtful and date information. The original taxon is included in the result.
817 public IncludedTaxaDTO
listIncludedTaxa(UUID taxonUuid
, IncludedTaxonConfiguration configuration
);
821 * Removes a synonym.<BR><BR>
823 * In detail it removes
824 * <li>the synonym concept</li>
826 * If <code>removeNameIfPossible</code> is true
827 * it also removes the synonym name if it is not used in any other context
828 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
829 * If <code>newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name
830 * is not deleted and the name is homotypic to the taxon
831 * the name is moved to a new homotypic group.<BR><BR>
833 * If synonym is <code>null</code> the method has no effect.
837 * @param removeNameIfPossible
838 * @return deleteResult
841 public DeleteResult
deleteSynonym(Synonym synonym
, SynonymDeletionConfigurator config
);
846 * The method essentially loads the synonym and calls the
847 * {@link #deleteSynonym(Synonym, SynonymDeletionConfigurator) deleteSynonym} method
853 public DeleteResult
deleteSynonym(UUID synonymUuid
, SynonymDeletionConfigurator config
);
859 public Taxon
findBestMatchingTaxon(String taxonName
);
861 public Taxon
findBestMatchingTaxon(MatchingTaxonConfigurator config
);
863 public Synonym
findBestMatchingSynonym(String taxonName
, boolean includeUnpublished
);
865 public List
<UuidAndTitleCache
<IdentifiableEntity
>> findTaxaAndNamesForEditor(IFindTaxaAndNamesConfigurator configurator
);
868 * Creates the specified inferred synonyms for the taxon in the classification, but do not insert it to the database
871 * @return list of inferred synonyms
873 public List
<Synonym
> createInferredSynonyms(Taxon taxon
, Classification tree
, SynonymType type
, boolean doWithMisappliedNames
);
876 * Creates all inferred synonyms for the taxon in the classification, but do not insert it to the database
880 * @return list of inferred synonyms
882 public List
<Synonym
> createAllInferredSynonyms(Taxon taxon
, Classification tree
, boolean doWithMisappliedNames
);
884 public Taxon
findAcceptedTaxonFor(UUID synonymUuid
, UUID classificationUuid
, List
<String
> propertyPaths
);
886 public List
<TaxonBase
> findTaxaByName(MatchingTaxonConfigurator config
);
890 * @param clazz the optional {@link TaxonBase} subclass
891 * @param identifier the identifier string
892 * @param identifierType the identifier type
893 * @param subtreeFilter filter on a classification subtree (TaxonNode)
894 * @param matchmode the match mode for the identifier string
895 * @param includeEntity should the taxon as an object be included in the result
896 * @param pageSize page size
897 * @param pageNumber page number
898 * @param propertyPaths property path for initializing the returned taxon object (requires includeEntity=true)
899 * @return the resulting {@link IdentifiedEntityDTO} pager
900 * @see IIdentifiableEntityService#findByIdentifier(Class, String, DefinedTerm, MatchMode, boolean, Integer, Integer, List)
902 public <S
extends TaxonBase
> Pager
<IdentifiedEntityDTO
<S
>> findByIdentifier(
903 Class
<S
> clazz
, String identifier
, DefinedTerm identifierType
, TaxonNode subtreeFilter
,
904 MatchMode matchmode
, boolean includeEntity
, Integer pageSize
,
905 Integer pageNumber
, List
<String
> propertyPaths
);
908 * Returns a pager for {@link MarkedEntityDTO DTOs} that hold the marker including type, title and uuid
909 * and the according {@link TaxonBase} information (uuid, title and the taxon object itself (optional)).
911 * @param clazz The optional {@link TaxonBase} subclass
912 * @param markerType the obligatory marker type, if not given, the results will always be empty
913 * @param markerValue the optional
914 * @param subtreeFilter filter on a classification subtree (TaxonNode)
915 * @param includeEntity should the taxon as an object be included in the result
916 * @param titleType which label to give the returned entity, taxon.titleCache, name.titleCache or name.nameCache
917 * @param pageSize page size
918 * @param pageNumber page number
919 * @param propertyPaths property path for initializing the returned taxon object (requires includeEntity=true)
920 * @return the resulting {@link MarkedEntityDTO} pager
921 * @see IIdentifiableEntityService#findByMarker(Class, MarkerType, Boolean, boolean, Integer, Integer, List)
923 public <S
extends TaxonBase
> Pager
<MarkedEntityDTO
<S
>> findByMarker(
924 Class
<S
> clazz
, MarkerType markerType
, Boolean markerValue
,
925 TaxonNode subtreeFilter
, boolean includeEntity
, TaxonTitleType titleType
,
926 Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
930 * @param acceptedTaxonUuid
933 public UpdateResult
swapSynonymAndAcceptedTaxon(UUID synonymUUid
, UUID acceptedTaxonUuid
);
938 * @param classificationUuid
941 public DeleteResult
deleteTaxon(UUID taxonUuid
, TaxonDeletionConfigurator config
, UUID classificationUuid
);
944 public UpdateResult
moveFactualDateToAnotherTaxon(UUID fromTaxonUuid
,
951 * @param taxonRelationshipType
953 * @param microcitation
956 public UpdateResult
changeSynonymToRelatedTaxon(UUID synonymUuid
, UUID toTaxonUuid
, TaxonRelationshipType taxonRelationshipType
,
957 Reference citation
, String microcitation
);
960 * @param fromTaxonUuid
962 * @param oldRelationshipType
965 * @throws DataChangeNoRollbackException
967 public UpdateResult
changeRelatedTaxonToSynonym(UUID fromTaxonUuid
, UUID toTaxonUuid
,
968 TaxonRelationshipType oldRelationshipType
, SynonymType synonymType
) throws DataChangeNoRollbackException
;