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
;
22 import eu
.etaxonomy
.cdm
.api
.service
.config
.IFindTaxaAndNamesConfigurator
;
23 import eu
.etaxonomy
.cdm
.api
.service
.config
.MatchingTaxonConfigurator
;
24 import eu
.etaxonomy
.cdm
.api
.service
.config
.SynonymDeletionConfigurator
;
26 import eu
.etaxonomy
.cdm
.api
.service
.config
.TaxonBaseDeletionConfigurator
;
27 import eu
.etaxonomy
.cdm
.api
.service
.config
.TaxonDeletionConfigurator
;
28 import eu
.etaxonomy
.cdm
.api
.service
.exception
.DataChangeNoRollbackException
;
29 import eu
.etaxonomy
.cdm
.api
.service
.exception
.HomotypicalGroupChangeException
;
30 import eu
.etaxonomy
.cdm
.api
.service
.exception
.ReferencedObjectUndeletableException
;
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
.IdentifiableEntity
;
36 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
37 import eu
.etaxonomy
.cdm
.model
.common
.OrderedTermVocabulary
;
38 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
;
39 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
.Direction
;
40 import eu
.etaxonomy
.cdm
.model
.common
.UuidAndTitleCache
;
41 import eu
.etaxonomy
.cdm
.model
.description
.DescriptionElementBase
;
42 import eu
.etaxonomy
.cdm
.model
.description
.Feature
;
43 import eu
.etaxonomy
.cdm
.model
.description
.PresenceAbsenceTermBase
;
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
.TaxonRelationship
;
58 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationshipType
;
59 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
60 import eu
.etaxonomy
.cdm
.persistence
.fetch
.CdmFetch
;
61 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
64 public interface ITaxonService
extends IIdentifiableEntityService
<TaxonBase
>{
67 * Computes all taxon bases.
72 * FIXME could substitute with list(Synonym.class, limit, start)
74 public List
<Synonym
> getAllSynonyms(int limit
, int start
);
77 * Computes all taxon bases.
82 * FIXME could substitute with list(Taxon.class, limit,start)
84 public List
<Taxon
> getAllTaxa(int limit
, int start
);
87 * Computes all Taxon instances that do not have a taxonomic parent.
88 * @param sec The concept reference that the taxon belongs to
90 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
91 * @return The List<Taxon> of root taxa.
92 * @deprecated obsolete when using classification
95 public List
<Taxon
> getRootTaxa(Reference sec
, CdmFetch cdmFetch
, boolean onlyWithChildren
);
98 * Computes all Taxon instances which name is of a certain Rank.
99 * @param rank The rank of the taxon name
100 * @param sec The concept reference that the taxon belongs to
101 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
102 * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
103 * the misapplied name are not returned.<Br>Default: true.
104 * @param propertyPaths
105 * properties to be initialized, For detailed description and
106 * examples <b>please refer to:</b>
107 * {@link IBeanInitializer#initialize(Object, List)}. <Br>
109 * @return The List<Taxon> of root taxa.
110 * @deprecated obsolete when using classification
113 public List
<Taxon
> getRootTaxa(Rank rank
, Reference sec
, boolean onlyWithChildren
, boolean withMisapplications
, List
<String
> propertyPaths
);
116 * Computes all relationships.
120 * FIXME candidate for harmonization - rename to listRelationships
122 public List
<RelationshipBase
> getAllRelationships(int limit
, int start
);
125 * Returns TaxonRelationshipType vocabulary
127 * @deprecated use TermService#getVocabulary(VocabularyType) instead
130 public OrderedTermVocabulary
<TaxonRelationshipType
> getTaxonRelationshipTypeVocabulary();
133 * Returns a list of taxa that matches the name string and the sec reference
134 * @param name the name string to search for
135 * @param sec the taxons sec reference
136 * @return a list of taxa matching the name and the sec reference
138 public List
<TaxonBase
> searchTaxaByName(String name
, Reference sec
);
141 * Swaps given synonym and accepted taxon.
144 * <li>A new accepted taxon with the synonyms name is created</li>
145 * <li>The synonym is deleted from the old accepted taxons synonym list</li>
146 * <li>A new synonym with the name of the old accepted taxon is created</li>
147 * <li>The newly created synonym get related to the newly created accepted taxon</li>
151 * @param acceptedTaxon
152 * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
154 public void swapSynonymAndAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
);
157 * Changes a synonym into an accepted taxon and removes
158 * the synonym relationship to the given accepted taxon.
159 * Other synonyms homotypic to the synonym to change are
160 * moved to the same new accepted taxon as homotypic
161 * synonyms. The new accepted taxon has the same name and
162 * the same sec reference as the old synonym.<BR>
163 * If the given accepted taxon and the synonym are homotypic
164 * to each other an exception may be thrown as taxonomically it doesn't
165 * make sense to have two accepted taxa in the same homotypic group
166 * but also it is than difficult to decide how to handle other names
167 * in the homotypic group. It is up to the implementing class to
168 * handle this situation via an exception or in another way.
172 * the synonym to change into an accepted taxon
173 * @param acceptedTaxon
174 * an accepted taxon, the synonym had a relationship to
175 * @param deleteSynonym
176 * if true the method tries to delete the old synonym from the database
177 * @param copyCitationInfo
178 * if true the citation and the microcitation of newly created synonyms
179 * is taken from the old synonym relationships.
181 * if given this citation is added to the newly created synonym
182 * relationships as citation. Only used if copyCitationInfo is <code> false</code>
183 * @param microCitation
184 * if given this microCitation is added to the newly created synonym
185 * relationships as microCitation.Only used if copyCitationInfo is <code> false</code>
187 * the newly created accepted taxon
188 * @throws IllegalArgumentException
189 * if the given accepted taxon and the synonym are homotypic
190 * to each other an exception may be thrown as taxonomically it doesn't
191 * make sense to have two accepted taxa in the same homotypic group
192 * but also it is than difficult to decide how to handle other names
193 * in the homotypic group. It is up to the implementing class to
194 * handle this situation via an exception or in another way.
196 public Taxon
changeSynonymToAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
, boolean deleteSynonym
, boolean copyCitationInfo
, Reference citation
, String microCitation
) throws HomotypicalGroupChangeException
;
199 * TODO still needed and correct?
200 * Change a synonym into a related concept
203 * the synonym to change into the concept taxon
205 * the taxon the newly created concept should be related to
206 * @param taxonRelationshipType
207 * the type of relationship
209 * @param microReference
211 * the newly created concept
213 public Taxon
changeSynonymToRelatedTaxon(Synonym synonym
, Taxon toTaxon
, TaxonRelationshipType taxonRelationshipType
, Reference reference
, String microReference
);
216 * Deletes all synonym relationships of a given synonym. If taxon is given only those relationships to the taxon are deleted.
217 * @param syn the synonym
221 public long deleteSynonymRelationships(Synonym syn
, Taxon taxon
);
224 * Deletes a taxon from the underlying database according to the given {@link TaxonDeletionConfigurator configurator}.
227 * @throws ReferencedObjectUndeletableException
229 public UUID
deleteTaxon(Taxon taxon
, TaxonDeletionConfigurator config
, Classification classification
) throws DataChangeNoRollbackException
;
232 * Changes the homotypic group of a synonym into the new homotypic group.
233 * All relations to taxa are updated correctly depending on the homotypic
234 * group of the accepted taxon. <BR>
235 * All existing basionym relationships to and from this name are removed.<BR>
236 * If the parameter <code>targetTaxon</code> is defined, the synonym is
237 * added to this taxon irrespctive of if it has been related to this
239 * If <code>removeFromOtherTaxa</code> is true and <code>targetTaxon</code> is
240 * defined all relationships to other taxa are deleted.<BR>
241 * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
242 * between the existing basionym(s) of the new homotypic group and the synonyms name
246 * @param newHomotypicalGroup
248 * @param setBasionymRelationIfApplicable
250 public void changeHomotypicalGroupOfSynonym(Synonym synonym
, HomotypicalGroup newHomotypicalGroup
, Taxon targetTaxon
,
251 boolean removeFromOtherTaxa
, boolean setBasionymRelationIfApplicable
);
255 * Moves a synonym to another taxon and removes the old synonym relationship.
257 * @param oldSynonymRelation the old synonym relationship defining the synonym to move and the old accepted taxon.
258 * @param newTaxon the taxon the synonym will be moved to
259 * @param moveHomotypicGroup if the synonym belongs to a homotypical group with other synonyms and
260 * <code>moveHomotypicGroup</code> is <code>true</code> all these synonyms are moved to the new taxon,
261 * if <code>false</code> a {@link HomotypicalGroupChangeException} is thrown.
262 * <code>MoveHomotypicGroup</code> has no effect if the synonym is the only synonym in it's homotypic group.
263 * @param newSynonymRelationshipType the synonym relationship type of the new synonym relations. Default is
264 * {@link SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF() heterotypic}.
265 * @param newReference The reference for the new synonym relation(s).
266 * @param newReferenceDetail The reference detail for the new synonym relation(s).
267 * @param keepReference if no <code>newReference</code> and/or no <code>newReferenceDetail</code>
268 * is defined they are taken from the old synonym relation(s) if <code>keepReference</code> is
269 * <code>true</code>. If <code>false</code> the reference and the reference detail will be taken
270 * only from the <code>newReference</code> and <code>newReferenceDetail</code>.
271 * @return The new synonym relationship. If <code>moveHomotypicGroup</code> is <code>true</code> additionally
272 * created new synonym relationships must be retrieved separately from the new taxon.
273 * @throws HomotypicalGroupChangeException Exception is thrown if (1) synonym is homotypic to the old accepted taxon or
274 * (2) synonym is in homotypic group with other synonyms and <code>moveHomotypicGroup</code> is false
276 public SynonymRelationship
moveSynonymToAnotherTaxon(SynonymRelationship oldSynonymRelation
, Taxon newTaxon
, boolean moveHomotypicGroup
,
277 SynonymRelationshipType newSynonymRelationshipType
, Reference newReference
, String newReferenceDetail
, boolean keepReference
) throws HomotypicalGroupChangeException
;
280 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
281 * where the supplied taxon is relatedTo.
283 * @param taxon The taxon that is relatedTo
284 * @param type The type of TaxonRelationship (can be null)
285 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
286 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
287 * @param orderHints Properties to order by
288 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
289 * @return a List of TaxonRelationship instances
291 public List
<TaxonRelationship
> listToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
296 * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
297 * where the supplied taxon is relatedTo.
299 * @param taxon The taxon that is relatedTo
300 * @param type The type of TaxonRelationship (can be null)
301 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
302 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
303 * @param orderHints Properties to order by
304 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
305 * @return a Pager of TaxonRelationship instances
307 public Pager
<TaxonRelationship
> pageToTaxonRelationships(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 argument is supplied)
311 * where the supplied taxon is relatedFrom.
313 * @param taxon The taxon that is relatedFrom
314 * @param type The type of TaxonRelationship (can be null)
315 * @param 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 List of TaxonRelationship instances
321 public List
<TaxonRelationship
> listFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
325 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
326 * where the supplied taxon is relatedFrom.
328 * @param taxon The taxon that is relatedFrom
329 * @param type The type of TaxonRelationship (can be null)
330 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
331 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
332 * @param orderHints Properties to order by
333 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
334 * @return a Pager of TaxonRelationship instances
336 public Pager
<TaxonRelationship
> pageFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
339 * lists all taxa which are related to the <code>taxon</code> given as
343 * @param includeRelationships
345 * <code>1</code> for one level, <code>null</code> for infinite
346 * depth, <code>0</code> will completely omit collecting related taxa.
349 * @param propertyPaths
352 public Set
<Taxon
> listRelatedTaxa(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, Integer maxDepth
,
353 Integer limit
, Integer start
, List
<String
> propertyPaths
);
356 * lists all accepted taxa for the given {@link Synonym}
361 * @param propertyPaths
364 public List
<Classification
> listClassifications(TaxonBase taxonBase
, Integer limit
, Integer start
, List
<String
> propertyPaths
);
367 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
368 * where the supplied synonym is relatedFrom.
370 * @param taxon The synonym that is relatedFrom
371 * @param type The type of SynonymRelationship (can be null)
372 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
373 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
374 * * @param orderHints Properties to order by
375 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
376 * @return a Pager of SynonymRelationship instances
378 public Pager
<SynonymRelationship
> getSynonyms(Synonym synonym
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
381 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
382 * where the supplied taxon is relatedTo.
384 * @param taxon The taxon that is relatedTo
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(Taxon taxon
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
395 * Returns the list of all synonyms that share the same homotypical group with the given taxon.
396 * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
398 * @param propertyPaths
401 public List
<Synonym
> getHomotypicSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
404 * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
405 * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
406 * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
407 * belong to a homotypical group which cannot be the homotypical group to which the
408 * taxon name of the given taxon belongs. This method does not return the homotypic group the given
409 * taxon belongs to.<BR>
410 * This method does neglect the type of synonym relationship that is defined between the given taxon
411 * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
412 * in one of the result lists as long as the synonym does not belong to the same homotypic group as
413 * the given taxon.<BR>
414 * The list returned is ordered according to the date of publication of the
415 * first published name within each homotypical group.
417 * @see #getHeterotypicSynonymyGroups()
418 * @see #getSynonyms()
419 * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
420 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
423 * @param propertyPaths
426 public List
<List
<Synonym
>> getHeterotypicSynonymyGroups(Taxon taxon
, List
<String
> propertyPaths
);
429 * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
431 * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
433 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
434 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
436 * Supports path like <code>orderHints.propertyNames</code> which
437 * include *-to-one properties like createdBy.username or
438 * authorTeam.persistentTitleCache
439 * @param propertyPaths properties to be initialized
440 * @return a Pager Taxon instances
441 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
444 public Pager
<TaxonBase
> search(Class
<?
extends TaxonBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
447 * Returns a list of TaxonBase instances where the
448 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
449 * <i>null</i> will search for those taxa with a value of null in that field
451 * @param clazz optionally filter by class (can be null to return all taxa)
453 * @param infragenericEpithet
454 * @param specificEpithet
455 * @param infraspecificEpithet
457 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
458 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
459 * @return a list of TaxonBase instances
461 public Pager
<TaxonBase
> findTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, Rank rank
, Integer pageSize
, Integer pageNumber
);
464 * Returns a list of TaxonBase instances where the
465 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
466 * <i>null</i> will search for those taxa with a value of null in that field
468 * @param clazz optionally filter by class
470 * @param infragenericEpithet
471 * @param specificEpithet
472 * @param infraspecificEpithet
474 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
475 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
476 * @return a List of TaxonBase instances
478 public List
<TaxonBase
> listTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, Rank rank
, Integer pageSize
, Integer pageNumber
);
481 * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
482 * that match the properties specified in the configurator.
483 * @param configurator
486 public Pager
<IdentifiableEntity
> findTaxaAndNames(IFindTaxaAndNamesConfigurator configurator
);
489 * performes a union searches for TaxonBase instances on all available
490 * free text indexes. At the time of writing this documentation it combines
491 * {@link #findByDescriptionElementFullText(Class, String, Classification, List, List, boolean, Integer, Integer, List, List)}
492 * and {@link #findByFullText(Class, String, Classification, List, boolean, Integer, Integer, List, List)
496 * @param classification
497 * Additional filter criterion: If a taxonomic classification
498 * three is specified here the result set will only contain taxa
499 * of the given classification
501 * Additional filter criterion: Search only in these languages.
502 * Not all text fields in the cdm model are multilingual, thus
503 * this setting will only apply to the multilingiual fields.
504 * Other fields are searched nevertheless if this parameter is
506 * @param highlightFragments
509 * The maximum number of objects returned (can be null for all
512 * The offset (in pageSize chunks) from the start of the result
515 * Supports path like <code>orderHints.propertyNames</code> which
516 * include *-to-one properties like createdBy.username or
517 * authorTeam.persistentTitleCache
518 * @param propertyPaths
519 * properties to initialize - see
520 * {@link IBeanInitializer#initialize(Object, List)}
521 * @return a paged list of instances of type T matching the queryString and
522 * the additional filter criteria
524 * @throws CorruptIndexException
525 * @throws IOException
526 * @throws ParseException
527 * @throws LuceneMultiSearchException
528 * @deprecated this search should fully be covered by the new method
529 * {@link #findTaxaAndNamesByFullText(EnumSet, String, Classification, Set, List, boolean, Integer, Integer, List, List)}
530 * , maybe we should rename this latter method to give it a more meaningful name
533 public Pager
<SearchResult
<TaxonBase
>> findByEverythingFullText(String queryString
,
534 Classification classification
, List
<Language
> languages
, boolean highlightFragments
,
535 Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
, LuceneMultiSearchException
;
538 * Searches for TaxonBase instances using the TaxonBase free text index.
540 * <h4>This is an experimental feature, it may be moved, modified, or even
541 * removed in future releases!!!</h4>
544 * Additional filter criterion: The specific TaxonBase subclass
548 * @param classification
549 * Additional filter criterion: If a taxonomic classification
550 * three is specified here the result set will only contain taxa
551 * of the given classification
553 * Additional filter criterion: Search only in these languages.
554 * Not all text fields in the cdm model are multilingual, thus
555 * this setting will only apply to the multilingiual fields.
556 * Other fields are searched nevertheless if this parameter is
558 * @param highlightFragments
561 * The maximum number of objects returned (can be null for all
564 * The offset (in pageSize chunks) from the start of the result
567 * Supports path like <code>orderHints.propertyNames</code> which
568 * include *-to-one properties like createdBy.username or
569 * authorTeam.persistentTitleCache
570 * @param propertyPaths
571 * properties to initialize - see
572 * {@link IBeanInitializer#initialize(Object, List)}
573 * @return a paged list of instances of type T matching the queryString and
574 * the additional filter criteria
575 * @throws CorruptIndexException
576 * @throws IOException
577 * @throws ParseException
579 public Pager
<SearchResult
<TaxonBase
>> findByFullText(Class
<?
extends TaxonBase
> clazz
, String queryString
, Classification classification
,
580 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
581 List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
;
586 * @param statusFilter
587 * @param classification
588 * Additional filter criterion: If a taxonomic classification
589 * three is specified here the result set will only contain taxa
590 * of the given classification
591 * @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 propertyPath
603 * Common properties to initialize the instances of the
604 * CDM types ({@link Taxon} and {@link Synonym}
605 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
606 * @return a paged list of instances of {@link Taxon} instances
607 * @throws IOException
608 * @throws ParseException
610 public Pager
<SearchResult
<TaxonBase
>> findByDistribution(List
<NamedArea
> areaFilter
, List
<PresenceAbsenceTermBase
<?
>> statusFilter
,
611 Classification classification
,
612 Integer pageSize
, Integer pageNumber
,
613 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
) throws IOException
, ParseException
;
616 * Searches for TaxonBase instances using the TaxonBase free text index.
620 * <h4>This is an experimental feature, it may be moved, modified, or even
621 * removed in future releases!!!</h4>
623 * Additional filter criterion: defaults to [doTaxa] if set null
626 * @param classification
627 * Additional filter criterion: If a taxonomic classification
628 * three is specified here the result set will only contain taxa
629 * of the given classification
632 * Additional filter criterion: Search only in these languages.
633 * Not all text fields in the cdm model are multilingual, thus
634 * this setting will only apply to the multilingiual fields.
635 * Other fields are searched nevertheless if this parameter is
637 * @param highlightFragments
640 * The maximum number of objects returned (can be null for all
643 * The offset (in pageSize chunks) from the start of the result
646 * Supports path like <code>orderHints.propertyNames</code> which
647 * include *-to-one properties like createdBy.username or
648 * authorTeam.persistentTitleCache
649 * @param propertyPath
650 * Common properties to initialize the instances of the
651 * CDM types ({@link Taxon} and {@link Synonym}
652 * this method can return - see {@link IBeanInitializer#initialize(Object, List)}
653 * @return a paged list of instances of {@link Taxon}, {@link Synonym}, matching the queryString and
654 * the additional filter criteria
655 * @throws CorruptIndexException
656 * @throws IOException
657 * @throws ParseException
658 * @throws LuceneMultiSearchException
660 public Pager
<SearchResult
<TaxonBase
>> findTaxaAndNamesByFullText(
661 EnumSet
<TaxaAndNamesSearchMode
> searchModes
,
662 String queryString
, Classification classification
, Set
<NamedArea
> namedAreas
, Set
<PresenceAbsenceTermBase
<?
>> distributionStatus
,
663 List
<Language
> languages
, boolean highlightFragments
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
,
664 List
<String
> propertyPaths
) throws CorruptIndexException
, IOException
, ParseException
, LuceneMultiSearchException
;
667 * Searches for TaxonBase instances by using the DescriptionElement free text index.
669 * <h4>This is an experimental feature, it may be moved, modified, or even
670 * removed in future releases!!!</h4>
673 * Additional filter criterion:
675 * the query string to filter by
676 * @param classification
677 * Additional filter criterion: If a taxonomic classification
678 * three is specified here the result set will only contain taxa
679 * of the given classification
683 * Additional filter criterion: Search only in these languages.
684 * Not all text fields in the cdm model are multilingual, thus
685 * this setting will only apply to the multilingiual fields.
686 * Other fields are searched nevertheless if this parameter is
688 * @param highlightFragments
691 * The maximum number of objects returned (can be null for all
694 * The offset (in pageSize chunks) from the start of the result
697 * Supports path like <code>orderHints.propertyNames</code> which
698 * include *-to-one properties like createdBy.username or
699 * authorTeam.persistentTitleCache
700 * @param propertyPaths
701 * properties to initialize - see
702 * {@link IBeanInitializer#initialize(Object, List)}
703 * @return a paged list of instances of type T matching the queryString and
704 * the additional filter criteria
705 * @throws IOException
706 * @throws CorruptIndexException
707 * @throws ParseException
709 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
;
717 * @param widthOrDuration
721 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
724 public List
<MediaRepresentation
> getAllMedia(Taxon taxon
, int size
, int height
, int widthOrDuration
, String
[] mimeTypes
);
728 * Lists all Media found in an any TaxonDescription associated with this
732 * @param includeRelationships
733 * the given list of TaxonRelationshipEdges will be taken into
734 * account when retrieving media associated with the given taxon.
736 * @param limitToGalleries
737 * whether to take only TaxonDescription into account which are
740 * @deprecated use {@link #listMedia(Taxon, Set, boolean, boolean, List)} instead
743 public List
<Media
> listTaxonDescriptionMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
, boolean limitToGalleries
, List
<String
> propertyPath
);
746 * Lists all Media found in an any TaxonDescription, NameDescription,
747 * SpecimenOrObservationBase, DnaSample Chromatograms, etc. associated with this taxon.
750 * @param includeRelationships
751 * the given list of TaxonRelationshipEdges will be taken into
752 * account when retrieving media associated with the given taxon.
754 * @param limitToGalleries
755 * whether to take only descriptions into account which are
756 * marked as gallery, can be NULL
757 * @param includeTaxonDescriptions
758 * whether to take TaxonDescriptions into account, can be NULL
759 * @param includeOccurrences
760 * whether to take TaxonDescriptions into account, can be NULL
761 * @param includeTaxonNameDescriptions
762 * whether to take TaxonNameDescriptions into account, can be NULL
763 * @param propertyPath
766 public List
<Media
> listMedia(Taxon taxon
, Set
<TaxonRelationshipEdge
> includeRelationships
,
767 Boolean limitToGalleries
, Boolean includeTaxonDescriptions
, Boolean includeOccurrences
,
768 Boolean includeTaxonNameDescriptions
, List
<String
> propertyPath
);
770 public List
<TaxonBase
> findTaxaByID(Set
<Integer
> listOfIDs
);
773 * Returns the TaxonBase with the given UUID
774 * using the given match mode and initialization strategy
777 * @param propertyPaths
780 public TaxonBase
findTaxonByUuid(UUID uuid
, List
<String
> propertyPaths
);
782 public int countAllRelationships();
784 public List
<TaxonNameBase
> findIdenticalTaxonNames(List
<String
> propertyPath
);
785 public List
<TaxonNameBase
> findIdenticalTaxonNameIds(List
<String
> propertyPath
);
786 public String
getPhylumName(TaxonNameBase name
);
788 public long deleteSynonymRelationships(Synonym syn
);
795 * Removes a synonym.<BR><BR>
797 * In detail it removes
798 * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
799 * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
801 * If <code>removeNameIfPossible</code> is true
802 * it also removes the synonym name if it is not used in any other context
803 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
804 * If <code>newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
805 * the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
807 * If synonym is <code>null</code> the method has no effect.
811 * @param removeNameIfPossible
812 * @throws DataChangeNoRollbackException
814 public void deleteSynonym(Synonym synonym
, SynonymDeletionConfigurator config
);
818 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
819 * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
821 * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
822 * @param type The type of SynonymRelationship (can be null)
823 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
824 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
825 * @param orderHints Properties to order by
826 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link IBeanInitializer#initialize(Object, List)}
827 * @param direction The direction of the relationship
828 * @return a List of SynonymRelationship instances
830 public List
<SynonymRelationship
> listSynonymRelationships(
831 TaxonBase taxonBase
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
,
832 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
, Direction direction
);
838 public Taxon
findBestMatchingTaxon(String taxonName
);
840 public Taxon
findBestMatchingTaxon(MatchingTaxonConfigurator config
);
842 public Synonym
findBestMatchingSynonym(String taxonName
);
844 public List
<UuidAndTitleCache
<TaxonBase
>> getUuidAndTitleCacheTaxon();
846 public List
<UuidAndTitleCache
<TaxonBase
>> getUuidAndTitleCacheSynonym();
848 public List
<UuidAndTitleCache
<TaxonBase
>> findTaxaAndNamesForEditor(IFindTaxaAndNamesConfigurator configurator
);
851 * Creates the specified inferred synonyms for the taxon in the classification, but do not insert it to the database
854 * @return list of inferred synonyms
856 public List
<Synonym
> createInferredSynonyms(Taxon taxon
, Classification tree
, SynonymRelationshipType type
, boolean doWithMisappliedNames
);
859 * Creates all inferred synonyms for the taxon in the classification, but do not insert it to the database
863 * @return list of inferred synonyms
865 public List
<Synonym
> createAllInferredSynonyms(Taxon taxon
, Classification tree
, boolean doWithMisappliedNames
);
871 * Removes a synonym.<BR><BR>
873 * In detail it removes
874 * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
875 * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
877 * If <code>config.removeNameIfPossible</code> is true
878 * it also removes the synonym name if it is not used in any other context
879 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
880 * If <code>config.newHomotypicGroupIfNeeded</code> is <code>true</code> and the synonym name is not deleted and
881 * the name is homotypic to the taxon the name is moved to a new homotypical group.<BR><BR>
883 * If synonym is <code>null</code> the method has no effect.
888 * @throws DataChangeNoRollbackException
890 void deleteSynonym(Synonym synonym
, Taxon taxon
,
891 SynonymDeletionConfigurator config
);