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
.io
.IOException
;
14 import java
.util
.EnumSet
;
15 import java
.util
.List
;
17 import java
.util
.UUID
;
19 import org
.apache
.lucene
.index
.CorruptIndexException
;
20 import org
.apache
.lucene
.queryparser
.classic
.ParseException
;
22 import eu
.etaxonomy
.cdm
.api
.service
.config
.IFindTaxaAndNamesConfigurator
;
23 import eu
.etaxonomy
.cdm
.api
.service
.config
.IncludedTaxonConfiguration
;
24 import eu
.etaxonomy
.cdm
.api
.service
.config
.MatchingTaxonConfigurator
;
25 import eu
.etaxonomy
.cdm
.api
.service
.config
.SynonymDeletionConfigurator
;
26 import eu
.etaxonomy
.cdm
.api
.service
.config
.TaxonDeletionConfigurator
;
27 import eu
.etaxonomy
.cdm
.api
.service
.dto
.IdentifiedEntityDTO
;
28 import eu
.etaxonomy
.cdm
.api
.service
.dto
.IncludedTaxaDTO
;
29 import eu
.etaxonomy
.cdm
.api
.service
.dto
.MarkedEntityDTO
;
30 import eu
.etaxonomy
.cdm
.api
.service
.exception
.DataChangeNoRollbackException
;
31 import eu
.etaxonomy
.cdm
.api
.service
.exception
.HomotypicalGroupChangeException
;
32 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
33 import eu
.etaxonomy
.cdm
.api
.service
.search
.LuceneMultiSearchException
;
34 import eu
.etaxonomy
.cdm
.api
.service
.search
.SearchResult
;
35 import eu
.etaxonomy
.cdm
.api
.service
.util
.TaxonRelationshipEdge
;
36 import eu
.etaxonomy
.cdm
.model
.common
.DefinedTerm
;
37 import eu
.etaxonomy
.cdm
.model
.common
.IdentifiableEntity
;
38 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
39 import eu
.etaxonomy
.cdm
.model
.common
.MarkerType
;
40 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionElementBase
;
41 import eu
.etaxonomy
.cdm
.model
.description
.Feature
;
42 import eu
.etaxonomy
.cdm
.model
.description
.PresenceAbsenceTerm
;
43 import eu
.etaxonomy
.cdm
.model
.location
.NamedArea
;
44 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
45 import eu
.etaxonomy
.cdm
.model
.media
.MediaRepresentation
;
46 import eu
.etaxonomy
.cdm
.model
.name
.HomotypicalGroup
;
47 import eu
.etaxonomy
.cdm
.model
.name
.Rank
;
48 import eu
.etaxonomy
.cdm
.model
.name
.TaxonNameBase
;
49 import eu
.etaxonomy
.cdm
.model
.reference
.Reference
;
50 import eu
.etaxonomy
.cdm
.model
.taxon
.Classification
;
51 import eu
.etaxonomy
.cdm
.model
.taxon
.Synonym
;
52 import eu
.etaxonomy
.cdm
.model
.taxon
.SynonymType
;
53 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
54 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonBase
;
55 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonNode
;
56 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationship
;
57 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationshipType
;
58 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
59 import eu
.etaxonomy
.cdm
.persistence
.dto
.UuidAndTitleCache
;
60 import eu
.etaxonomy
.cdm
.persistence
.query
.MatchMode
;
61 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
64 public interface ITaxonService
extends IIdentifiableEntityService
<TaxonBase
>{
67 * Returns a list of taxa that matches the name string and the sec reference
68 * @param name the name string to search for
69 * @param sec the taxons sec reference
70 * @return a list of taxa matching the name and the sec reference
72 public List
<TaxonBase
> searchTaxaByName(String name
, Reference sec
);
75 * Swaps given synonym and accepted taxon.
78 * <li>A new accepted taxon with the synonyms name is created</li>
79 * <li>The synonym is deleted from the old accepted taxons synonym list</li>
80 * <li>A new synonym with the name of the old accepted taxon is created</li>
81 * <li>The newly created synonym get related to the newly created accepted taxon</li>
85 * @param acceptedTaxon
88 public UpdateResult
swapSynonymAndAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
);
91 * Changes a synonym into an accepted taxon and removes
92 * the synonym relationship to the given accepted taxon.
93 * Other synonyms homotypic to the synonym to change are
94 * moved to the same new accepted taxon as homotypic
95 * synonyms. The new accepted taxon has the same name and
96 * the same sec reference as the old synonym.<BR>
97 * If the given accepted taxon and the synonym are homotypic
98 * to each other an exception may be thrown as taxonomically it doesn't
99 * make sense to have two accepted taxa in the same homotypic group
100 * but also it is than difficult to decide how to handle other names
101 * in the homotypic group. It is up to the implementing class to
102 * handle this situation via an exception or in another way.
106 * the synonym to change into an accepted taxon
107 * @param acceptedTaxon
108 * an accepted taxon, the synonym had a relationship to
109 * @param deleteSynonym
110 * if true the method tries to delete the old synonym from the database
112 * the newly created accepted taxon
113 * @throws IllegalArgumentException
114 * if the given accepted taxon and the synonym are homotypic
115 * to each other an exception may be thrown as taxonomically it doesn't
116 * make sense to have two accepted taxa in the same homotypic group
117 * but also it is than difficult to decide how to handle other names
118 * in the homotypic group. It is up to the implementing class to
119 * handle this situation via an exception or in another way.
121 public Taxon
changeSynonymToAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
, boolean deleteSynonym
) throws HomotypicalGroupChangeException
;
125 * @param acceptedTaxonUuid
126 * @param newParentNodeUuid
127 * @param deleteSynonym
129 * @throws HomotypicalGroupChangeException
131 public UpdateResult
changeSynonymToAcceptedTaxon(UUID synonymUuid
, UUID acceptedTaxonUuid
, UUID newParentNodeUuid
,
132 boolean deleteSynonym
)
133 throws HomotypicalGroupChangeException
;
136 * TODO still needed and correct?
137 * Change a synonym into a related concept
140 * the synonym to change into the concept taxon
142 * the taxon the newly created concept should be related to
143 * @param taxonRelationshipType
144 * the type of relationship
146 * @param microReference
148 * the newly created concept
150 public Taxon
changeSynonymToRelatedTaxon(Synonym synonym
, Taxon toTaxon
, TaxonRelationshipType taxonRelationshipType
, Reference reference
, String microReference
);
153 * TODO still needed and correct?
154 * Change a synonym into a related concept
157 * the synonym to change into the concept taxon
159 * the taxon the newly created concept should be related to
160 * @param taxonRelationshipType
161 * the type of relationship
163 * @param microReference
165 * the newly created concept
166 * @throws DataChangeNoRollbackException
168 public Synonym
changeRelatedTaxonToSynonym(Taxon fromTaxon
, Taxon toTaxon
,
169 TaxonRelationshipType oldRelationshipType
,
170 SynonymType synonymType
) throws DataChangeNoRollbackException
;
173 * Changes the homotypic group of a synonym into the new homotypic group.
174 * All relations to taxa are updated correctly depending on the homotypic
175 * group of the accepted taxon. <BR>
176 * All existing basionym relationships to and from this name are removed.<BR>
177 * If the parameter <code>targetTaxon</code> is defined, the synonym is
178 * added to this taxon irrespctive of if it has been related to this
180 * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
181 * between the existing basionym(s) of the new homotypic group and the synonyms name
185 * @param newHomotypicalGroup
187 * @param setBasionymRelationIfApplicable
189 public void changeHomotypicalGroupOfSynonym(Synonym synonym
, HomotypicalGroup newHomotypicalGroup
,
190 Taxon targetTaxon
, boolean setBasionymRelationIfApplicable
);
193 * See {@link #moveSynonymToAnotherTaxon(Synonym, Taxon, boolean, SynonymType, Reference, String, boolean)}
196 * @param moveHomotypicGroup
197 * @param newSynonymType
199 * @throws HomotypicalGroupChangeException
201 public UpdateResult
moveSynonymToAnotherTaxon(Synonym oldSynonym
, Taxon newTaxon
, boolean moveHomotypicGroup
,
202 SynonymType newSynonymType
) throws HomotypicalGroupChangeException
;
206 * Moves a synonym to another taxon and removes the old synonym relationship.
208 * @param oldSynonym the old synonym to move.
209 * @param newTaxon the taxon the synonym will be moved to
210 * @param moveHomotypicGroup if the synonym belongs to a homotypic group with other synonyms and
211 * <code>moveHomotypicGroup</code> is <code>true</code> all these synonyms are moved to the new taxon,
212 * if <code>false</code> a {@link HomotypicalGroupChangeException} is thrown.
213 * <code>moveHomotypicGroup</code> has no effect if the synonym is the only synonym in it's homotypic group.
214 * @param newSynonymType the synonym type of the new synonyms. Default is
215 * {@link SynonymType#HETEROTYPIC_SYNONYM_OF() heterotypic}.
216 * @param newSecundum The secundum for the new synonyms).
217 * @param newSecundumDetail The secundum micro reference for the new synonym(s).
218 * @param keepSecundumIfUndefined if no <code>newSecundum</code> and/or no <code>newSecundumDetail</code>
219 * is defined they are taken from the old synonym(s) if <code>keepSecundumIfUndefined</code> is
220 * <code>true</code>. If <code>false</code> the secundum and the secundum detail will be taken
221 * only from the <code>newSecundum</code> and <code>newSecundumDetail</code> even if they are
222 * undefined (<code>null</code>).
223 * @return The new synonym relationship. If <code>moveHomotypicGroup</code> is <code>true</code> additionally
224 * created new synonym relationships must be retrieved separately from the new taxon.
225 * @throws HomotypicalGroupChangeException Exception is thrown if (1) synonym is homotypic to the old accepted taxon or
226 * (2) synonym is in homotypic group with other synonyms and <code>moveHomotypicGroup</code> is false
228 public UpdateResult
moveSynonymToAnotherTaxon(Synonym oldSynonym
, Taxon newTaxon
, boolean moveHomotypicGroup
,
229 SynonymType newSynonymType
, Reference newSecundum
,
230 String newSecundumDetail
, boolean keepSecundumIfUndefined
) throws HomotypicalGroupChangeException
;
235 * @param newTaxonUUID
236 * @param moveHomotypicGroup
237 * @param newSynonymType
239 * @param referenceDetail
240 * @param keepReference
242 * @throws HomotypicalGroupChangeException
244 * @see {@link #moveSynonymToAnotherTaxon(Synonym, Taxon, boolean, SynonymType, Reference, String, boolean)}
246 public UpdateResult
moveSynonymToAnotherTaxon(Synonym oldSynonym
,
247 UUID newTaxonUUID
, boolean moveHomotypicGroup
,
248 SynonymType newSynonymType
,
249 Reference newSecundum
, String newSecundumDetail
, boolean keepSecundumIfUndefined
)
250 throws HomotypicalGroupChangeException
;
253 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
254 * where the supplied taxon is relatedTo.
256 * @param taxon The taxon that is relatedTo
257 * @param type The type of TaxonRelationship (can be null)
258 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
259 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
260 * @param orderHints Properties to order by
261 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
262 * @return a List of TaxonRelationship instances
264 public List
<TaxonRelationship
> listToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
269 * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
270 * where the supplied taxon is relatedTo.
272 * @param taxon The taxon that is relatedTo
273 * @param type The type of TaxonRelationship (can be null)
274 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
275 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
276 * @param orderHints Properties to order by
277 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
278 * @return a Pager of TaxonRelationship instances
280 public Pager
<TaxonRelationship
> pageToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
283 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
284 * where the supplied taxon is relatedFrom.
286 * @param taxon The taxon that is relatedFrom
287 * @param type The type of TaxonRelationship (can be null)
288 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
289 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
290 * @param orderHints Properties to order by
291 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
292 * @return a List of TaxonRelationship instances
294 public List
<TaxonRelationship
> listFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
298 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
299 * where the supplied taxon is relatedFrom.
301 * @param taxon The taxon that is relatedFrom
302 * @param type The type of TaxonRelationship (can be null)
303 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
304 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
305 * @param orderHints Properties to order by
306 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
307 * @return a Pager of TaxonRelationship instances
309 public Pager
<TaxonRelationship
> pageFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
312 * lists all taxa which are related to the <code>taxon</code> given as
316 * @param includeRelationships
318 * <code>1</code> for one level, <code>null</code> for infinite
319 * depth, <code>0</code> will completely omit collecting related taxa.
322 * @param propertyPaths
325 public Set
<Taxon
> listRelatedTaxa(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, Integer maxDepth
,
326 Integer limit
, Integer start
, List
<String
> propertyPaths
);
329 * Lists all classifications the given taxon/synonym is used in{@link Synonym}
334 * @param propertyPaths
337 public List
<Classification
> listClassifications(TaxonBase taxonBase
, Integer limit
, Integer start
, List
<String
> propertyPaths
);
340 * Returns the Synonyms (with the given synonym relationship type, if this argument is supplied)
341 * that do have the supplied taxon as accepted taxon.
343 * @param taxon The accepted taxon
344 * @param type The type of Synonym (can be null)
345 * @param pageSize The maximum number of synonyms returned (can be null for returning synonyms)
346 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
347 * * @param orderHints Properties to order by
348 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
349 * @return a Pager of {@link Synonym} instances
351 public Pager
<Synonym
> getSynonyms(Taxon taxon
, SynonymType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
354 * This method returns in the first entry the list of synonyms of the
355 * homotypic group of the accepted taxon. All other entries represent the lists of heterotypic
356 * synonym groups. For detailed information about these 2 groups see
357 * {@link #getHomotypicSynonymsByHomotypicGroup(Taxon, List)} and
358 * {@link #getHeterotypicSynonymyGroups(Taxon, List)}
360 * @see #getSynonyms()
361 * @see SynonymType#HETEROTYPIC_SYNONYM_OF()
362 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
364 * @param taxon the accepted taxon
365 * @param propertyPaths the property path
366 * @return the list of groups of synonyms
368 public List
<List
<Synonym
>> getSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
372 * Returns the list of all synonyms that share the same homotypical group with the given taxon.
373 * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
375 * @param propertyPaths
378 public List
<Synonym
> getHomotypicSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
381 * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
382 * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
383 * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
384 * belong to a homotypical group which cannot be the homotypical group to which the
385 * taxon name of the given taxon belongs. This method does not return the homotypic group the given
386 * taxon belongs to.<BR>
387 * This method does neglect the type of synonym relationship that is defined between the given taxon
388 * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
389 * in one of the result lists as long as the synonym does not belong to the same homotypic group as
390 * the given taxon.<BR>
391 * The list returned is ordered according to the date of publication of the
392 * first published name within each homotypical group.
394 * @see #getHeterotypicSynonymyGroups()
395 * @see #getSynonyms()
396 * @see SynonymType#HETEROTYPIC_SYNONYM_OF()
397 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
400 * @param propertyPaths
403 public List
<List
<Synonym
>> getHeterotypicSynonymyGroups(Taxon taxon
, List
<String
> propertyPaths
);
406 * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
408 * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
410 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
411 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
413 * Supports path like <code>orderHints.propertyNames</code> which
414 * include *-to-one properties like createdBy.username or
415 * authorTeam.persistentTitleCache
416 * @param propertyPaths properties to be initialized
417 * @return a Pager Taxon instances
418 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
421 public Pager
<TaxonBase
> search(Class
<?
extends TaxonBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
424 * Returns a list of TaxonBase instances where the
425 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
426 * <i>null</i> will search for those taxa with a value of null in that field
428 * @param clazz optionally filter by class (can be null to return all taxa)
430 * @param infragenericEpithet
431 * @param specificEpithet
432 * @param infraspecificEpithet
434 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
435 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
436 * @return a list of TaxonBase instances
438 public Pager
<TaxonBase
> findTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, String authorship
, Rank rank
, Integer pageSize
, Integer pageNumber
);
441 * Returns a list of TaxonBase instances where the
442 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
443 * <i>null</i> will search for those taxa with a value of null in that field
445 * @param clazz optionally filter by class
447 * @param infragenericEpithet
448 * @param specificEpithet
449 * @param infraspecificEpithet
451 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
452 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
453 * @return a List of TaxonBase instances
455 public List
<TaxonBase
> listTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, String authorship
, Rank rank
, Integer pageSize
, Integer pageNumber
);
458 * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
459 * that match the properties specified in the configurator.
460 * @param configurator
463 public Pager
<IdentifiableEntity
> findTaxaAndNames(IFindTaxaAndNamesConfigurator configurator
);
466 * performes a union searches for TaxonBase instances on all available
467 * free text indexes. At the time of writing this documentation it combines
468 * {@link #findByDescriptionElementFullText(Class, String, Classification, List, List, boolean, Integer, Integer, List, List)}
469 * and {@link #findByFullText(Class, String, Classification, List, boolean, Integer, Integer, List, List)
473 * @param classification
474 * Additional filter criterion: If a taxonomic classification
475 * three is specified here the result set will only contain taxa
476 * of the given classification
478 * Additional filter criterion: Search only in these languages.
479 * Not all text fields in the cdm model are multilingual, thus
480 * this setting will only apply to the multilingiual fields.
481 * Other fields are searched nevertheless if this parameter is
483 * @param highlightFragments
486 * The maximum number of objects returned (can be null for all
489 * The offset (in pageSize chunks) from the start of the result
492 * Supports path like <code>orderHints.propertyNames</code> which
493 * include *-to-one properties like createdBy.username or
494 * authorTeam.persistentTitleCache
495 * @param propertyPaths
496 * properties to initialize - see
497 * {@link IBeanInitializer#initialize(Object, List)}
498 * @return a paged list of instances of type T matching the queryString and
499 * the additional filter criteria
501 * @throws CorruptIndexException
502 * @throws IOException
503 * @throws ParseException
504 * @throws LuceneMultiSearchException
505 * @deprecated this search should fully be covered by the new method
506 * {@link #findTaxaAndNamesByFullText(EnumSet, String, Classification, Set, List, boolean, Integer, Integer, List, List)}
507 * , maybe we should rename this latter method to give it a more meaningful name
510 public Pager
<SearchResult
<TaxonBase
>> findByEverythingFullText(String queryString
,
511 Classification classification
, List
<Language
> languages
, boolean highlightFragments
,
512 Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
, LuceneMultiSearchException
;
515 * Searches for TaxonBase instances using the TaxonBase free text index.
517 * <h4>This is an experimental feature, it may be moved, modified, or even
518 * removed in future releases!!!</h4>
521 * Additional filter criterion: The specific TaxonBase subclass
525 * @param classification
526 * Additional filter criterion: If a taxonomic classification
527 * three is specified here the result set will only contain taxa
528 * of the given classification
530 * Additional filter criterion: Search only in these languages.
531 * Not all text fields in the cdm model are multilingual, thus
532 * this setting will only apply to the multilingiual fields.
533 * Other fields are searched nevertheless if this parameter is
535 * @param highlightFragments
538 * The maximum number of objects returned (can be null for all
541 * The offset (in pageSize chunks) from the start of the result
544 * Supports path like <code>orderHints.propertyNames</code> which
545 * include *-to-one properties like createdBy.username or
546 * authorTeam.persistentTitleCache
547 * @param propertyPaths
548 * properties to initialize - see
549 * {@link IBeanInitializer#initialize(Object, List)}
550 * @return a paged list of instances of type T matching the queryString and
551 * the additional filter criteria
552 * @throws CorruptIndexException
553 * @throws IOException
554 * @throws ParseException
556 public Pager
<SearchResult
<TaxonBase
>> findByFullText(Class
<?
extends TaxonBase
> clazz
, String queryString
, Classification classification
,
557 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
558 List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
;
563 * @param statusFilter
564 * @param classification
565 * Additional filter criterion: If a taxonomic classification
566 * three is specified here the result set will only contain taxa
567 * of the given classification
568 * @param highlightFragments
570 * The maximum number of objects returned (can be null for all
573 * The offset (in pageSize chunks) from the start of the result
576 * Supports path like <code>orderHints.propertyNames</code> which
577 * include *-to-one properties like createdBy.username or
578 * authorTeam.persistentTitleCache
579 * @param propertyPath
580 * Common properties to initialize the instances of the
581 * CDM types ({@link Taxon} and {@link Synonym}
582 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
583 * @return a paged list of instances of {@link Taxon} instances
584 * @throws IOException
585 * @throws ParseException
587 public Pager
<SearchResult
<TaxonBase
>> findByDistribution(List
<NamedArea
> areaFilter
, List
<PresenceAbsenceTerm
> statusFilter
,
588 Classification classification
,
589 Integer pageSize
, Integer pageNumber
,
590 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws IOException
, ParseException
;
593 * Searches for TaxonBase instances using the TaxonBase free text index.
597 * <h4>This is an experimental feature, it may be moved, modified, or even
598 * removed in future releases!!!</h4>
600 * Additional filter criterion: defaults to [doTaxa] if set null
603 * @param classification
604 * Additional filter criterion: If a taxonomic classification
605 * three is specified here the result set will only contain taxa
606 * of the given classification
609 * Additional filter criterion: Search only in these languages.
610 * Not all text fields in the cdm model are multilingual, thus
611 * this setting will only apply to the multilingiual fields.
612 * Other fields are searched nevertheless if this parameter is
614 * @param highlightFragments
617 * The maximum number of objects returned (can be null for all
620 * The offset (in pageSize chunks) from the start of the result
623 * Supports path like <code>orderHints.propertyNames</code> which
624 * include *-to-one properties like createdBy.username or
625 * authorTeam.persistentTitleCache
626 * @param propertyPath
627 * Common properties to initialize the instances of the
628 * CDM types ({@link Taxon} and {@link Synonym}
629 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
630 * @return a paged list of instances of {@link Taxon}, {@link Synonym}, matching the queryString and
631 * the additional filter criteria
632 * @throws CorruptIndexException
633 * @throws IOException
634 * @throws ParseException
635 * @throws LuceneMultiSearchException
637 public Pager
<SearchResult
<TaxonBase
>> findTaxaAndNamesByFullText(
638 EnumSet
<TaxaAndNamesSearchMode
> searchModes
,
639 String queryString
, Classification classification
, Set
<NamedArea
> namedAreas
, Set
<PresenceAbsenceTerm
> distributionStatus
,
640 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
641 List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
, LuceneMultiSearchException
;
644 * Searches for TaxonBase instances by using the DescriptionElement free text index.
646 * <h4>This is an experimental feature, it may be moved, modified, or even
647 * removed in future releases!!!</h4>
650 * Additional filter criterion:
652 * the query string to filter by
653 * @param classification
654 * Additional filter criterion: If a taxonomic classification
655 * three is specified here the result set will only contain taxa
656 * of the given classification
660 * Additional filter criterion: Search only in these languages.
661 * Not all text fields in the cdm model are multilingual, thus
662 * this setting will only apply to the multilingiual fields.
663 * Other fields are searched nevertheless if this parameter is
665 * @param highlightFragments
668 * The maximum number of objects returned (can be null for all
671 * The offset (in pageSize chunks) from the start of the result
674 * Supports path like <code>orderHints.propertyNames</code> which
675 * include *-to-one properties like createdBy.username or
676 * authorTeam.persistentTitleCache
677 * @param propertyPaths
678 * properties to initialize - see
679 * {@link IBeanInitializer#initialize(Object, List)}
680 * @return a paged list of instances of type T matching the queryString and
681 * the additional filter criteria
682 * @throws IOException
683 * @throws CorruptIndexException
684 * @throws ParseException
686 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 CorruptIndexException
, IOException
, ParseException
;
694 * @param widthOrDuration
698 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
701 public List
<MediaRepresentation
> getAllMedia(Taxon taxon
, int size
, int height
, int widthOrDuration
, String
[] mimeTypes
);
705 * Lists all Media found in an any TaxonDescription associated with this
709 * @param includeRelationships
710 * the given list of TaxonRelationshipEdges will be taken into
711 * account when retrieving media associated with the given taxon.
713 * @param limitToGalleries
714 * whether to take only TaxonDescription into account which are
717 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
720 public List
<Media
> listTaxonDescriptionMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, boolean limitToGalleries
, List
<String
> propertyPath
);
723 * Lists all Media found in an any TaxonDescription, NameDescription,
724 * SpecimenOrObservationBase, DnaSample Chromatograms, etc. associated with this taxon.
727 * @param includeRelationships
728 * the given list of TaxonRelationshipEdges will be taken into
729 * account when retrieving media associated with the given taxon.
731 * @param limitToGalleries
732 * whether to take only descriptions into account which are
733 * marked as gallery, can be NULL
734 * @param includeTaxonDescriptions
735 * whether to take TaxonDescriptions into account, can be NULL
736 * @param includeOccurrences
737 * whether to take TaxonDescriptions into account, can be NULL
738 * @param includeTaxonNameDescriptions
739 * whether to take TaxonNameDescriptions into account, can be NULL
740 * @param propertyPath
743 public List
<Media
> listMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
,
744 Boolean limitToGalleries
, Boolean includeTaxonDescriptions
, Boolean includeOccurrences
,
745 Boolean includeTaxonNameDescriptions
, List
<String
> propertyPath
);
747 public List
<TaxonBase
> findTaxaByID(Set
<Integer
> listOfIDs
);
750 * Returns the TaxonBase with the given UUID
751 * using the given match mode and initialization strategy
754 * @param propertyPaths
757 public TaxonBase
findTaxonByUuid(UUID uuid
, List
<String
> propertyPaths
);
760 * Counts the number of synonyms
761 * @param onlyAttachedToTaxon if <code>true</code> only those synonyms being attached to
762 * an accepted taxon are counted
763 * @return the number of synonyms
765 public int countSynonyms(boolean onlyAttachedToTaxon
);
767 public List
<TaxonNameBase
> findIdenticalTaxonNames(List
<String
> propertyPath
);
769 public List
<TaxonNameBase
> findIdenticalTaxonNameIds(List
<String
> propertyPath
);
771 // public String getPhylumName(TaxonNameBase name);
774 * Returns all {@link Taxon taxa} which are {@link TaxonRelationshipType#CONGRUENT_TO() congruent} or
775 * {@link TaxonRelationshipType#INCLUDES() included} in the taxon represented by the given taxon uuid.
776 * The result also returns the path to these taxa represented by the uuids of
777 * the {@link TaxonRelationshipType taxon relationships types} and doubtful information.
778 * If classificationUuids is set only taxa of classifications are returned which are included
779 * in the given {@link Classification classifications}. ALso the path to these taxa may not include
780 * taxa from other classifications.
781 * @param taxonUuid uuid of the original taxon
782 * @param classificationUuids List of uuids of classifications used as a filter
783 * @param includeDoubtful set to <code>true</code> if also doubtfully included taxa should be included in the result
784 * @return a DTO which includes a list of taxa with the pathes from the original taxon to the given taxon as well
785 * as doubtful and date information. The original taxon is included in the result.
787 public IncludedTaxaDTO
listIncludedTaxa(UUID taxonUuid
, IncludedTaxonConfiguration configuration
);
791 * Removes a synonym.<BR><BR>
793 * In detail it removes
794 * <li>the synonym concept</li>
796 * If <code>removeNameIfPossible</code> is true
797 * it also removes the synonym name if it is not used in any other context
798 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
799 * If <code>newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name
800 * is not deleted and the name is homotypic to the taxon
801 * the name is moved to a new homotypic group.<BR><BR>
803 * If synonym is <code>null</code> the method has no effect.
807 * @param removeNameIfPossible
808 * @return deleteResult
811 public DeleteResult
deleteSynonym(Synonym synonym
, SynonymDeletionConfigurator config
);
816 * The method essentially loads the synonym and calls the
817 * {@link #deleteSynonym(Synonym, SynonymDeletionConfigurator) deleteSynonym} method
823 public DeleteResult
deleteSynonym(UUID synonymUuid
, SynonymDeletionConfigurator config
);
829 public Taxon
findBestMatchingTaxon(String taxonName
);
831 public Taxon
findBestMatchingTaxon(MatchingTaxonConfigurator config
);
833 public Synonym
findBestMatchingSynonym(String taxonName
);
835 public List
<UuidAndTitleCache
<IdentifiableEntity
>> findTaxaAndNamesForEditor(IFindTaxaAndNamesConfigurator configurator
);
838 * Creates the specified inferred synonyms for the taxon in the classification, but do not insert it to the database
841 * @return list of inferred synonyms
843 public List
<Synonym
> createInferredSynonyms(Taxon taxon
, Classification tree
, SynonymType type
, boolean doWithMisappliedNames
);
846 * Creates all inferred synonyms for the taxon in the classification, but do not insert it to the database
850 * @return list of inferred synonyms
852 public List
<Synonym
> createAllInferredSynonyms(Taxon taxon
, Classification tree
, boolean doWithMisappliedNames
);
854 public Taxon
findAcceptedTaxonFor(UUID synonymUuid
, UUID classificationUuid
, List
<String
> propertyPaths
);
856 public List
<TaxonBase
> findTaxaByName(MatchingTaxonConfigurator config
);
860 * @param clazz the optional {@link TaxonBase} subclass
861 * @param identifier the identifier string
862 * @param identifierType the identifier type
863 * @param subtreeFilter filter on a classification subtree (TaxonNode)
864 * @param matchmode the match mode for the identifier string
865 * @param includeEntity should the taxon as an object be included in the result
866 * @param pageSize page size
867 * @param pageNumber page number
868 * @param propertyPaths property path for initializing the returned taxon object (requires includeEntity=true)
869 * @return the resulting {@link IdentifiedEntityDTO} pager
870 * @see IIdentifiableEntityService#findByIdentifier(Class, String, DefinedTerm, MatchMode, boolean, Integer, Integer, List)
872 public <S
extends TaxonBase
> Pager
<IdentifiedEntityDTO
<S
>> findByIdentifier(
873 Class
<S
> clazz
, String identifier
, DefinedTerm identifierType
, TaxonNode subtreeFilter
,
874 MatchMode matchmode
, boolean includeEntity
, Integer pageSize
,
875 Integer pageNumber
, List
<String
> propertyPaths
);
878 * Returns a pager for {@link MarkedEntityDTO DTOs} that hold the marker including type, title and uuid
879 * and the according {@link TaxonBase} information (uuid, title and the taxon object itself (optional)).
881 * @param clazz The optional {@link TaxonBase} subclass
882 * @param markerType the obligatory marker type, if not given, the results will always be empty
883 * @param markerValue the optional
884 * @param subtreeFilter filter on a classification subtree (TaxonNode)
885 * @param includeEntity should the taxon as an object be included in the result
886 * @param pageSize page size
887 * @param pageNumber page number
888 * @param propertyPaths property path for initializing the returned taxon object (requires includeEntity=true)
889 * @return the resulting {@link MarkedEntityDTO} pager
890 * @see IIdentifiableEntityService#findByMarker(Class, MarkerType, Boolean, boolean, Integer, Integer, List)
892 public <S
extends TaxonBase
> Pager
<MarkedEntityDTO
<S
>> findByMarker(
893 Class
<S
> clazz
, MarkerType markerType
, Boolean markerValue
,
894 TaxonNode subtreeFilter
, boolean includeEntity
, Integer pageSize
,
895 Integer pageNumber
, List
<String
> propertyPaths
);
899 * @param acceptedTaxonUuid
902 public UpdateResult
swapSynonymAndAcceptedTaxon(UUID synonymUUid
, UUID acceptedTaxonUuid
);
907 * @param classificationUuid
910 public DeleteResult
deleteTaxon(UUID taxonUuid
, TaxonDeletionConfigurator config
, UUID classificationUuid
);
913 public UpdateResult
moveFactualDateToAnotherTaxon(UUID fromTaxonUuid
,
920 * @param taxonRelationshipType
922 * @param microcitation
925 public UpdateResult
changeSynonymToRelatedTaxon(UUID synonymUuid
, UUID toTaxonUuid
, TaxonRelationshipType taxonRelationshipType
,
926 Reference citation
, String microcitation
);
929 * @param fromTaxonUuid
931 * @param oldRelationshipType
934 * @throws DataChangeNoRollbackException
936 public UpdateResult
changeRelatedTaxonToSynonym(UUID fromTaxonUuid
, UUID toTaxonUuid
,
937 TaxonRelationshipType oldRelationshipType
, SynonymType synonymType
) throws DataChangeNoRollbackException
;