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
.util
.List
;
16 import eu
.etaxonomy
.cdm
.api
.service
.config
.DeleteException
;
17 import eu
.etaxonomy
.cdm
.api
.service
.config
.ITaxonServiceConfigurator
;
18 import eu
.etaxonomy
.cdm
.api
.service
.config
.MatchingTaxonConfigurator
;
19 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
20 import eu
.etaxonomy
.cdm
.model
.common
.IdentifiableEntity
;
21 import eu
.etaxonomy
.cdm
.model
.common
.OrderedTermVocabulary
;
22 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
;
23 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
.Direction
;
24 import eu
.etaxonomy
.cdm
.model
.common
.UuidAndTitleCache
;
25 import eu
.etaxonomy
.cdm
.model
.media
.MediaRepresentation
;
26 import eu
.etaxonomy
.cdm
.model
.name
.HomotypicalGroup
;
27 import eu
.etaxonomy
.cdm
.model
.name
.Rank
;
28 import eu
.etaxonomy
.cdm
.model
.name
.TaxonNameBase
;
29 import eu
.etaxonomy
.cdm
.model
.reference
.Reference
;
30 import eu
.etaxonomy
.cdm
.model
.taxon
.Classification
;
31 import eu
.etaxonomy
.cdm
.model
.taxon
.Synonym
;
32 import eu
.etaxonomy
.cdm
.model
.taxon
.SynonymRelationship
;
33 import eu
.etaxonomy
.cdm
.model
.taxon
.SynonymRelationshipType
;
34 import eu
.etaxonomy
.cdm
.model
.taxon
.Taxon
;
35 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonBase
;
36 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationship
;
37 import eu
.etaxonomy
.cdm
.model
.taxon
.TaxonRelationshipType
;
38 import eu
.etaxonomy
.cdm
.persistence
.dao
.BeanInitializer
;
39 import eu
.etaxonomy
.cdm
.persistence
.fetch
.CdmFetch
;
40 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
43 public interface ITaxonService
extends IIdentifiableEntityService
<TaxonBase
>{
46 * Computes all taxon bases.
51 * FIXME could substitute with list(Synonym.class, limit, start)
53 public List
<Synonym
> getAllSynonyms(int limit
, int start
);
56 * Computes all taxon bases.
61 * FIXME could substitute with list(Taxon.class, limit,start)
63 public List
<Taxon
> getAllTaxa(int limit
, int start
);
66 * Computes all Taxon instances that do not have a taxonomic parent.
67 * @param sec The concept reference that the taxon belongs to
69 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
70 * @return The List<Taxon> of root taxa.
71 * @deprecated obsolete when using classification
73 public List
<Taxon
> getRootTaxa(Reference sec
, CdmFetch cdmFetch
, boolean onlyWithChildren
);
76 * Computes all Taxon instances which name is of a certain Rank.
77 * @param rank The rank of the taxon name
78 * @param sec The concept reference that the taxon belongs to
79 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
80 * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
81 * the misapplied name are not returned.<Br>Default: true.
82 * @param propertyPaths
83 * properties to be initialized, For detailed description and
84 * examples <b>please refer to:</b>
85 * {@link BeanInitializer#initialize(Object, List)}. <Br>
87 * @return The List<Taxon> of root taxa.
88 * @deprecated obsolete when using classification
90 public List
<Taxon
> getRootTaxa(Rank rank
, Reference sec
, boolean onlyWithChildren
, boolean withMisapplications
, List
<String
> propertyPaths
);
93 * Computes all relationships.
97 * FIXME candidate for harmonization - rename to listRelationships
99 public List
<RelationshipBase
> getAllRelationships(int limit
, int start
);
102 * Returns TaxonRelationshipType vocabulary
104 * @deprecated use TermService#getVocabulary(VocabularyType) instead
106 public OrderedTermVocabulary
<TaxonRelationshipType
> getTaxonRelationshipTypeVocabulary();
109 * Returns a list of taxa that matches the name string and the sec reference
110 * @param name the name string to search for
111 * @param sec the taxons sec reference
112 * @return a list of taxa matching the name and the sec reference
114 public List
<TaxonBase
> searchTaxaByName(String name
, Reference sec
);
117 * Swaps given synonym and accepted taxon.
120 * <li>A new accepted taxon with the synonyms name is created</li>
121 * <li>The synonym is deleted from the old accepted taxons synonym list</li>
122 * <li>A new synonym with the name of the old accepted taxon is created</li>
123 * <li>The newly created synonym get related to the newly created accepted taxon</li>
127 * @param acceptedTaxon
128 * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
130 public void swapSynonymAndAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
);
133 * Changes a synonym into an accepted taxon and removes
134 * the synonym relationship to the given accepted taxon.
135 * Other synonyms homotypic to the synonym to change are
136 * moved to the same new accepted taxon as homotypic
137 * synonyms. The new accepted taxon has the same name and
138 * the same sec reference as the old synonym.<BR>
139 * If the given accepted taxon and the synonym are homotypic
140 * to each other an exception may be thrown as taxonomically it doesn't
141 * make sense to have two accepted taxa in the same homotypic group
142 * but also it is than difficult to decide how to handle other names
143 * in the homotypic group. It is up to the implementing class to
144 * handle this situation via an exception or in another way.
145 * TODO Open issue: does the old synonym need to be deleted from the database?
148 * the synonym to change into an accepted taxon
149 * @param acceptedTaxon
150 * an accepted taxon, the synonym had a relationship to
151 * @param deleteSynonym
152 * if true the method tries to delete the old synonym from the database
153 * @param copyCitationInfo
154 * if true the citation and the microcitation of newly created synonyms
155 * is taken from the old synonym relationships.
157 * if given this citation is added to the newly created synonym
158 * relationships as citation. Only used if copyCitationInfo is <code> false</code>
159 * @param microCitation
160 * if given this microCitation is added to the newly created synonym
161 * relationships as microCitation.Only used if copyCitationInfo is <code> false</code>
163 * the newly created accepted taxon
164 * @throws IllegalArgumentException
165 * if the given accepted taxon and the synonym are homotypic
166 * to each other an exception may be thrown as taxonomically it doesn't
167 * make sense to have two accepted taxa in the same homotypic group
168 * but also it is than difficult to decide how to handle other names
169 * in the homotypic group. It is up to the implementing class to
170 * handle this situation via an exception or in another way.
172 public Taxon
changeSynonymToAcceptedTaxon(Synonym synonym
, Taxon acceptedTaxon
, boolean deleteSynonym
, boolean copyCitationInfo
, Reference citation
, String microCitation
) throws IllegalArgumentException
;
175 * TODO still needed and correct?
176 * Change a synonym into a related concept
179 * the synonym to change into the concept taxon
181 * the taxon the newly created concept should be related to
182 * @param taxonRelationshipType
183 * the type of relationship
185 * @param microReference
187 * the newly created concept
189 public Taxon
changeSynonymToRelatedTaxon(Synonym synonym
, Taxon toTaxon
, TaxonRelationshipType taxonRelationshipType
, Reference reference
, String microReference
);
193 * Changes the homotypic group of a synonym into the new homotypic group.
194 * All relations to taxa are updated correctly depending on the homotypic
195 * group of the accepted taxon. <BR>
196 * All existing basionym relationships to and from this name are removed.<BR>
197 * If the parameter <code>targetTaxon</code> is defined, the synonym is
198 * added to this taxon irrespctive of if it has been related to this
200 * If <code>removeFromOtherTaxa</code> is true and <code>targetTaxon</code> is
201 * defined all relationships to other taxa are deleted.<BR>
202 * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
203 * between the existing basionym(s) of the new homotypic group and the synonyms name
207 * @param newHomotypicalGroup
209 * @param setBasionymRelationIfApplicable
211 public void changeHomotypicalGroupOfSynonym(Synonym synonym
, HomotypicalGroup newHomotypicalGroup
, Taxon targetTaxon
,
212 boolean removeFromOtherTaxa
, boolean setBasionymRelationIfApplicable
);
216 * Move a synonym to another taxon, effectively removing the old synonym relationship
218 * @param synonymRelation
221 * @param referenceDetail
224 public Taxon
moveSynonymToAnotherTaxon(SynonymRelationship synonymRelation
, Taxon toTaxon
, SynonymRelationshipType synonymRelationshipType
, Reference reference
, String referenceDetail
);
227 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
228 * where the supplied taxon is relatedTo.
230 * @param taxon The taxon that is relatedTo
231 * @param type The type of TaxonRelationship (can be null)
232 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
233 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
234 * @param orderHints Properties to order by
235 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
236 * @return a List of TaxonRelationship instances
238 public List
<TaxonRelationship
> listToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
243 * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
244 * where the supplied taxon is relatedTo.
246 * @param taxon The taxon that is relatedTo
247 * @param type The type of TaxonRelationship (can be null)
248 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
249 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
250 * @param orderHints Properties to order by
251 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
252 * @return a Pager of TaxonRelationship instances
254 public Pager
<TaxonRelationship
> pageToTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
257 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
258 * where the supplied taxon is relatedFrom.
260 * @param taxon The taxon that is relatedFrom
261 * @param type The type of TaxonRelationship (can be null)
262 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
263 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
264 * @param orderHints Properties to order by
265 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
266 * @return a List of TaxonRelationship instances
268 public List
<TaxonRelationship
> listFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
272 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
273 * where the supplied taxon is relatedFrom.
275 * @param taxon The taxon that is relatedFrom
276 * @param type The type of TaxonRelationship (can be null)
277 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
278 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
279 * @param orderHints Properties to order by
280 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
281 * @return a Pager of TaxonRelationship instances
283 public Pager
<TaxonRelationship
> pageFromTaxonRelationships(Taxon taxon
, TaxonRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
286 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
287 * where the supplied synonym is relatedFrom.
289 * @param taxon The synonym that is relatedFrom
290 * @param type The type of SynonymRelationship (can be null)
291 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
292 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
293 * * @param orderHints Properties to order by
294 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
295 * @return a Pager of SynonymRelationship instances
297 public Pager
<SynonymRelationship
> getSynonyms(Synonym synonym
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
300 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
301 * where the supplied taxon is relatedTo.
303 * @param taxon The taxon that is relatedTo
304 * @param type The type of SynonymRelationship (can be null)
305 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
306 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
307 * * @param orderHints Properties to order by
308 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
309 * @return a Pager of SynonymRelationship instances
311 public Pager
<SynonymRelationship
> getSynonyms(Taxon taxon
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
314 * Returns the list of all synonyms that share the same homotypical group with the given taxon.
315 * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
317 * @param propertyPaths
320 public List
<Synonym
> getHomotypicSynonymsByHomotypicGroup(Taxon taxon
, List
<String
> propertyPaths
);
323 * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
324 * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
325 * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
326 * belong to a homotypical group which cannot be the homotypical group to which the
327 * taxon name of the given taxon belongs. This method does not return the homotypic group the given
328 * taxon belongs to.<BR>
329 * This method does neglect the type of synonym relationship that is defined between the given taxon
330 * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
331 * in one of the result lists as long as the synonym does not belong to the same homotypic group as
332 * the given taxon.<BR>
333 * The list returned is ordered according to the date of publication of the
334 * first published name within each homotypical group.
336 * @see #getHeterotypicSynonymyGroups()
337 * @see #getSynonyms()
338 * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
339 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
342 * @param propertyPaths
345 public List
<List
<Synonym
>> getHeterotypicSynonymyGroups(Taxon taxon
, List
<String
> propertyPaths
);
348 * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
350 * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
352 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
353 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
355 * Supports path like <code>orderHints.propertyNames</code> which
356 * include *-to-one properties like createdBy.username or
357 * authorTeam.persistentTitleCache
358 * @param propertyPaths properties to be initialized
359 * @return a Pager Taxon instances
360 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
362 public Pager
<TaxonBase
> search(Class
<?
extends TaxonBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
365 * Returns a list of TaxonBase instances where the
366 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
367 * <i>null</i> will search for those taxa with a value of null in that field
369 * @param clazz optionally filter by class (can be null to return all taxa)
371 * @param infragenericEpithet
372 * @param specificEpithet
373 * @param infraspecificEpithet
375 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
376 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
377 * @return a list of TaxonBase instances
379 public Pager
<TaxonBase
> findTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, Rank rank
, Integer pageSize
, Integer pageNumber
);
382 * Returns a list of TaxonBase instances where the
383 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
384 * <i>null</i> will search for those taxa with a value of null in that field
386 * @param clazz optionally filter by class
388 * @param infragenericEpithet
389 * @param specificEpithet
390 * @param infraspecificEpithet
392 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
393 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
394 * @return a List of TaxonBase instances
396 public List
<TaxonBase
> listTaxaByName(Class
<?
extends TaxonBase
> clazz
, String uninomial
, String infragenericEpithet
, String specificEpithet
, String infraspecificEpithet
, Rank rank
, Integer pageSize
, Integer pageNumber
);
399 * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
400 * that match the properties specified in the configurator.
401 * @param configurator
404 public Pager
<IdentifiableEntity
> findTaxaAndNames(ITaxonServiceConfigurator configurator
);
411 * @param widthOrDuration
415 * FIXME candidate for harmonization - rename to listMedia()
417 public List
<MediaRepresentation
> getAllMedia(Taxon taxon
, int size
, int height
, int widthOrDuration
, String
[] mimeTypes
);
419 public List
<TaxonBase
> findTaxaByID(Set
<Integer
> listOfIDs
);
421 * returns a list of inferred synonyms concerning the taxon with synonymrelationshiptype type
427 public List
<Synonym
> createInferredSynonyms(Classification tree
, Taxon taxon
, SynonymRelationshipType type
);
429 * returns a list of all inferred synonyms (inferred epithet, inferred genus and potential combination) concerning the taxon
434 public List
<Synonym
> createAllInferredSynonyms(Classification tree
, Taxon taxon
);
436 public int countAllRelationships();
438 public List
<TaxonNameBase
> findIdenticalTaxonNames(List
<String
> propertyPath
);
439 public List
<TaxonNameBase
> findIdenticalTaxonNameIds(List
<String
> propertyPath
);
440 public String
getPhylumName(TaxonNameBase name
);
442 public long deleteSynonymRelationships(Synonym syn
);
446 * Removes a synonym.<BR><BR>
448 * In detail it removes
449 * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
450 * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
452 * If <code>removeNameIfPossible</code> is true
453 * it also removes the synonym name if it is not used in any other context
454 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)<BR><BR>
456 * If synonym is <code>null</code> the method has no effect.
460 * @param removeNameIfPossible
461 * @throws DeleteException
463 public void deleteSynonym(Synonym synonym
, Taxon taxon
, boolean removeNameIfPossible
);
467 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
468 * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
470 * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
471 * @param type The type of SynonymRelationship (can be null)
472 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
473 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
474 * @param orderHints Properties to order by
475 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
476 * @param direction The direction of the relationship
477 * @return a List of SynonymRelationship instances
479 public List
<SynonymRelationship
> listSynonymRelationships(
480 TaxonBase taxonBase
, SynonymRelationshipType type
, Integer pageSize
, Integer pageNumber
,
481 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
, Direction direction
);
487 public Taxon
findBestMatchingTaxon(String taxonName
);
489 public Taxon
findBestMatchingTaxon(MatchingTaxonConfigurator config
);
491 public Synonym
findBestMatchingSynonym(String taxonName
);
493 public List
<UuidAndTitleCache
<TaxonBase
>> getUuidAndTitleCacheTaxon();
495 public List
<UuidAndTitleCache
<TaxonBase
>> getUuidAndTitleCacheSynonym();
497 public List
<UuidAndTitleCache
<TaxonBase
>> findTaxaAndNamesForEditor(ITaxonServiceConfigurator configurator
);