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
.ParseException
;
21 import org
.springframework
.transaction
.annotation
.Transactional
;
23 import eu
.etaxonomy
.cdm
.api
.service
.config
.IFindTaxaAndNamesConfigurator
;
24 import eu
.etaxonomy
.cdm
.api
.service
.config
.IncludedTaxonConfiguration
;
25 import eu
.etaxonomy
.cdm
.api
.service
.config
.MatchingTaxonConfigurator
;
26 import eu
.etaxonomy
.cdm
.api
.service
.config
.SynonymDeletionConfigurator
;
27 import eu
.etaxonomy
.cdm
.api
.service
.config
.TaxonDeletionConfigurator
;
28 import eu
.etaxonomy
.cdm
.api
.service
.dto
.FindByIdentifierDTO
;
29 import eu
.etaxonomy
.cdm
.api
.service
.dto
.IncludedTaxaDTO
;
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
.OrderedTermVocabulary
;
40 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
;
41 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
.Direction
;
42 import eu
.etaxonomy
.cdm
.model
.common
.UuidAndTitleCache
;
43 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionElementBase
;
44 import eu
.etaxonomy
.cdm
.model
.description
.Feature
;
45 import eu
.etaxonomy
.cdm
.model
.description
.PresenceAbsenceTerm
;
46 import eu
.etaxonomy
.cdm
.model
.location
.NamedArea
;
47 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
48 import eu
.etaxonomy
.cdm
.model
.media
.MediaRepresentation
;
49 import eu
.etaxonomy
.cdm
.model
.name
.HomotypicalGroup
;
50 import eu
.etaxonomy
.cdm
.model
.name
.Rank
;
51 import eu
.etaxonomy
.cdm
.model
.name
.TaxonNameBase
;
52 import eu
.etaxonomy
.cdm
.model
.reference
.Reference
;
53 import eu
.etaxonomy
.cdm
.model
.taxon
.Classification
;
54 import eu
.etaxonomy
.cdm
.model
.taxon
.Synonym
;
55 import eu
.etaxonomy
.cdm
.model
.taxon
.SynonymRelationship
;
56 import eu
.etaxonomy
.cdm
.model
.taxon
.SynonymRelationshipType
;
57 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
58 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonBase
;
59 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonNode
;
60 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationship
;
61 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationshipType
;
62 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
63 import eu
.etaxonomy
.cdm
.persistence
.fetch
.CdmFetch
;
64 import eu
.etaxonomy
.cdm
.persistence
.query
.MatchMode
;
65 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
68 public interface ITaxonService
extends IIdentifiableEntityService
<TaxonBase
>{
71 * Computes all Taxon instances that do not have a taxonomic parent.
72 * @param sec The concept reference that the taxon belongs to
74 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
75 * @return The List<Taxon> of root taxa.
76 * @deprecated obsolete when using classification
79 public List
<Taxon
> getRootTaxa(Reference sec
, CdmFetch cdmFetch
, boolean onlyWithChildren
);
82 * Computes all Taxon instances which name is of a certain Rank.
83 * @param rank The rank of the taxon name
84 * @param sec The concept reference that the taxon belongs to
85 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
86 * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
87 * the misapplied name are not returned.<Br>Default: true.
88 * @param propertyPaths
89 * properties to be initialized, For detailed description and
90 * examples <b>please refer to:</b>
91 * {@link IBeanInitializer#initialize(Object, List)}. <Br>
93 * @return The List<Taxon> of root taxa.
94 * @deprecated obsolete when using classification
97 public List
<Taxon
> getRootTaxa(Rank rank
, Reference sec
, boolean onlyWithChildren
, boolean withMisapplications
, List
<String
> propertyPaths
);
100 * Computes all relationships.
104 * FIXME candidate for harmonization - rename to listRelationships
106 public List
<RelationshipBase
> getAllRelationships(int limit
, int start
);
109 * Returns TaxonRelationshipType vocabulary
111 * @deprecated use TermService#getVocabulary(VocabularyType) instead
114 public OrderedTermVocabulary
<TaxonRelationshipType
> getTaxonRelationshipTypeVocabulary();
117 * Returns a list of taxa that matches the name string and the sec reference
118 * @param name the name string to search for
119 * @param sec the taxons sec reference
120 * @return a list of taxa matching the name and the sec reference
122 public List
<TaxonBase
> searchTaxaByName(String name
, Reference sec
);
125 * Swaps given synonym and accepted taxon.
128 * <li>A new accepted taxon with the synonyms name is created</li>
129 * <li>The synonym is deleted from the old accepted taxons synonym list</li>
130 * <li>A new synonym with the name of the old accepted taxon is created</li>
131 * <li>The newly created synonym get related to the newly created accepted taxon</li>
135 * @param acceptedTaxon
136 * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
138 public void 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
);
238 * Deletes a taxon from the underlying database according to the given {@link TaxonDeletionConfigurator configurator}.
243 public DeleteResult
deleteTaxon(Taxon taxon
, TaxonDeletionConfigurator config
, Classification classification
) ;
246 * Changes the homotypic group of a synonym into the new homotypic group.
247 * All relations to taxa are updated correctly depending on the homotypic
248 * group of the accepted taxon. <BR>
249 * All existing basionym relationships to and from this name are removed.<BR>
250 * If the parameter <code>targetTaxon</code> is defined, the synonym is
251 * added to this taxon irrespctive of if it has been related to this
253 * If <code>removeFromOtherTaxa</code> is true and <code>targetTaxon</code> is
254 * defined all relationships to other taxa are deleted.<BR>
255 * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
256 * between the existing basionym(s) of the new homotypic group and the synonyms name
260 * @param newHomotypicalGroup
262 * @param setBasionymRelationIfApplicable
264 public void changeHomotypicalGroupOfSynonym(Synonym synonym
, HomotypicalGroup newHomotypicalGroup
, Taxon targetTaxon
,
265 boolean removeFromOtherTaxa
, boolean setBasionymRelationIfApplicable
);
269 * Moves a synonym to another taxon and removes the old synonym relationship.
271 * @param oldSynonymRelation the old synonym relationship defining the synonym to move and the old accepted taxon.
272 * @param newTaxon the taxon the synonym will be moved to
273 * @param moveHomotypicGroup if the synonym belongs to a homotypical group with other synonyms and
274 * <code>moveHomotypicGroup</code> is <code>true</code> all these synonyms are moved to the new taxon,
275 * if <code>false</code> a {@link HomotypicalGroupChangeException} is thrown.
276 * <code>MoveHomotypicGroup</code> has no effect if the synonym is the only synonym in it's homotypic group.
277 * @param newSynonymRelationshipType the synonym relationship type of the new synonym relations. Default is
278 * {@link SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF() heterotypic}.
279 * @param newReference The reference for the new synonym relation(s).
280 * @param newReferenceDetail The reference detail for the new synonym relation(s).
281 * @param keepReference if no <code>newReference</code> and/or no <code>newReferenceDetail</code>
282 * is defined they are taken from the old synonym relation(s) if <code>keepReference</code> is
283 * <code>true</code>. If <code>false</code> the reference and the reference detail will be taken
284 * only from the <code>newReference</code> and <code>newReferenceDetail</code>.
285 * @return The new synonym relationship. If <code>moveHomotypicGroup</code> is <code>true</code> additionally
286 * created new synonym relationships must be retrieved separately from the new taxon.
287 * @throws HomotypicalGroupChangeException Exception is thrown if (1) synonym is homotypic to the old accepted taxon or
288 * (2) synonym is in homotypic group with other synonyms and <code>moveHomotypicGroup</code> is false
290 public SynonymRelationship
moveSynonymToAnotherTaxon(SynonymRelationship oldSynonymRelation
, Taxon newTaxon
, boolean moveHomotypicGroup
,
291 SynonymRelationshipType newSynonymRelationshipType
, Reference newReference
, String newReferenceDetail
, boolean keepReference
) throws HomotypicalGroupChangeException
;
294 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
295 * where the supplied taxon is relatedTo.
297 * @param taxon The taxon that is relatedTo
298 * @param type The type of TaxonRelationship (can be null)
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
> listToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
310 * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
311 * where the supplied taxon is relatedTo.
313 * @param taxon The taxon that is relatedTo
314 * @param type The type of TaxonRelationship (can be null)
315 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
316 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
317 * @param orderHints Properties to order by
318 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
319 * @return a Pager of TaxonRelationship instances
321 public Pager
<TaxonRelationship
> pageToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
324 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
325 * where the supplied taxon is relatedFrom.
327 * @param taxon The taxon that is relatedFrom
328 * @param type The type of TaxonRelationship (can be null)
329 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
330 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
331 * @param orderHints Properties to order by
332 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
333 * @return a List of TaxonRelationship instances
335 public List
<TaxonRelationship
> listFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
339 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
340 * where the supplied taxon is relatedFrom.
342 * @param taxon The taxon that is relatedFrom
343 * @param type The type of TaxonRelationship (can be null)
344 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
345 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
346 * @param orderHints Properties to order by
347 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
348 * @return a Pager of TaxonRelationship instances
350 public Pager
<TaxonRelationship
> pageFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
353 * lists all taxa which are related to the <code>taxon</code> given as
357 * @param includeRelationships
359 * <code>1</code> for one level, <code>null</code> for infinite
360 * depth, <code>0</code> will completely omit collecting related taxa.
363 * @param propertyPaths
366 public Set
<Taxon
> listRelatedTaxa(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, Integer maxDepth
,
367 Integer limit
, Integer start
, List
<String
> propertyPaths
);
370 * lists all accepted taxa for the given {@link Synonym}
375 * @param propertyPaths
378 public List
<Classification
> listClassifications(TaxonBase taxonBase
, Integer limit
, Integer start
, List
<String
> propertyPaths
);
381 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
382 * where the supplied synonym is relatedFrom.
384 * @param taxon The synonym that is relatedFrom
385 * @param type The type of SynonymRelationship (can be null)
386 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
387 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
388 * * @param orderHints Properties to order by
389 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
390 * @return a Pager of SynonymRelationship instances
392 public Pager
<SynonymRelationship
> getSynonyms(Synonym synonym
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
395 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
396 * where the supplied taxon is relatedTo.
398 * @param taxon The taxon that is relatedTo
399 * @param type The type of SynonymRelationship (can be null)
400 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
401 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
402 * * @param orderHints Properties to order by
403 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
404 * @return a Pager of SynonymRelationship instances
406 public Pager
<SynonymRelationship
> getSynonyms(Taxon taxon
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
409 * This method returns in the first entry the list of synonyms of the
410 * homotypic group of the accepted taxon. All other entries represent the lists of heterotypic
411 * synonym groups. For detailed information about these 2 groups see
412 * {@link #getHomotypicSynonymsByHomotypicGroup(Taxon, List)} and
413 * {@link #getHeterotypicSynonymyGroups(Taxon, List)}
415 * @see #getSynonyms()
416 * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
417 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
419 * @param taxon the accepted taxon
420 * @param propertyPaths the property path
421 * @return the list of groups of synonyms
423 public List
<List
<Synonym
>> getSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
427 * Returns the list of all synonyms that share the same homotypical group with the given taxon.
428 * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
430 * @param propertyPaths
433 public List
<Synonym
> getHomotypicSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
436 * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
437 * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
438 * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
439 * belong to a homotypical group which cannot be the homotypical group to which the
440 * taxon name of the given taxon belongs. This method does not return the homotypic group the given
441 * taxon belongs to.<BR>
442 * This method does neglect the type of synonym relationship that is defined between the given taxon
443 * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
444 * in one of the result lists as long as the synonym does not belong to the same homotypic group as
445 * the given taxon.<BR>
446 * The list returned is ordered according to the date of publication of the
447 * first published name within each homotypical group.
449 * @see #getHeterotypicSynonymyGroups()
450 * @see #getSynonyms()
451 * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
452 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
455 * @param propertyPaths
458 public List
<List
<Synonym
>> getHeterotypicSynonymyGroups(Taxon taxon
, List
<String
> propertyPaths
);
461 * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
463 * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
465 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
466 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
468 * Supports path like <code>orderHints.propertyNames</code> which
469 * include *-to-one properties like createdBy.username or
470 * authorTeam.persistentTitleCache
471 * @param propertyPaths properties to be initialized
472 * @return a Pager Taxon instances
473 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
476 public Pager
<TaxonBase
> search(Class
<?
extends TaxonBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
479 * Returns a list of TaxonBase instances where the
480 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
481 * <i>null</i> will search for those taxa with a value of null in that field
483 * @param clazz optionally filter by class (can be null to return all taxa)
485 * @param infragenericEpithet
486 * @param specificEpithet
487 * @param infraspecificEpithet
489 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
490 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
491 * @return a list of TaxonBase instances
493 public Pager
<TaxonBase
> findTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, Rank rank
, Integer pageSize
, Integer pageNumber
);
496 * Returns a list of TaxonBase instances where the
497 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
498 * <i>null</i> will search for those taxa with a value of null in that field
500 * @param clazz optionally filter by class
502 * @param infragenericEpithet
503 * @param specificEpithet
504 * @param infraspecificEpithet
506 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
507 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
508 * @return a List of TaxonBase instances
510 public List
<TaxonBase
> listTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, Rank rank
, Integer pageSize
, Integer pageNumber
);
513 * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
514 * that match the properties specified in the configurator.
515 * @param configurator
518 public Pager
<IdentifiableEntity
> findTaxaAndNames(IFindTaxaAndNamesConfigurator configurator
);
521 * performes a union searches for TaxonBase instances on all available
522 * free text indexes. At the time of writing this documentation it combines
523 * {@link #findByDescriptionElementFullText(Class, String, Classification, List, List, boolean, Integer, Integer, List, List)}
524 * and {@link #findByFullText(Class, String, Classification, List, boolean, Integer, Integer, List, List)
528 * @param classification
529 * Additional filter criterion: If a taxonomic classification
530 * three is specified here the result set will only contain taxa
531 * of the given classification
533 * Additional filter criterion: Search only in these languages.
534 * Not all text fields in the cdm model are multilingual, thus
535 * this setting will only apply to the multilingiual fields.
536 * Other fields are searched nevertheless if this parameter is
538 * @param highlightFragments
541 * The maximum number of objects returned (can be null for all
544 * The offset (in pageSize chunks) from the start of the result
547 * Supports path like <code>orderHints.propertyNames</code> which
548 * include *-to-one properties like createdBy.username or
549 * authorTeam.persistentTitleCache
550 * @param propertyPaths
551 * properties to initialize - see
552 * {@link IBeanInitializer#initialize(Object, List)}
553 * @return a paged list of instances of type T matching the queryString and
554 * the additional filter criteria
556 * @throws CorruptIndexException
557 * @throws IOException
558 * @throws ParseException
559 * @throws LuceneMultiSearchException
560 * @deprecated this search should fully be covered by the new method
561 * {@link #findTaxaAndNamesByFullText(EnumSet, String, Classification, Set, List, boolean, Integer, Integer, List, List)}
562 * , maybe we should rename this latter method to give it a more meaningful name
565 public Pager
<SearchResult
<TaxonBase
>> findByEverythingFullText(String queryString
,
566 Classification classification
, List
<Language
> languages
, boolean highlightFragments
,
567 Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
, LuceneMultiSearchException
;
570 * Searches for TaxonBase instances using the TaxonBase free text index.
572 * <h4>This is an experimental feature, it may be moved, modified, or even
573 * removed in future releases!!!</h4>
576 * Additional filter criterion: The specific TaxonBase subclass
580 * @param classification
581 * Additional filter criterion: If a taxonomic classification
582 * three is specified here the result set will only contain taxa
583 * of the given classification
585 * Additional filter criterion: Search only in these languages.
586 * Not all text fields in the cdm model are multilingual, thus
587 * this setting will only apply to the multilingiual fields.
588 * Other fields are searched nevertheless if this parameter is
590 * @param highlightFragments
593 * The maximum number of objects returned (can be null for all
596 * The offset (in pageSize chunks) from the start of the result
599 * Supports path like <code>orderHints.propertyNames</code> which
600 * include *-to-one properties like createdBy.username or
601 * authorTeam.persistentTitleCache
602 * @param propertyPaths
603 * properties to initialize - see
604 * {@link IBeanInitializer#initialize(Object, List)}
605 * @return a paged list of instances of type T matching the queryString and
606 * the additional filter criteria
607 * @throws CorruptIndexException
608 * @throws IOException
609 * @throws ParseException
611 public Pager
<SearchResult
<TaxonBase
>> findByFullText(Class
<?
extends TaxonBase
> clazz
, String queryString
, Classification classification
,
612 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
613 List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
;
618 * @param statusFilter
619 * @param classification
620 * Additional filter criterion: If a taxonomic classification
621 * three is specified here the result set will only contain taxa
622 * of the given classification
623 * @param highlightFragments
625 * The maximum number of objects returned (can be null for all
628 * The offset (in pageSize chunks) from the start of the result
631 * Supports path like <code>orderHints.propertyNames</code> which
632 * include *-to-one properties like createdBy.username or
633 * authorTeam.persistentTitleCache
634 * @param propertyPath
635 * Common properties to initialize the instances of the
636 * CDM types ({@link Taxon} and {@link Synonym}
637 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
638 * @return a paged list of instances of {@link Taxon} instances
639 * @throws IOException
640 * @throws ParseException
642 public Pager
<SearchResult
<TaxonBase
>> findByDistribution(List
<NamedArea
> areaFilter
, List
<PresenceAbsenceTerm
> statusFilter
,
643 Classification classification
,
644 Integer pageSize
, Integer pageNumber
,
645 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws IOException
, ParseException
;
648 * Searches for TaxonBase instances using the TaxonBase free text index.
652 * <h4>This is an experimental feature, it may be moved, modified, or even
653 * removed in future releases!!!</h4>
655 * Additional filter criterion: defaults to [doTaxa] if set null
658 * @param classification
659 * Additional filter criterion: If a taxonomic classification
660 * three is specified here the result set will only contain taxa
661 * of the given classification
664 * Additional filter criterion: Search only in these languages.
665 * Not all text fields in the cdm model are multilingual, thus
666 * this setting will only apply to the multilingiual fields.
667 * Other fields are searched nevertheless if this parameter is
669 * @param highlightFragments
672 * The maximum number of objects returned (can be null for all
675 * The offset (in pageSize chunks) from the start of the result
678 * Supports path like <code>orderHints.propertyNames</code> which
679 * include *-to-one properties like createdBy.username or
680 * authorTeam.persistentTitleCache
681 * @param propertyPath
682 * Common properties to initialize the instances of the
683 * CDM types ({@link Taxon} and {@link Synonym}
684 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
685 * @return a paged list of instances of {@link Taxon}, {@link Synonym}, matching the queryString and
686 * the additional filter criteria
687 * @throws CorruptIndexException
688 * @throws IOException
689 * @throws ParseException
690 * @throws LuceneMultiSearchException
692 public Pager
<SearchResult
<TaxonBase
>> findTaxaAndNamesByFullText(
693 EnumSet
<TaxaAndNamesSearchMode
> searchModes
,
694 String queryString
, Classification classification
, Set
<NamedArea
> namedAreas
, Set
<PresenceAbsenceTerm
> distributionStatus
,
695 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
696 List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
, LuceneMultiSearchException
;
699 * Searches for TaxonBase instances by using the DescriptionElement free text index.
701 * <h4>This is an experimental feature, it may be moved, modified, or even
702 * removed in future releases!!!</h4>
705 * Additional filter criterion:
707 * the query string to filter by
708 * @param classification
709 * Additional filter criterion: If a taxonomic classification
710 * three is specified here the result set will only contain taxa
711 * of the given classification
715 * Additional filter criterion: Search only in these languages.
716 * Not all text fields in the cdm model are multilingual, thus
717 * this setting will only apply to the multilingiual fields.
718 * Other fields are searched nevertheless if this parameter is
720 * @param highlightFragments
723 * The maximum number of objects returned (can be null for all
726 * The offset (in pageSize chunks) from the start of the result
729 * Supports path like <code>orderHints.propertyNames</code> which
730 * include *-to-one properties like createdBy.username or
731 * authorTeam.persistentTitleCache
732 * @param propertyPaths
733 * properties to initialize - see
734 * {@link IBeanInitializer#initialize(Object, List)}
735 * @return a paged list of instances of type T matching the queryString and
736 * the additional filter criteria
737 * @throws IOException
738 * @throws CorruptIndexException
739 * @throws ParseException
741 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
;
749 * @param widthOrDuration
753 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
756 public List
<MediaRepresentation
> getAllMedia(Taxon taxon
, int size
, int height
, int widthOrDuration
, String
[] mimeTypes
);
760 * Lists all Media found in an any TaxonDescription associated with this
764 * @param includeRelationships
765 * the given list of TaxonRelationshipEdges will be taken into
766 * account when retrieving media associated with the given taxon.
768 * @param limitToGalleries
769 * whether to take only TaxonDescription into account which are
772 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
775 public List
<Media
> listTaxonDescriptionMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, boolean limitToGalleries
, List
<String
> propertyPath
);
778 * Lists all Media found in an any TaxonDescription, NameDescription,
779 * SpecimenOrObservationBase, DnaSample Chromatograms, etc. associated with this taxon.
782 * @param includeRelationships
783 * the given list of TaxonRelationshipEdges will be taken into
784 * account when retrieving media associated with the given taxon.
786 * @param limitToGalleries
787 * whether to take only descriptions into account which are
788 * marked as gallery, can be NULL
789 * @param includeTaxonDescriptions
790 * whether to take TaxonDescriptions into account, can be NULL
791 * @param includeOccurrences
792 * whether to take TaxonDescriptions into account, can be NULL
793 * @param includeTaxonNameDescriptions
794 * whether to take TaxonNameDescriptions into account, can be NULL
795 * @param propertyPath
798 public List
<Media
> listMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
,
799 Boolean limitToGalleries
, Boolean includeTaxonDescriptions
, Boolean includeOccurrences
,
800 Boolean includeTaxonNameDescriptions
, List
<String
> propertyPath
);
802 public List
<TaxonBase
> findTaxaByID(Set
<Integer
> listOfIDs
);
805 * Returns the TaxonBase with the given UUID
806 * using the given match mode and initialization strategy
809 * @param propertyPaths
812 public TaxonBase
findTaxonByUuid(UUID uuid
, List
<String
> propertyPaths
);
814 public int countAllRelationships();
816 public List
<TaxonNameBase
> findIdenticalTaxonNames(List
<String
> propertyPath
);
818 public List
<TaxonNameBase
> findIdenticalTaxonNameIds(List
<String
> propertyPath
);
820 public String
getPhylumName(TaxonNameBase name
);
822 public long deleteSynonymRelationships(Synonym syn
);
825 * Returns all {@link Taxon taxa} which are {@link TaxonRelationshipType#CONGRUENT_TO() congruent} or
826 * {@link TaxonRelationshipType#INCLUDES() included} in the taxon represented by the given taxon uuid.
827 * The result also returns the path to these taxa represented by the uuids of
828 * the {@link TaxonRelationshipType taxon relationships types} and doubtful information.
829 * If classificationUuids is set only taxa of classifications are returned which are included
830 * in the given {@link Classification classifications}. ALso the path to these taxa may not include
831 * taxa from other classifications.
832 * @param taxonUuid uuid of the original taxon
833 * @param classificationUuids List of uuids of classifications used as a filter
834 * @param includeDoubtful set to <code>true</code> if also doubtfully included taxa should be included in the result
835 * @return a DTO which includes a list of taxa with the pathes from the original taxon to the given taxon as well
836 * as doubtful and date information. The original taxon is included in the result.
838 public IncludedTaxaDTO
listIncludedTaxa(UUID taxonUuid
, IncludedTaxonConfiguration configuration
);
842 * Removes a synonym.<BR><BR>
844 * In detail it removes
845 * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
846 * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
848 * If <code>removeNameIfPossible</code> is true
849 * it also removes the synonym name if it is not used in any other context
850 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
851 * If <code>newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
852 * the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
854 * If synonym is <code>null</code> the method has no effect.
858 * @param removeNameIfPossible
859 * @return deleteResult
862 public DeleteResult
deleteSynonym(Synonym synonym
, SynonymDeletionConfigurator config
);
866 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
867 * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
869 * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
870 * @param type The type of SynonymRelationship (can be null)
871 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
872 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
873 * @param orderHints Properties to order by
874 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
875 * @param direction The direction of the relationship
876 * @return a List of SynonymRelationship instances
878 public List
<SynonymRelationship
> listSynonymRelationships(
879 TaxonBase taxonBase
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
,
880 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
, Direction direction
);
886 public Taxon
findBestMatchingTaxon(String taxonName
);
888 public Taxon
findBestMatchingTaxon(MatchingTaxonConfigurator config
);
890 public Synonym
findBestMatchingSynonym(String taxonName
);
892 public List
<UuidAndTitleCache
<TaxonBase
>> getUuidAndTitleCacheTaxon();
894 public List
<UuidAndTitleCache
<TaxonBase
>> getUuidAndTitleCacheSynonym();
896 public List
<UuidAndTitleCache
<IdentifiableEntity
>> findTaxaAndNamesForEditor(IFindTaxaAndNamesConfigurator configurator
);
899 * Creates the specified inferred synonyms for the taxon in the classification, but do not insert it to the database
902 * @return list of inferred synonyms
904 public List
<Synonym
> createInferredSynonyms(Taxon taxon
, Classification tree
, SynonymRelationshipType type
, boolean doWithMisappliedNames
);
907 * Creates all inferred synonyms for the taxon in the classification, but do not insert it to the database
911 * @return list of inferred synonyms
913 public List
<Synonym
> createAllInferredSynonyms(Taxon taxon
, Classification tree
, boolean doWithMisappliedNames
);
919 * Removes a synonym.<BR><BR>
921 * In detail it removes
922 * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
923 * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
925 * If <code>config.removeNameIfPossible</code> is true
926 * it also removes the synonym name if it is not used in any other context
927 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
928 * If <code>config.newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
929 * the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
931 * If synonym is <code>null</code> the method has no effect.
936 * @return deleteResult
938 DeleteResult
deleteSynonym(Synonym synonym
, Taxon taxon
,
939 SynonymDeletionConfigurator config
);
941 public Pager
<Taxon
> pageAcceptedTaxaFor(UUID synonymUuid
, UUID classificationUuid
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
942 List
<String
> propertyPaths
);
944 public List
<Taxon
> listAcceptedTaxaFor(UUID synonymUuid
, UUID classificationUuid
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
945 List
<String
> propertyPaths
);
947 public List
<TaxonBase
> findTaxaByName(MatchingTaxonConfigurator config
);
950 public <S
extends TaxonBase
> Pager
<FindByIdentifierDTO
<S
>> findByIdentifier(
951 Class
<S
> clazz
, String identifier
, DefinedTerm identifierType
, TaxonNode subtreeFilter
,
952 MatchMode matchmode
, boolean includeEntity
, Integer pageSize
,
953 Integer pageNumber
, List
<String
> propertyPaths
);