tests for getXXXSynonymByGroup #2552
[cdmlib.git] / cdmlib-services / src / main / java / eu / etaxonomy / cdm / api / service / ITaxonService.java
1 // $Id$
2 /**
3 * Copyright (C) 2007 EDIT
4 * European Distributed Institute of Taxonomy
5 * http://www.e-taxonomy.eu
6 *
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.
9 */
10
11 package eu.etaxonomy.cdm.api.service;
12
13 import java.util.List;
14 import java.util.Set;
15
16 import eu.etaxonomy.cdm.api.service.config.ITaxonServiceConfigurator;
17 import eu.etaxonomy.cdm.api.service.config.MatchingTaxonConfigurator;
18 import eu.etaxonomy.cdm.api.service.pager.Pager;
19 import eu.etaxonomy.cdm.model.common.IdentifiableEntity;
20 import eu.etaxonomy.cdm.model.common.OrderedTermVocabulary;
21 import eu.etaxonomy.cdm.model.common.RelationshipBase;
22 import eu.etaxonomy.cdm.model.common.RelationshipBase.Direction;
23 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
24 import eu.etaxonomy.cdm.model.media.MediaRepresentation;
25 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
26 import eu.etaxonomy.cdm.model.name.Rank;
27 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
28 import eu.etaxonomy.cdm.model.reference.Reference;
29 import eu.etaxonomy.cdm.model.taxon.Classification;
30 import eu.etaxonomy.cdm.model.taxon.Synonym;
31 import eu.etaxonomy.cdm.model.taxon.SynonymRelationship;
32 import eu.etaxonomy.cdm.model.taxon.SynonymRelationshipType;
33 import eu.etaxonomy.cdm.model.taxon.Taxon;
34 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
35 import eu.etaxonomy.cdm.model.taxon.TaxonRelationship;
36 import eu.etaxonomy.cdm.model.taxon.TaxonRelationshipType;
37 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
38 import eu.etaxonomy.cdm.persistence.fetch.CdmFetch;
39 import eu.etaxonomy.cdm.persistence.query.OrderHint;
40
41
42 public interface ITaxonService extends IIdentifiableEntityService<TaxonBase>{
43
44 /**
45 * Computes all taxon bases.
46 * @param limit
47 * @param start
48 * @return
49 *
50 * FIXME could substitute with list(Synonym.class, limit, start)
51 */
52 public List<Synonym> getAllSynonyms(int limit, int start);
53
54 /**
55 * Computes all taxon bases.
56 * @param limit
57 * @param start
58 * @return
59 *
60 * FIXME could substitute with list(Taxon.class, limit,start)
61 */
62 public List<Taxon> getAllTaxa(int limit, int start);
63
64 /**
65 * Computes all Taxon instances that do not have a taxonomic parent.
66 * @param sec The concept reference that the taxon belongs to
67 *
68 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
69 * @return The List<Taxon> of root taxa.
70 * @deprecated obsolete when using classification
71 */
72 public List<Taxon> getRootTaxa(Reference sec, CdmFetch cdmFetch, boolean onlyWithChildren);
73
74 /**
75 * Computes all Taxon instances which name is of a certain Rank.
76 * @param rank The rank of the taxon name
77 * @param sec The concept reference that the taxon belongs to
78 * @param onlyWithChildren if true only taxa are returned that have taxonomic children. <Br>Default: true.
79 * @param withMisapplications if false taxa that have at least one misapplied name relationship in which they are
80 * the misapplied name are not returned.<Br>Default: true.
81 * @param propertyPaths
82 * properties to be initialized, For detailed description and
83 * examples <b>please refer to:</b>
84 * {@link BeanInitializer#initialize(Object, List)}. <Br>
85 * Default: true.
86 * @return The List<Taxon> of root taxa.
87 * @deprecated obsolete when using classification
88 */
89 public List<Taxon> getRootTaxa(Rank rank, Reference sec, boolean onlyWithChildren, boolean withMisapplications, List<String> propertyPaths);
90
91 /**
92 * Computes all relationships.
93 * @param limit
94 * @param start
95 * @return
96 * FIXME candidate for harmonization - rename to listRelationships
97 */
98 public List<RelationshipBase> getAllRelationships(int limit, int start);
99
100 /**
101 * Returns TaxonRelationshipType vocabulary
102 * @return
103 * @deprecated use TermService#getVocabulary(VocabularyType) instead
104 */
105 public OrderedTermVocabulary<TaxonRelationshipType> getTaxonRelationshipTypeVocabulary();
106
107 /**
108 * Returns a list of taxa that matches the name string and the sec reference
109 * @param name the name string to search for
110 * @param sec the taxons sec reference
111 * @return a list of taxa matching the name and the sec reference
112 */
113 public List<TaxonBase> searchTaxaByName(String name, Reference sec);
114
115 /**
116 * Swaps given synonym and accepted taxon.
117 * In particular:
118 * <ul>
119 * <li>A new accepted taxon with the synonyms name is created</li>
120 * <li>The synonym is deleted from the old accepted taxons synonym list</li>
121 * <li>A new synonym with the name of the old accepted taxon is created</li>
122 * <li>The newly created synonym get related to the newly created accepted taxon</li>
123 * </ul>
124 *
125 * @param synonym
126 * @param acceptedTaxon
127 * @param synonymRelationshipType the relationship type the newly created synonym will have. Defaults to SYNONYM_OF
128 */
129 public void swapSynonymAndAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon);
130
131 /**
132 * Changes a synonym into an accepted taxon and removes
133 * the synonym relationship to the given accepted taxon.
134 * Other synonyms homotypic to the synonym to change are
135 * moved to the same new accepted taxon as homotypic
136 * synonyms. The new accepted taxon has the same name and
137 * the same sec reference as the old synonym.<BR>
138 * If the given accepted taxon and the synonym are homotypic
139 * to each other an exception may be thrown as taxonomically it doesn't
140 * make sense to have two accepted taxa in the same homotypic group
141 * but also it is than difficult to decide how to handle other names
142 * in the homotypic group. It is up to the implementing class to
143 * handle this situation via an exception or in another way.
144 * TODO Open issue: does the old synonym need to be deleted from the database?
145 *
146 * @param synonym
147 * the synonym to change into an accepted taxon
148 * @param acceptedTaxon
149 * an accepted taxon, the synonym had a relationship to
150 * @param deleteSynonym
151 * if true the method tries to delete the old synonym from the database
152 * @param copyCitationInfo
153 * if true the citation and the microcitation of newly created synonyms
154 * is taken from the old synonym relationships.
155 * @param citation
156 * if given this citation is added to the newly created synonym
157 * relationships as citation. Only used if copyCitationInfo is <code> false</code>
158 * @param microCitation
159 * if given this microCitation is added to the newly created synonym
160 * relationships as microCitation.Only used if copyCitationInfo is <code> false</code>
161 * @return
162 * the newly created accepted taxon
163 * @throws IllegalArgumentException
164 * if the given accepted taxon and the synonym are homotypic
165 * to each other an exception may be thrown as taxonomically it doesn't
166 * make sense to have two accepted taxa in the same homotypic group
167 * but also it is than difficult to decide how to handle other names
168 * in the homotypic group. It is up to the implementing class to
169 * handle this situation via an exception or in another way.
170 */
171 public Taxon changeSynonymToAcceptedTaxon(Synonym synonym, Taxon acceptedTaxon, boolean deleteSynonym, boolean copyCitationInfo, Reference citation, String microCitation) throws IllegalArgumentException;
172
173 /**
174 * TODO still needed and correct?
175 * Change a synonym into a related concept
176 *
177 * @param synonym
178 * the synonym to change into the concept taxon
179 * @param toTaxon
180 * the taxon the newly created concept should be related to
181 * @param taxonRelationshipType
182 * the type of relationship
183 * @param reference
184 * @param microReference
185 * @return
186 * the newly created concept
187 */
188 public Taxon changeSynonymToRelatedTaxon(Synonym synonym, Taxon toTaxon, TaxonRelationshipType taxonRelationshipType, Reference reference, String microReference);
189
190
191 /**
192 * Changes the homotypic group of a synonym into the new homotypic group.
193 * All relations to taxa are updated correctly depending on the homotypic
194 * group of the accepted taxon. <BR>
195 * All existing basionym relationships to and from this name are removed.<BR>
196 * If the parameter <code>targetTaxon</code> is defined, the synonym is
197 * added to this taxon irrespctive of if it has been related to this
198 * taxon before.<BR>
199 * If <code>removeFromOtherTaxa</code> is true and <code>targetTaxon</code> is
200 * defined all relationships to other taxa are deleted.<BR>
201 * If <code>setBasionymRelationIfApplicable</code> is true a basionym relationship
202 * between the existing basionym(s) of the new homotypic group and the synonyms name
203 * is added.<BR>
204 *
205 * @param synonym
206 * @param newHomotypicalGroup
207 * @param taxon
208 * @param setBasionymRelationIfApplicable
209 */
210 public void changeHomotypicalGroupOfSynonym(Synonym synonym, HomotypicalGroup newHomotypicalGroup, Taxon targetTaxon,
211 boolean removeFromOtherTaxa, boolean setBasionymRelationIfApplicable);
212
213
214 /**
215 * Move a synonym to another taxon, effectively removing the old synonym relationship
216 *
217 * @param synonymRelation
218 * @param toTaxon
219 * @param reference
220 * @param referenceDetail
221 * @return
222 */
223 public Taxon moveSynonymToAnotherTaxon(SynonymRelationship synonymRelation, Taxon toTaxon, SynonymRelationshipType synonymRelationshipType, Reference reference, String referenceDetail);
224
225 /**
226 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
227 * where the supplied taxon is relatedTo.
228 *
229 * @param taxon The taxon that is relatedTo
230 * @param type The type of TaxonRelationship (can be null)
231 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
232 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
233 * @param orderHints Properties to order by
234 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
235 * @return a List of TaxonRelationship instances
236 */
237 public List<TaxonRelationship> listToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
238
239
240
241 /**
242 * Returns the TaxonRelationships (of where relationship.type == type, if this arguement is supplied)
243 * where the supplied taxon is relatedTo.
244 *
245 * @param taxon The taxon that is relatedTo
246 * @param type The type of TaxonRelationship (can be null)
247 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
248 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
249 * @param orderHints Properties to order by
250 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
251 * @return a Pager of TaxonRelationship instances
252 */
253 public Pager<TaxonRelationship> pageToTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
254
255 /**
256 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
257 * where the supplied taxon is relatedFrom.
258 *
259 * @param taxon The taxon that is relatedFrom
260 * @param type The type of TaxonRelationship (can be null)
261 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
262 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
263 * @param orderHints Properties to order by
264 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
265 * @return a List of TaxonRelationship instances
266 */
267 public List<TaxonRelationship> listFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
268
269
270 /**
271 * Returns the TaxonRelationships (of where relationship.type == type, if this argument is supplied)
272 * where the supplied taxon is relatedFrom.
273 *
274 * @param taxon The taxon that is relatedFrom
275 * @param type The type of TaxonRelationship (can be null)
276 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
277 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
278 * @param orderHints Properties to order by
279 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
280 * @return a Pager of TaxonRelationship instances
281 */
282 public Pager<TaxonRelationship> pageFromTaxonRelationships(Taxon taxon, TaxonRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
283
284 /**
285 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
286 * where the supplied synonym is relatedFrom.
287 *
288 * @param taxon The synonym that is relatedFrom
289 * @param type The type of SynonymRelationship (can be null)
290 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
291 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
292 * * @param orderHints Properties to order by
293 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
294 * @return a Pager of SynonymRelationship instances
295 */
296 public Pager<SynonymRelationship> getSynonyms(Synonym synonym, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
297
298 /**
299 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
300 * where the supplied taxon is relatedTo.
301 *
302 * @param taxon The taxon that is relatedTo
303 * @param type The type of SynonymRelationship (can be null)
304 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
305 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
306 * * @param orderHints Properties to order by
307 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
308 * @return a Pager of SynonymRelationship instances
309 */
310 public Pager<SynonymRelationship> getSynonyms(Taxon taxon, SynonymRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
311
312 /**
313 * Returns the list of all synonyms that share the same homotypical group with the given taxon.
314 * Only those homotypic synonyms are returned that do have a synonym relationship with the accepted taxon.
315 * @param taxon
316 * @param propertyPaths
317 * @return
318 */
319 public List<Synonym> getHomotypicSynonymsByHomotypicGroup(Taxon taxon, List<String> propertyPaths);
320
321 /**
322 * Returns the ordered list of all {@link eu.etaxonomy.cdm.model.name.HomotypicalGroup homotypical groups}
323 * that contain {@link Synonym synonyms} that are heterotypic to the given taxon.
324 * {@link eu.etaxonomy.cdm.model.name.TaxonNameBase Taxon names} of heterotypic synonyms
325 * belong to a homotypical group which cannot be the homotypical group to which the
326 * taxon name of the given taxon belongs. This method does not return the homotypic group the given
327 * taxon belongs to.<BR>
328 * This method does neglect the type of synonym relationship that is defined between the given taxon
329 * and the synonym. So the synonym relationship may be homotypic however a synonym is returned
330 * in one of the result lists as long as the synonym does not belong to the same homotypic group as
331 * the given taxon.<BR>
332 * The list returned is ordered according to the date of publication of the
333 * first published name within each homotypical group.
334 *
335 * @see #getHeterotypicSynonymyGroups()
336 * @see #getSynonyms()
337 * @see SynonymRelationshipType#HETEROTYPIC_SYNONYM_OF()
338 * @see eu.etaxonomy.cdm.model.name.HomotypicalGroup
339
340 * @param taxon
341 * @param propertyPaths
342 * @return
343 */
344 public List<List<Synonym>> getHeterotypicSynonymyGroups(Taxon taxon, List<String> propertyPaths);
345
346 /**
347 * Returns a Paged List of TaxonBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
348 *
349 * @param clazz filter the results by class (or pass null to return all TaxonBase instances)
350 * @param queryString
351 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
352 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
353 * @param orderHints
354 * Supports path like <code>orderHints.propertyNames</code> which
355 * include *-to-one properties like createdBy.username or
356 * authorTeam.persistentTitleCache
357 * @param propertyPaths properties to be initialized
358 * @return a Pager Taxon instances
359 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
360 */
361 public Pager<TaxonBase> search(Class<? extends TaxonBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
362
363 /**
364 * Returns a list of TaxonBase instances where the
365 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
366 * <i>null</i> will search for those taxa with a value of null in that field
367 *
368 * @param clazz optionally filter by class (can be null to return all taxa)
369 * @param uninomial
370 * @param infragenericEpithet
371 * @param specificEpithet
372 * @param infraspecificEpithet
373 * @param rank
374 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
375 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
376 * @return a list of TaxonBase instances
377 */
378 public Pager<TaxonBase> findTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
379
380 /**
381 * Returns a list of TaxonBase instances where the
382 * taxon.name properties match the parameters passed. In order to search for any string value, pass '*', passing the string value of
383 * <i>null</i> will search for those taxa with a value of null in that field
384 *
385 * @param clazz optionally filter by class
386 * @param uninomial
387 * @param infragenericEpithet
388 * @param specificEpithet
389 * @param infraspecificEpithet
390 * @param rank
391 * @param pageSize The maximum number of taxa returned (can be null for all matching taxa)
392 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
393 * @return a List of TaxonBase instances
394 */
395 public List<TaxonBase> listTaxaByName(Class<? extends TaxonBase> clazz, String uninomial, String infragenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber);
396
397 /**
398 * Returns a list of IdentifiableEntity instances (in particular, TaxonNameBase and TaxonBase instances)
399 * that match the properties specified in the configurator.
400 * @param configurator
401 * @return
402 */
403 public Pager<IdentifiableEntity> findTaxaAndNames(ITaxonServiceConfigurator configurator);
404
405 /**
406 *
407 * @param taxon
408 * @param size
409 * @param height
410 * @param widthOrDuration
411 * @param mimeTypes
412 * @return
413 *
414 * FIXME candidate for harmonization - rename to listMedia()
415 */
416 public List<MediaRepresentation> getAllMedia(Taxon taxon, int size, int height, int widthOrDuration, String[] mimeTypes);
417
418 public List<TaxonBase> findTaxaByID(Set<Integer> listOfIDs);
419 /**
420 * returns a list of inferred synonyms concerning the taxon with synonymrelationshiptype type
421 * @param tree
422 * @param taxon
423 * @param type
424 * @return
425 */
426 public List<Synonym> createInferredSynonyms(Classification tree, Taxon taxon, SynonymRelationshipType type);
427 /**
428 * returns a list of all inferred synonyms (inferred epithet, inferred genus and potential combination) concerning the taxon
429 * @param tree
430 * @param taxon
431 * @return
432 */
433 public List<Synonym> createAllInferredSynonyms(Classification tree, Taxon taxon);
434
435 public int countAllRelationships();
436
437 public List<TaxonNameBase> findIdenticalTaxonNames(List<String> propertyPath);
438 public List<TaxonNameBase> findIdenticalTaxonNameIds(List<String> propertyPath);
439 public String getPhylumName(TaxonNameBase name);
440
441 public long deleteSynonymRelationships(Synonym syn);
442
443
444 /**
445 * Removes a synonym.
446 *
447 * In detail it removes
448 * <li>all synonym relationship to the given taxon or to all taxa if taxon is <code>null</code></li>
449 * <li>the synonym concept if it is not referenced by any synonym relationship anymore</li>
450 * <BR><BR>
451 * If <code>removeNameIfPossible</code> is true
452 * it also removes the synonym name if it is not used in any other context
453 * (part of a concept, in DescriptionElementSource, part of a name relationship, used inline, ...)
454 *
455 * @param taxon
456 * @param synonym
457 * @param removeNameIfPossible
458 */
459 public void deleteSynonym(Synonym synonym, Taxon taxon, boolean removeNameIfPossible);
460
461
462 /**
463 * Returns the SynonymRelationships (of where relationship.type == type, if this argument is supplied)
464 * depending on direction, where the supplied taxon is relatedTo or the supplied synonym is relatedFrom.
465 *
466 * @param taxonBase The taxon or synonym that is relatedTo or relatedFrom
467 * @param type The type of SynonymRelationship (can be null)
468 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
469 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
470 * @param orderHints Properties to order by
471 * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}
472 * @param direction The direction of the relationship
473 * @return a List of SynonymRelationship instances
474 */
475 public List<SynonymRelationship> listSynonymRelationships(
476 TaxonBase taxonBase, SynonymRelationshipType type, Integer pageSize, Integer pageNumber,
477 List<OrderHint> orderHints, List<String> propertyPaths, Direction direction);
478
479 /**
480 * @param tnb
481 * @return
482 */
483 public Taxon findBestMatchingTaxon(String taxonName);
484
485 public Taxon findBestMatchingTaxon(MatchingTaxonConfigurator config);
486
487 public Synonym findBestMatchingSynonym(String taxonName);
488
489 public List<UuidAndTitleCache<TaxonBase>> getUuidAndTitleCacheTaxon();
490
491 public List<UuidAndTitleCache<TaxonBase>> getUuidAndTitleCacheSynonym();
492
493 public List<UuidAndTitleCache<TaxonBase>> findTaxaAndNamesForEditor(ITaxonServiceConfigurator configurator);
494
495 }