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
.FindByIdentifierDTO
;
28 import eu
.etaxonomy
.cdm
.api
.service
.dto
.IncludedTaxaDTO
;
29 import eu
.etaxonomy
.cdm
.api
.service
.exception
.DataChangeNoRollbackException
;
30 import eu
.etaxonomy
.cdm
.api
.service
.exception
.HomotypicalGroupChangeException
;
31 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
32 import eu
.etaxonomy
.cdm
.api
.service
.search
.LuceneMultiSearchException
;
33 import eu
.etaxonomy
.cdm
.api
.service
.search
.SearchResult
;
34 import eu
.etaxonomy
.cdm
.api
.service
.util
.TaxonRelationshipEdge
;
35 import eu
.etaxonomy
.cdm
.model
.common
.DefinedTerm
;
36 import eu
.etaxonomy
.cdm
.model
.common
.IdentifiableEntity
;
37 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
38 import eu
.etaxonomy
.cdm
.model
.common
.OrderedTermVocabulary
;
39 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
;
40 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
.Direction
;
41 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionElementBase
;
42 import eu
.etaxonomy
.cdm
.model
.description
.Feature
;
43 import eu
.etaxonomy
.cdm
.model
.description
.PresenceAbsenceTerm
;
44 import eu
.etaxonomy
.cdm
.model
.location
.NamedArea
;
45 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
46 import eu
.etaxonomy
.cdm
.model
.media
.MediaRepresentation
;
47 import eu
.etaxonomy
.cdm
.model
.name
.HomotypicalGroup
;
48 import eu
.etaxonomy
.cdm
.model
.name
.Rank
;
49 import eu
.etaxonomy
.cdm
.model
.name
.TaxonNameBase
;
50 import eu
.etaxonomy
.cdm
.model
.reference
.Reference
;
51 import eu
.etaxonomy
.cdm
.model
.taxon
.Classification
;
52 import eu
.etaxonomy
.cdm
.model
.taxon
.Synonym
;
53 import eu
.etaxonomy
.cdm
.model
.taxon
.SynonymRelationship
;
54 import eu
.etaxonomy
.cdm
.model
.taxon
.SynonymRelationshipType
;
55 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
56 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonBase
;
57 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonNode
;
58 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationship
;
59 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationshipType
;
60 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
61 import eu
.etaxonomy
.cdm
.persistence
.dto
.UuidAndTitleCache
;
62 import eu
.etaxonomy
.cdm
.persistence
.fetch
.CdmFetch
;
63 import eu
.etaxonomy
.cdm
.persistence
.query
.MatchMode
;
64 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
67 public interface ITaxonService
extends IIdentifiableEntityService
<TaxonBase
>{
70 * Computes all Taxon instances that do not have a taxonomic parent.
71 * @param sec The concept reference that the taxon belongs to
73 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
74 * @return The List<Taxon> of root taxa.
75 * @deprecated obsolete when using classification
78 public List
<Taxon
> getRootTaxa(Reference sec
, CdmFetch cdmFetch
, boolean onlyWithChildren
);
81 * Computes all Taxon instances which name is of a certain Rank.
82 * @param rank The rank of the taxon name
83 * @param sec The concept reference that the taxon belongs to
84 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
85 * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
86 * the misapplied name are not returned.<Br>Default: true.
87 * @param propertyPaths
88 * properties to be initialized, For detailed description and
89 * examples <b>please refer to:</b>
90 * {@link IBeanInitializer#initialize(Object, List)}. <Br>
92 * @return The List<Taxon> of root taxa.
93 * @deprecated obsolete when using classification
96 public List
<Taxon
> getRootTaxa(Rank rank
, Reference sec
, boolean onlyWithChildren
, boolean withMisapplications
, List
<String
> propertyPaths
);
99 * Computes all relationships.
103 * FIXME candidate for harmonization - rename to listRelationships
105 public List
<RelationshipBase
> getAllRelationships(int limit
, int start
);
108 * Returns TaxonRelationshipType vocabulary
110 * @deprecated use TermService#getVocabulary(VocabularyType) instead
113 public OrderedTermVocabulary
<TaxonRelationshipType
> getTaxonRelationshipTypeVocabulary();
116 * Returns a list of taxa that matches the name string and the sec reference
117 * @param name the name string to search for
118 * @param sec the taxons sec reference
119 * @return a list of taxa matching the name and the sec reference
121 public List
<TaxonBase
> searchTaxaByName(String name
, Reference sec
);
124 * Swaps given synonym and accepted taxon.
127 * <li>A new accepted taxon with the synonyms name is created</li>
128 * <li>The synonym is deleted from the old accepted taxons synonym list</li>
129 * <li>A new synonym with the name of the old accepted taxon is created</li>
130 * <li>The newly created synonym get related to the newly created accepted taxon</li>
134 * @param acceptedTaxon
135 * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
138 public UpdateResult
swapSynonymAndAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
);
141 * Changes a synonym into an accepted taxon and removes
142 * the synonym relationship to the given accepted taxon.
143 * Other synonyms homotypic to the synonym to change are
144 * moved to the same new accepted taxon as homotypic
145 * synonyms. The new accepted taxon has the same name and
146 * the same sec reference as the old synonym.<BR>
147 * If the given accepted taxon and the synonym are homotypic
148 * to each other an exception may be thrown as taxonomically it doesn't
149 * make sense to have two accepted taxa in the same homotypic group
150 * but also it is than difficult to decide how to handle other names
151 * in the homotypic group. It is up to the implementing class to
152 * handle this situation via an exception or in another way.
156 * the synonym to change into an accepted taxon
157 * @param acceptedTaxon
158 * an accepted taxon, the synonym had a relationship to
159 * @param deleteSynonym
160 * if true the method tries to delete the old synonym from the database
161 * @param copyCitationInfo
162 * if true the citation and the microcitation of newly created synonyms
163 * is taken from the old synonym relationships.
165 * if given this citation is added to the newly created synonym
166 * relationships as citation. Only used if copyCitationInfo is <code> false</code>
167 * @param microCitation
168 * if given this microCitation is added to the newly created synonym
169 * relationships as microCitation.Only used if copyCitationInfo is <code> false</code>
171 * the newly created accepted taxon
172 * @throws IllegalArgumentException
173 * if the given accepted taxon and the synonym are homotypic
174 * to each other an exception may be thrown as taxonomically it doesn't
175 * make sense to have two accepted taxa in the same homotypic group
176 * but also it is than difficult to decide how to handle other names
177 * in the homotypic group. It is up to the implementing class to
178 * handle this situation via an exception or in another way.
180 public Taxon
changeSynonymToAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
, boolean deleteSynonym
, boolean copyCitationInfo
, Reference citation
, String microCitation
) throws HomotypicalGroupChangeException
;
183 * TODO still needed and correct?
184 * Change a synonym into a related concept
187 * the synonym to change into the concept taxon
189 * the taxon the newly created concept should be related to
190 * @param taxonRelationshipType
191 * the type of relationship
193 * @param microReference
195 * the newly created concept
197 public Taxon
changeSynonymToRelatedTaxon(Synonym synonym
, Taxon toTaxon
, TaxonRelationshipType taxonRelationshipType
, Reference reference
, String microReference
);
200 * TODO still needed and correct?
201 * Change a synonym into a related concept
204 * the synonym to change into the concept taxon
206 * the taxon the newly created concept should be related to
207 * @param taxonRelationshipType
208 * the type of relationship
210 * @param microReference
212 * the newly created concept
213 * @throws DataChangeNoRollbackException
215 public Synonym
changeRelatedTaxonToSynonym(Taxon fromTaxon
, Taxon toTaxon
,
216 TaxonRelationshipType oldRelationshipType
,
217 SynonymRelationshipType synonymRelationshipType
) throws DataChangeNoRollbackException
;
219 * Deletes all synonym relationships of a given synonym. If taxon is given
220 * only those relationships to the taxon are deleted.
226 * @deprecated This method must no longer being used since the
227 * SynonymRelationship is annotated at the {@link Taxon} and at
228 * the {@link Synonym} with <code>orphanDelete=true</code>. Just
229 * remove the from and to entities from the relationship and
230 * hibernate will care for the deletion. Using this method can cause
231 * <code>StaleStateException</code> (see http://dev.e-taxonomy.eu/trac/ticket/3797)
235 public long deleteSynonymRelationships(Synonym syn
, Taxon taxon
);
239 * Changes the homotypic group of a synonym into the new homotypic group.
240 * All relations to taxa are updated correctly depending on the homotypic
241 * group of the accepted taxon. <BR>
242 * All existing basionym relationships to and from this name are removed.<BR>
243 * If the parameter <code>targetTaxon</code> is defined, the synonym is
244 * added to this taxon irrespctive of if it has been related to this
246 * If <code>removeFromOtherTaxa</code> is true and <code>targetTaxon</code> is
247 * defined all relationships to other taxa are deleted.<BR>
248 * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
249 * between the existing basionym(s) of the new homotypic group and the synonyms name
253 * @param newHomotypicalGroup
255 * @param setBasionymRelationIfApplicable
257 public void changeHomotypicalGroupOfSynonym(Synonym synonym
, HomotypicalGroup newHomotypicalGroup
, Taxon targetTaxon
,
258 boolean removeFromOtherTaxa
, boolean setBasionymRelationIfApplicable
);
262 * Moves a synonym to another taxon and removes the old synonym relationship.
264 * @param oldSynonymRelation the old synonym relationship defining the synonym to move and the old accepted taxon.
265 * @param newTaxon the taxon the synonym will be moved to
266 * @param moveHomotypicGroup if the synonym belongs to a homotypical group with other synonyms and
267 * <code>moveHomotypicGroup</code> is <code>true</code> all these synonyms are moved to the new taxon,
268 * if <code>false</code> a {@link HomotypicalGroupChangeException} is thrown.
269 * <code>MoveHomotypicGroup</code> has no effect if the synonym is the only synonym in it's homotypic group.
270 * @param newSynonymRelationshipType the synonym relationship type of the new synonym relations. Default is
271 * {@link SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF() heterotypic}.
272 * @param newReference The reference for the new synonym relation(s).
273 * @param newReferenceDetail The reference detail for the new synonym relation(s).
274 * @param keepReference if no <code>newReference</code> and/or no <code>newReferenceDetail</code>
275 * is defined they are taken from the old synonym relation(s) if <code>keepReference</code> is
276 * <code>true</code>. If <code>false</code> the reference and the reference detail will be taken
277 * only from the <code>newReference</code> and <code>newReferenceDetail</code>.
278 * @return The new synonym relationship. If <code>moveHomotypicGroup</code> is <code>true</code> additionally
279 * created new synonym relationships must be retrieved separately from the new taxon.
280 * @throws HomotypicalGroupChangeException Exception is thrown if (1) synonym is homotypic to the old accepted taxon or
281 * (2) synonym is in homotypic group with other synonyms and <code>moveHomotypicGroup</code> is false
283 public UpdateResult
moveSynonymToAnotherTaxon(SynonymRelationship oldSynonymRelation
, Taxon newTaxon
, boolean moveHomotypicGroup
,
284 SynonymRelationshipType newSynonymRelationshipType
, Reference newReference
, String newReferenceDetail
, boolean keepReference
) throws HomotypicalGroupChangeException
;
287 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
288 * where the supplied taxon is relatedTo.
290 * @param taxon The taxon that is relatedTo
291 * @param type The type of TaxonRelationship (can be null)
292 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
293 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
294 * @param orderHints Properties to order by
295 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
296 * @return a List of TaxonRelationship instances
298 public List
<TaxonRelationship
> listToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
303 * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
304 * where the supplied taxon is relatedTo.
306 * @param taxon The taxon that is relatedTo
307 * @param type The type of TaxonRelationship (can be null)
308 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
309 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
310 * @param orderHints Properties to order by
311 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
312 * @return a Pager of TaxonRelationship instances
314 public Pager
<TaxonRelationship
> pageToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
317 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
318 * where the supplied taxon is relatedFrom.
320 * @param taxon The taxon that is relatedFrom
321 * @param type The type of TaxonRelationship (can be null)
322 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
323 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
324 * @param orderHints Properties to order by
325 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
326 * @return a List of TaxonRelationship instances
328 public List
<TaxonRelationship
> listFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
332 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
333 * where the supplied taxon is relatedFrom.
335 * @param taxon The taxon that is relatedFrom
336 * @param type The type of TaxonRelationship (can be null)
337 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
338 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
339 * @param orderHints Properties to order by
340 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
341 * @return a Pager of TaxonRelationship instances
343 public Pager
<TaxonRelationship
> pageFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
346 * lists all taxa which are related to the <code>taxon</code> given as
350 * @param includeRelationships
352 * <code>1</code> for one level, <code>null</code> for infinite
353 * depth, <code>0</code> will completely omit collecting related taxa.
356 * @param propertyPaths
359 public Set
<Taxon
> listRelatedTaxa(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, Integer maxDepth
,
360 Integer limit
, Integer start
, List
<String
> propertyPaths
);
363 * lists all accepted taxa for the given {@link Synonym}
368 * @param propertyPaths
371 public List
<Classification
> listClassifications(TaxonBase taxonBase
, Integer limit
, Integer start
, List
<String
> propertyPaths
);
374 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
375 * where the supplied synonym is relatedFrom.
377 * @param taxon The synonym that is relatedFrom
378 * @param type The type of SynonymRelationship (can be null)
379 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
380 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
381 * * @param orderHints Properties to order by
382 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
383 * @return a Pager of SynonymRelationship instances
385 public Pager
<SynonymRelationship
> getSynonyms(Synonym synonym
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
388 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
389 * where the supplied taxon is relatedTo.
391 * @param taxon The taxon that is relatedTo
392 * @param type The type of SynonymRelationship (can be null)
393 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
394 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
395 * * @param orderHints Properties to order by
396 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
397 * @return a Pager of SynonymRelationship instances
399 public Pager
<SynonymRelationship
> getSynonyms(Taxon taxon
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
402 * This method returns in the first entry the list of synonyms of the
403 * homotypic group of the accepted taxon. All other entries represent the lists of heterotypic
404 * synonym groups. For detailed information about these 2 groups see
405 * {@link #getHomotypicSynonymsByHomotypicGroup(Taxon, List)} and
406 * {@link #getHeterotypicSynonymyGroups(Taxon, List)}
408 * @see #getSynonyms()
409 * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
410 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
412 * @param taxon the accepted taxon
413 * @param propertyPaths the property path
414 * @return the list of groups of synonyms
416 public List
<List
<Synonym
>> getSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
420 * Returns the list of all synonyms that share the same homotypical group with the given taxon.
421 * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
423 * @param propertyPaths
426 public List
<Synonym
> getHomotypicSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
429 * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
430 * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
431 * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
432 * belong to a homotypical group which cannot be the homotypical group to which the
433 * taxon name of the given taxon belongs. This method does not return the homotypic group the given
434 * taxon belongs to.<BR>
435 * This method does neglect the type of synonym relationship that is defined between the given taxon
436 * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
437 * in one of the result lists as long as the synonym does not belong to the same homotypic group as
438 * the given taxon.<BR>
439 * The list returned is ordered according to the date of publication of the
440 * first published name within each homotypical group.
442 * @see #getHeterotypicSynonymyGroups()
443 * @see #getSynonyms()
444 * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
445 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
448 * @param propertyPaths
451 public List
<List
<Synonym
>> getHeterotypicSynonymyGroups(Taxon taxon
, List
<String
> propertyPaths
);
454 * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
456 * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
458 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
459 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
461 * Supports path like <code>orderHints.propertyNames</code> which
462 * include *-to-one properties like createdBy.username or
463 * authorTeam.persistentTitleCache
464 * @param propertyPaths properties to be initialized
465 * @return a Pager Taxon instances
466 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
469 public Pager
<TaxonBase
> search(Class
<?
extends TaxonBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
472 * Returns a list of TaxonBase instances where the
473 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
474 * <i>null</i> will search for those taxa with a value of null in that field
476 * @param clazz optionally filter by class (can be null to return all taxa)
478 * @param infragenericEpithet
479 * @param specificEpithet
480 * @param infraspecificEpithet
482 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
483 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
484 * @return a list of TaxonBase instances
486 public Pager
<TaxonBase
> findTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, String authorship
, Rank rank
, Integer pageSize
, Integer pageNumber
);
489 * Returns a list of TaxonBase instances where the
490 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
491 * <i>null</i> will search for those taxa with a value of null in that field
493 * @param clazz optionally filter by class
495 * @param infragenericEpithet
496 * @param specificEpithet
497 * @param infraspecificEpithet
499 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
500 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
501 * @return a List of TaxonBase instances
503 public List
<TaxonBase
> listTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, String authorship
, Rank rank
, Integer pageSize
, Integer pageNumber
);
506 * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
507 * that match the properties specified in the configurator.
508 * @param configurator
511 public Pager
<IdentifiableEntity
> findTaxaAndNames(IFindTaxaAndNamesConfigurator configurator
);
514 * performes a union searches for TaxonBase instances on all available
515 * free text indexes. At the time of writing this documentation it combines
516 * {@link #findByDescriptionElementFullText(Class, String, Classification, List, List, boolean, Integer, Integer, List, List)}
517 * and {@link #findByFullText(Class, String, Classification, List, boolean, Integer, Integer, List, List)
521 * @param classification
522 * Additional filter criterion: If a taxonomic classification
523 * three is specified here the result set will only contain taxa
524 * of the given classification
526 * Additional filter criterion: Search only in these languages.
527 * Not all text fields in the cdm model are multilingual, thus
528 * this setting will only apply to the multilingiual fields.
529 * Other fields are searched nevertheless if this parameter is
531 * @param highlightFragments
534 * The maximum number of objects returned (can be null for all
537 * The offset (in pageSize chunks) from the start of the result
540 * Supports path like <code>orderHints.propertyNames</code> which
541 * include *-to-one properties like createdBy.username or
542 * authorTeam.persistentTitleCache
543 * @param propertyPaths
544 * properties to initialize - see
545 * {@link IBeanInitializer#initialize(Object, List)}
546 * @return a paged list of instances of type T matching the queryString and
547 * the additional filter criteria
549 * @throws CorruptIndexException
550 * @throws IOException
551 * @throws ParseException
552 * @throws LuceneMultiSearchException
553 * @deprecated this search should fully be covered by the new method
554 * {@link #findTaxaAndNamesByFullText(EnumSet, String, Classification, Set, List, boolean, Integer, Integer, List, List)}
555 * , maybe we should rename this latter method to give it a more meaningful name
558 public Pager
<SearchResult
<TaxonBase
>> findByEverythingFullText(String queryString
,
559 Classification classification
, List
<Language
> languages
, boolean highlightFragments
,
560 Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
, LuceneMultiSearchException
;
563 * Searches for TaxonBase instances using the TaxonBase free text index.
565 * <h4>This is an experimental feature, it may be moved, modified, or even
566 * removed in future releases!!!</h4>
569 * Additional filter criterion: The specific TaxonBase subclass
573 * @param classification
574 * Additional filter criterion: If a taxonomic classification
575 * three is specified here the result set will only contain taxa
576 * of the given classification
578 * Additional filter criterion: Search only in these languages.
579 * Not all text fields in the cdm model are multilingual, thus
580 * this setting will only apply to the multilingiual fields.
581 * Other fields are searched nevertheless if this parameter is
583 * @param highlightFragments
586 * The maximum number of objects returned (can be null for all
589 * The offset (in pageSize chunks) from the start of the result
592 * Supports path like <code>orderHints.propertyNames</code> which
593 * include *-to-one properties like createdBy.username or
594 * authorTeam.persistentTitleCache
595 * @param propertyPaths
596 * properties to initialize - see
597 * {@link IBeanInitializer#initialize(Object, List)}
598 * @return a paged list of instances of type T matching the queryString and
599 * the additional filter criteria
600 * @throws CorruptIndexException
601 * @throws IOException
602 * @throws ParseException
604 public Pager
<SearchResult
<TaxonBase
>> findByFullText(Class
<?
extends TaxonBase
> clazz
, String queryString
, Classification classification
,
605 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
606 List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
;
611 * @param statusFilter
612 * @param classification
613 * Additional filter criterion: If a taxonomic classification
614 * three is specified here the result set will only contain taxa
615 * of the given classification
616 * @param highlightFragments
618 * The maximum number of objects returned (can be null for all
621 * The offset (in pageSize chunks) from the start of the result
624 * Supports path like <code>orderHints.propertyNames</code> which
625 * include *-to-one properties like createdBy.username or
626 * authorTeam.persistentTitleCache
627 * @param propertyPath
628 * Common properties to initialize the instances of the
629 * CDM types ({@link Taxon} and {@link Synonym}
630 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
631 * @return a paged list of instances of {@link Taxon} instances
632 * @throws IOException
633 * @throws ParseException
635 public Pager
<SearchResult
<TaxonBase
>> findByDistribution(List
<NamedArea
> areaFilter
, List
<PresenceAbsenceTerm
> statusFilter
,
636 Classification classification
,
637 Integer pageSize
, Integer pageNumber
,
638 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws IOException
, ParseException
;
641 * Searches for TaxonBase instances using the TaxonBase free text index.
645 * <h4>This is an experimental feature, it may be moved, modified, or even
646 * removed in future releases!!!</h4>
648 * Additional filter criterion: defaults to [doTaxa] if set null
651 * @param classification
652 * Additional filter criterion: If a taxonomic classification
653 * three is specified here the result set will only contain taxa
654 * of the given classification
657 * Additional filter criterion: Search only in these languages.
658 * Not all text fields in the cdm model are multilingual, thus
659 * this setting will only apply to the multilingiual fields.
660 * Other fields are searched nevertheless if this parameter is
662 * @param highlightFragments
665 * The maximum number of objects returned (can be null for all
668 * The offset (in pageSize chunks) from the start of the result
671 * Supports path like <code>orderHints.propertyNames</code> which
672 * include *-to-one properties like createdBy.username or
673 * authorTeam.persistentTitleCache
674 * @param propertyPath
675 * Common properties to initialize the instances of the
676 * CDM types ({@link Taxon} and {@link Synonym}
677 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
678 * @return a paged list of instances of {@link Taxon}, {@link Synonym}, matching the queryString and
679 * the additional filter criteria
680 * @throws CorruptIndexException
681 * @throws IOException
682 * @throws ParseException
683 * @throws LuceneMultiSearchException
685 public Pager
<SearchResult
<TaxonBase
>> findTaxaAndNamesByFullText(
686 EnumSet
<TaxaAndNamesSearchMode
> searchModes
,
687 String queryString
, Classification classification
, Set
<NamedArea
> namedAreas
, Set
<PresenceAbsenceTerm
> distributionStatus
,
688 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
689 List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
, LuceneMultiSearchException
;
692 * Searches for TaxonBase instances by using the DescriptionElement free text index.
694 * <h4>This is an experimental feature, it may be moved, modified, or even
695 * removed in future releases!!!</h4>
698 * Additional filter criterion:
700 * the query string to filter by
701 * @param classification
702 * Additional filter criterion: If a taxonomic classification
703 * three is specified here the result set will only contain taxa
704 * of the given classification
708 * Additional filter criterion: Search only in these languages.
709 * Not all text fields in the cdm model are multilingual, thus
710 * this setting will only apply to the multilingiual fields.
711 * Other fields are searched nevertheless if this parameter is
713 * @param highlightFragments
716 * The maximum number of objects returned (can be null for all
719 * The offset (in pageSize chunks) from the start of the result
722 * Supports path like <code>orderHints.propertyNames</code> which
723 * include *-to-one properties like createdBy.username or
724 * authorTeam.persistentTitleCache
725 * @param propertyPaths
726 * properties to initialize - see
727 * {@link IBeanInitializer#initialize(Object, List)}
728 * @return a paged list of instances of type T matching the queryString and
729 * the additional filter criteria
730 * @throws IOException
731 * @throws CorruptIndexException
732 * @throws ParseException
734 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
;
742 * @param widthOrDuration
746 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
749 public List
<MediaRepresentation
> getAllMedia(Taxon taxon
, int size
, int height
, int widthOrDuration
, String
[] mimeTypes
);
753 * Lists all Media found in an any TaxonDescription associated with this
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 TaxonDescription into account which are
765 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
768 public List
<Media
> listTaxonDescriptionMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, boolean limitToGalleries
, List
<String
> propertyPath
);
771 * Lists all Media found in an any TaxonDescription, NameDescription,
772 * SpecimenOrObservationBase, DnaSample Chromatograms, etc. associated with this taxon.
775 * @param includeRelationships
776 * the given list of TaxonRelationshipEdges will be taken into
777 * account when retrieving media associated with the given taxon.
779 * @param limitToGalleries
780 * whether to take only descriptions into account which are
781 * marked as gallery, can be NULL
782 * @param includeTaxonDescriptions
783 * whether to take TaxonDescriptions into account, can be NULL
784 * @param includeOccurrences
785 * whether to take TaxonDescriptions into account, can be NULL
786 * @param includeTaxonNameDescriptions
787 * whether to take TaxonNameDescriptions into account, can be NULL
788 * @param propertyPath
791 public List
<Media
> listMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
,
792 Boolean limitToGalleries
, Boolean includeTaxonDescriptions
, Boolean includeOccurrences
,
793 Boolean includeTaxonNameDescriptions
, List
<String
> propertyPath
);
795 public List
<TaxonBase
> findTaxaByID(Set
<Integer
> listOfIDs
);
798 * Returns the TaxonBase with the given UUID
799 * using the given match mode and initialization strategy
802 * @param propertyPaths
805 public TaxonBase
findTaxonByUuid(UUID uuid
, List
<String
> propertyPaths
);
807 public int countAllRelationships();
809 public List
<TaxonNameBase
> findIdenticalTaxonNames(List
<String
> propertyPath
);
811 public List
<TaxonNameBase
> findIdenticalTaxonNameIds(List
<String
> propertyPath
);
813 public String
getPhylumName(TaxonNameBase name
);
815 public long deleteSynonymRelationships(Synonym syn
);
818 * Returns all {@link Taxon taxa} which are {@link TaxonRelationshipType#CONGRUENT_TO() congruent} or
819 * {@link TaxonRelationshipType#INCLUDES() included} in the taxon represented by the given taxon uuid.
820 * The result also returns the path to these taxa represented by the uuids of
821 * the {@link TaxonRelationshipType taxon relationships types} and doubtful information.
822 * If classificationUuids is set only taxa of classifications are returned which are included
823 * in the given {@link Classification classifications}. ALso the path to these taxa may not include
824 * taxa from other classifications.
825 * @param taxonUuid uuid of the original taxon
826 * @param classificationUuids List of uuids of classifications used as a filter
827 * @param includeDoubtful set to <code>true</code> if also doubtfully included taxa should be included in the result
828 * @return a DTO which includes a list of taxa with the pathes from the original taxon to the given taxon as well
829 * as doubtful and date information. The original taxon is included in the result.
831 public IncludedTaxaDTO
listIncludedTaxa(UUID taxonUuid
, IncludedTaxonConfiguration configuration
);
835 * Removes a synonym.<BR><BR>
837 * In detail it removes
838 * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
839 * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
841 * If <code>removeNameIfPossible</code> is true
842 * it also removes the synonym name if it is not used in any other context
843 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
844 * If <code>newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
845 * the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
847 * If synonym is <code>null</code> the method has no effect.
851 * @param removeNameIfPossible
852 * @return deleteResult
855 public DeleteResult
deleteSynonym(Synonym synonym
, SynonymDeletionConfigurator config
);
860 * The method essentially loads the synonym and calls the
861 * {@link #deleteSynonym(Synonym, SynonymDeletionConfigurator) deleteSynonym} method
867 public DeleteResult
deleteSynonym(UUID synonymUuid
, SynonymDeletionConfigurator config
);
870 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
871 * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
873 * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
874 * @param type The type of SynonymRelationship (can be null)
875 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
876 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
877 * @param orderHints Properties to order by
878 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
879 * @param direction The direction of the relationship
880 * @return a List of SynonymRelationship instances
882 public List
<SynonymRelationship
> listSynonymRelationships(
883 TaxonBase taxonBase
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
,
884 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
, Direction direction
);
890 public Taxon
findBestMatchingTaxon(String taxonName
);
892 public Taxon
findBestMatchingTaxon(MatchingTaxonConfigurator config
);
894 public Synonym
findBestMatchingSynonym(String taxonName
);
896 public List
<UuidAndTitleCache
<TaxonBase
>> getUuidAndTitleCacheTaxon(Integer limit
, String pattern
);
898 public List
<UuidAndTitleCache
<TaxonBase
>> getUuidAndTitleCacheSynonym(Integer limit
, String pattern
);
900 public List
<UuidAndTitleCache
<IdentifiableEntity
>> findTaxaAndNamesForEditor(IFindTaxaAndNamesConfigurator configurator
);
903 * Creates the specified inferred synonyms for the taxon in the classification, but do not insert it to the database
906 * @return list of inferred synonyms
908 public List
<Synonym
> createInferredSynonyms(Taxon taxon
, Classification tree
, SynonymRelationshipType type
, boolean doWithMisappliedNames
);
911 * Creates all inferred synonyms for the taxon in the classification, but do not insert it to the database
915 * @return list of inferred synonyms
917 public List
<Synonym
> createAllInferredSynonyms(Taxon taxon
, Classification tree
, boolean doWithMisappliedNames
);
923 * Removes a synonym.<BR><BR>
925 * In detail it removes
926 * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
927 * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
929 * If <code>config.removeNameIfPossible</code> is true
930 * it also removes the synonym name if it is not used in any other context
931 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
932 * If <code>config.newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
933 * the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
935 * If synonym is <code>null</code> the method has no effect.
940 * @return deleteResult
942 public DeleteResult
deleteSynonym(Synonym synonym
, Taxon taxon
, SynonymDeletionConfigurator config
);
946 public Pager
<Taxon
> pageAcceptedTaxaFor(UUID synonymUuid
, UUID classificationUuid
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
947 List
<String
> propertyPaths
);
949 public List
<Taxon
> listAcceptedTaxaFor(UUID synonymUuid
, UUID classificationUuid
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
950 List
<String
> propertyPaths
);
952 public List
<TaxonBase
> findTaxaByName(MatchingTaxonConfigurator config
);
955 public <S
extends TaxonBase
> Pager
<FindByIdentifierDTO
<S
>> findByIdentifier(
956 Class
<S
> clazz
, String identifier
, DefinedTerm identifierType
, TaxonNode subtreeFilter
,
957 MatchMode matchmode
, boolean includeEntity
, Integer pageSize
,
958 Integer pageNumber
, List
<String
> propertyPaths
);
967 public DeleteResult
deleteSynonym(UUID synonymUuid
, UUID taxonUuid
, SynonymDeletionConfigurator config
);
971 * @param acceptedTaxonUuid
974 public UpdateResult
swapSynonymAndAcceptedTaxon(UUID synonymUUid
, UUID acceptedTaxonUuid
);
979 * @param classificationUuid
982 public DeleteResult
deleteTaxon(UUID taxonUuid
, TaxonDeletionConfigurator config
, UUID classificationUuid
);
984 public UpdateResult
moveSynonymToAnotherTaxon(SynonymRelationship oldSynonymRelation
,
985 UUID newTaxonUUID
, boolean moveHomotypicGroup
,
986 SynonymRelationshipType newSynonymRelationshipType
,
987 Reference reference
, String referenceDetail
, boolean keepReference
)
988 throws HomotypicalGroupChangeException
;
990 public UpdateResult
moveFactualDateToAnotherTaxon(UUID fromTaxonUuid
,
997 * @param taxonRelationshipType
999 * @param microcitation
1002 public UpdateResult
changeSynonymToRelatedTaxon(UUID synonymUuid
, UUID toTaxonUuid
, TaxonRelationshipType taxonRelationshipType
,
1003 Reference citation
, String microcitation
);
1006 * @param fromTaxonUuid
1007 * @param toTaxonUuid
1008 * @param oldRelationshipType
1009 * @param synonymRelationshipType
1011 * @throws DataChangeNoRollbackException
1013 public UpdateResult
changeRelatedTaxonToSynonym(UUID fromTaxonUuid
, UUID toTaxonUuid
,
1014 TaxonRelationshipType oldRelationshipType
, SynonymRelationshipType synonymRelationshipType
) throws DataChangeNoRollbackException
;
1017 * @param synonymUuid
1018 * @param acceptedTaxonUuid
1019 * @param newParentNodeUuid
1020 * @param deleteSynonym
1021 * @param copyCitationInfo
1023 * @param microCitation
1025 * @throws HomotypicalGroupChangeException
1027 public UpdateResult
changeSynonymToAcceptedTaxon(UUID synonymUuid
, UUID acceptedTaxonUuid
, UUID newParentNodeUuid
,
1028 boolean deleteSynonym
, boolean copyCitationInfo
, Reference citation
, String microCitation
)
1029 throws HomotypicalGroupChangeException
;