remove harmonization candidates in TaxonDao and NameService
[cdmlib.git] / cdmlib-services / src / main / java / eu / etaxonomy / cdm / api / service / INameService.java
1 /**
2 * Copyright (C) 2007 EDIT
3 * European Distributed Institute of Taxonomy
4 * http://www.e-taxonomy.eu
5 *
6 * The contents of this file are subject to the Mozilla Public License Version 1.1
7 * See LICENSE.TXT at the top of this package for the full license terms.
8 */
9
10 package eu.etaxonomy.cdm.api.service;
11
12 import java.io.IOException;
13 import java.util.Collection;
14 import java.util.HashMap;
15 import java.util.List;
16 import java.util.Map;
17 import java.util.Optional;
18 import java.util.UUID;
19
20 import org.apache.lucene.index.CorruptIndexException;
21 import org.hibernate.criterion.Criterion;
22
23 import eu.etaxonomy.cdm.api.service.config.NameDeletionConfigurator;
24 import eu.etaxonomy.cdm.api.service.pager.Pager;
25 import eu.etaxonomy.cdm.api.service.search.DocumentSearchResult;
26 import eu.etaxonomy.cdm.api.service.search.LuceneParseException;
27 import eu.etaxonomy.cdm.api.service.search.SearchResult;
28 import eu.etaxonomy.cdm.api.utility.TaxonNamePartsFilter;
29 import eu.etaxonomy.cdm.model.common.Language;
30 import eu.etaxonomy.cdm.model.common.ReferencedEntityBase;
31 import eu.etaxonomy.cdm.model.common.RelationshipBase;
32 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
33 import eu.etaxonomy.cdm.model.name.HybridRelationship;
34 import eu.etaxonomy.cdm.model.name.HybridRelationshipType;
35 import eu.etaxonomy.cdm.model.name.INonViralName;
36 import eu.etaxonomy.cdm.model.name.NameRelationship;
37 import eu.etaxonomy.cdm.model.name.NameRelationshipType;
38 import eu.etaxonomy.cdm.model.name.NomenclaturalStatus;
39 import eu.etaxonomy.cdm.model.name.Rank;
40 import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignationStatus;
41 import eu.etaxonomy.cdm.model.name.TaxonName;
42 import eu.etaxonomy.cdm.model.name.TypeDesignationBase;
43 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
44 import eu.etaxonomy.cdm.persistence.dto.TaxonNameParts;
45 import eu.etaxonomy.cdm.persistence.dto.UuidAndTitleCache;
46 import eu.etaxonomy.cdm.persistence.query.MatchMode;
47 import eu.etaxonomy.cdm.persistence.query.OrderHint;
48 import eu.etaxonomy.cdm.strategy.cache.TaggedText;
49 import eu.etaxonomy.cdm.strategy.parser.NonViralNameParserImpl;
50
51 public interface INameService extends IIdentifiableEntityService<TaxonName> {
52
53 /**
54 * Deletes a name. Depening on the configurator state links to the name will either be
55 * deleted or throw exceptions.<BR>
56 * If name is <code>null</code> this method has no effect.
57 * @param name
58 * @param config
59 *
60 */
61 public DeleteResult delete(UUID nameUUID, NameDeletionConfigurator config);
62
63 /**
64 * Removes the given type designation from the given taxon name and deletes it from
65 * the database if it is not connected to any other name.
66 * If <code>typeDesignation</code> is <code>null</code> all type designations are deleted
67 * from the given taxon name. If <code>name</code> is <code>null</code> all names are removed from
68 * the given type designation. If both are <code>null</code> nothing happens.
69 * @param typeDesignation
70 * @param name
71 * @return
72 */
73 public DeleteResult deleteTypeDesignation(TaxonName name, TypeDesignationBase typeDesignation);
74
75 /**
76 * Removes the given type designation from the given taxon name and deletes it from
77 * the database if it is not connected to any other name.
78 * If <code>typeDesignation</code> is <code>null</code> all type designations are deleted
79 * from the given taxon name. If <code>name</code> is <code>null</code> all names are removed from
80 * the given type designation. If both are <code>null</code> nothing happens.
81 * @param typeDesignation
82 * @param name
83 * @return
84 */
85 public DeleteResult deleteTypeDesignation(UUID nameUuid, UUID typeDesignationUuid);
86
87
88 /**
89 * Saves the given type designations.
90 * @param typeDesignationCollection
91 * @return
92 */
93 public Map<UUID, TypeDesignationBase> saveTypeDesignationAll(Collection<TypeDesignationBase> typeDesignationCollection);
94
95 public Map<UUID, ReferencedEntityBase> saveReferencedEntitiesAll(Collection<ReferencedEntityBase> referencedEntityCollection);
96
97 /**
98 * Saves the given homotypical groups.
99 * @param homotypicalGroups
100 * @return
101 */
102 public Map<UUID, HomotypicalGroup> saveAllHomotypicalGroups(Collection<HomotypicalGroup> homotypicalGroups);
103
104 /**
105 * Returns all nomenclatural status.
106 * @param limit
107 * @param start
108 * @return
109 */
110 public List<NomenclaturalStatus> getAllNomenclaturalStatus(int limit, int start);
111
112 /**
113 * Returns all type designations.
114 * @param limit
115 * @param start
116 * @return
117 */
118 public List<TypeDesignationBase> getAllTypeDesignations(int limit, int start);
119
120 public TypeDesignationBase loadTypeDesignation(int id, List<String> propertyPaths);
121
122 public TypeDesignationBase loadTypeDesignation(UUID uuid, List<String> propertyPaths);
123
124 /**
125 * Returns all NonViralNames with a name cache that matches the given string
126 * @param name
127 * @return
128 */
129 public List<TaxonName> getNamesByNameCache(String nameCache);
130
131 /**
132 * Returns all NonViralNames with a title cache that matches the given string
133 * using the given match mode and initialization strategy
134 *
135 * @param name
136 * @param matchMode
137 * @param propertyPaths
138 * @return
139 */
140 public List<TaxonName> findNamesByTitleCache(String titleCache, MatchMode matchMode, List<String> propertyPaths);
141
142 /**
143 * Supports using wildcards in the query parameters.
144 * If a name part passed to the method contains the asterisk character ('*') it will be translated into '%' the related field is search with a LIKE clause.
145 * <p>
146 * A query parameter which is passed as <code>NULL</code> value will be ignored. A parameter passed as {@link Optional} object containing a <code>NULL</code> value will be used
147 * to filter select taxon names where the according field is <code>null</code>.
148 *
149 * @param filter
150 * @param infraGenericEpithet
151 * @param specificEpithet
152 * @param infraSpecificEpithet
153 * @param rank
154 * Only names having the specified rank are taken into account.
155 * @return
156 */
157 public Pager<TaxonNameParts> findTaxonNameParts(Optional<String> genusOrUninomial,
158 Optional<String> infraGenericEpithet, Optional<String> specificEpithet,
159 Optional<String> infraSpecificEpithet, Rank rank, Integer pageSize, Integer pageIndex, List<OrderHint> orderHints);
160
161 /**
162 * <b>This method behaves differently compared to {@link #findTaxonNameParts(Optional, Optional, Optional, Optional, Rank, Integer, Integer, List)}!</b>
163 * <p>
164 * The {@link TaxonNamePartsFilter} defines the rank and fixed name parts for the search process.
165 * For example: In case the <code>rank</code> is "genus", the <code>genusOrUninomial</code> will be used as search parameter which needs to match exactly.
166 * The <code>namePartQueryString</code> will be used to do a wildcard search on the specificEpithet.
167 * <p>
168 * For name part lookup purposes the <code>TaxonNameParts</code> in the result list can be asked to return the relavant name part by
169 * calling {@link TaxonNameParts#nameRankSpecificNamePart(TaxonName)}
170 *
171 *
172 * @param filter
173 * @return
174 */
175 public Pager<TaxonNameParts> findTaxonNameParts(TaxonNamePartsFilter filter, String namePartQueryString, Integer pageSize, Integer pageIndex, List<OrderHint> orderHints);
176
177 /**
178 * Returns all NonViralNames with a name cache that matches the given string
179 * using the given match mode and initialization strategy
180 *
181 * @param name
182 * @param matchMode
183 * @param propertyPaths
184 * @return
185 */
186 public List<TaxonName> findNamesByNameCache(String nameCache, MatchMode matchMode, List<String> propertyPaths);
187
188 /**
189 * Fuzzy matching for the taxon name elements. The input name is first atomised using the {@link NonViralNameParserImpl}
190 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
191 * Each field is then matched separately with the same accuracy parameter.
192 *
193 * @param name taxon name to fuzzy match
194 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
195 * @param languages list of languages to consider when matching (currently not used)
196 * @param highlightFragments
197 * @param propertyPaths
198 * @param maxNoOfResults
199 * @return
200 * @throws CorruptIndexException
201 * @throws IOException
202 * @throws ParseException
203 */
204 public List<SearchResult<TaxonName>> findByNameFuzzySearch(
205 String name,
206 float accuracy,
207 List<Language> languages,
208 boolean highlightFragments,
209 List<String> propertyPaths,
210 int maxNoOfResults) throws IOException, LuceneParseException;
211
212 /**
213 * Fuzzy matching for the taxon name elements using only the lucene index.
214 *
215 * The input name is first atomised using the {@link NonViralNameParserImpl}
216 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
217 * Each field is then matched separately with the same accuracy parameter.
218 *
219 * @param name taxon name to fuzzy match
220 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
221 * @param languages list of languages to consider when matching (currently not used)
222 * @param highlightFragments
223 * @param maxNoOfResults
224 * @return
225 * @throws CorruptIndexException
226 * @throws IOException
227 * @throws ParseException
228 */
229 public List<DocumentSearchResult> findByNameFuzzySearch(
230 String name,
231 float accuracy,
232 List<Language> languages,
233 boolean highlightFragments,
234 int maxNoOfResults) throws IOException, LuceneParseException;
235
236 /**
237 * Fuzzy matching against the name cache using only the lucene index.
238 *
239 *
240 * @param name taxon name to fuzzy match
241 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
242 * @param languages list of languages to consider when matching (currently not used)
243 * @param highlightFragments
244 * @param maxNoOfResults
245 * @return
246 * @throws CorruptIndexException
247 * @throws IOException
248 * @throws ParseException
249 */
250 public List<DocumentSearchResult> findByFuzzyNameCacheSearch(
251 String name,
252 float accuracy,
253 List<Language> languages,
254 boolean highlightFragments,
255 int maxNoOfResults) throws IOException, LuceneParseException;
256
257 /**
258 * Exact matching for the taxon name elements using only the lucene index.
259 *
260 * The input name is first atomised using the {@link NonViralNameParserImpl}
261 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
262 * Each field is then matched separately with the same accuracy parameter.
263 *
264 * @param name taxon name to fuzzy match
265 * @param wildcard boolean flag to indicate whether a wildcard '*' should be added at the end of the query
266 * @param languages list of languages to consider when matching (currently not used)
267 * @param highlightFragments
268 * @param maxNoOfResults
269 * @return
270 * @throws CorruptIndexException
271 * @throws IOException
272 * @throws ParseException
273 */
274
275 public List<DocumentSearchResult> findByNameExactSearch(
276 String name,
277 boolean wildcard,
278 List<Language> languages,
279 boolean highlightFragments,
280 int maxNoOfResults) throws IOException, LuceneParseException;
281
282 // TODO: Remove getNamesByName() methods. Use findNamesByTitle() instead.
283
284 public List<HomotypicalGroup> getAllHomotypicalGroups(int limit, int start);
285
286 @Deprecated
287 public List<RelationshipBase> getAllRelationships(int limit, int start);
288
289
290 /**
291 * Return a List of name relationships in which this name is related to
292 * another name, optionally filtered by relationship type
293 *
294 * @param name
295 * the name on either the <i>"from side"</i> or on the
296 * <i>"to side"</i> of the relationship, depending on the
297 * <code>direction</code> of the relationship.
298 * @param direction
299 * the direction of the NameRelationship, may be null to return all relationships
300 * @param type
301 * the relationship type (or null to return all relationships)
302 * @param pageSize
303 * The maximum number of relationships returned (can be null for
304 * all relationships)
305 * @param pageNumber
306 * The offset (in pageSize chunks) from the start of the result
307 * set (0 - based)
308 * @param orderHints
309 * may be null
310 * @param propertyPaths
311 * properties to initialize - see
312 * {@link IBeanInitializer#initialize(Object, List)}
313 * @return a Pager of NameRelationship instances
314 */
315 public List<NameRelationship> listNameRelationships(TaxonName name, NameRelationship.Direction direction, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
316
317 /**
318 * Return a List of name relationships in which this name is related to another name, optionally filtered
319 * by relationship type
320 *
321 * @param name the name on the <i>"from side"</i> of the relationship
322 * @param direction the direction of the NameRelationship
323 * @param type the relationship type (or null to return all relationships)
324 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
325 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
326 * @param orderHints may be null
327 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
328 * @return a Pager of NameRelationship instances
329 */
330 public Pager<NameRelationship> pageNameRelationships(TaxonName name, NameRelationship.Direction direction, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
331
332 /**
333 * Return a List of relationships in which this name is related to another name, optionally filtered
334 * by relationship type
335 *
336 * @param name the name on the <i>"from side"</i> of the relationship
337 * @param type the relationship type (or null to return all relationships)
338 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
339 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
340 * @param orderHints may be null
341 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
342 * @return a Pager of NameRelationship instances
343 * @deprecated use {@link #listNameRelationships(TaxonName, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
344 */
345 @Deprecated
346 public List<NameRelationship> listFromNameRelationships(TaxonName name, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
347
348 /**
349 * Return a List of relationships in which this name is related to another name, optionally filtered
350 * by relationship type
351 *
352 * @param name the name on the <i>"from side"</i> of the relationship
353 * @param type the relationship type (or null to return all relationships)
354 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
355 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
356 * @param orderHints may be null
357 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
358 * @return a Pager of NameRelationship instances
359 * @deprecated use {@link #pageNameRelationships(TaxonName, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
360 */
361 @Deprecated
362 public Pager<NameRelationship> pageFromNameRelationships(TaxonName name, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
363
364 /**
365 * Return a List of relationships in which another name is related to this name, optionally filtered
366 * by relationship type
367 *
368 * @param name the name on the <i>"to side"</i> of the relationship
369 * @param type the relationship type (or null to return all relationships)
370 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
371 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
372 * @param orderHints may be null
373 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
374 * @return a Pager of NameRelationship instances
375 * @deprecated use {@link #listNameRelationships(TaxonName, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
376 */
377 @Deprecated
378 public List<NameRelationship> listToNameRelationships(TaxonName name, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
379
380 /**
381 * Return a List of relationships in which another name is related to this name, optionally filtered
382 * by relationship type
383 *
384 * @param name the name on the <i>"to side"</i> of the relationship
385 * @param type the relationship type (or null to return all relationships)
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 may be null
389 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
390 * @return a Pager of NameRelationship instances
391 * @deprecated use {@link #pageNameRelationships(TaxonName, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
392 */
393 @Deprecated
394 public Pager<NameRelationship> pageToNameRelationships(TaxonName name, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
395
396
397 /**
398 * Return a List of hybrids related to this name, optionally filtered
399 * by hybrid relationship type
400 *
401 * @param name the name
402 * @param type the hybrid relationship type (or null to return all hybrids)
403 * @param pageSize The maximum number of hybrid relationships returned (can be null for all relationships)
404 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
405 * @param orderHints may be null
406 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
407 * @return a Pager of HybridRelationship instances
408 */
409 public Pager<HybridRelationship> getHybridNames(INonViralName name, HybridRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
410
411 /**
412 * Return a List of types related to this name, optionally filtered
413 * by type designation status
414 *
415 * @param name the name
416 * @param status the type designation status (or null to return all types)
417 * @param pageSize The maximum number of types returned (can be null for all types)
418 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
419 * @return a Pager of TypeDesignationBase instances
420 */
421 public Pager<TypeDesignationBase> getTypeDesignations(TaxonName name,
422 SpecimenTypeDesignationStatus status, Integer pageSize, Integer pageNumber);
423
424 public Pager<TypeDesignationBase> getTypeDesignations(TaxonName name,
425 SpecimenTypeDesignationStatus status, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
426
427
428 /**
429 * Returns a List of TaxonName instances that match the properties passed
430 *
431 * @param uninomial
432 * @param infraGenericEpithet
433 * @param specificEpithet
434 * @param infraspecificEpithet
435 * @param rank
436 * @param pageSize The maximum number of names returned (can be null for all names)
437 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
438 * @param orderHints may be null
439 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
440 * @return a Pager of TaxonName instances
441 */
442 public Pager<TaxonName> searchNames(String uninomial, String infraGenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
443
444 /**
445 * Returns a Paged List of TaxonName instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
446 *
447 * @param clazz filter the results by class (or pass null to return all TaxonName instances)
448 * @param queryString
449 * @param pageSize The maximum number of names returned (can be null for all matching names)
450 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
451 * @param orderHints
452 * Supports path like <code>orderHints.propertyNames</code> which
453 * include *-to-one properties like createdBy.username or
454 * authorTeam.persistentTitleCache
455 * @param propertyPaths properties to be initialized
456 * @return a Pager TaxonName instances
457 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
458 */
459 @Override
460 public Pager<TaxonName> search(Class<? extends TaxonName> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
461
462 /**
463 * Returns a map that holds uuid, titleCache pairs of all names in the current database
464 *
465 * @return
466 * a <code>Map</code> containing uuid and titleCache of names
467 */
468 public List<UuidAndTitleCache> getUuidAndTitleCacheOfNames(Integer limit, String pattern);
469
470 /**
471 * Return a Pager of names matching the given query string, optionally filtered by class, optionally with a particular MatchMode
472 *
473 * @param clazz filter by class - can be null to include all instances of type T
474 * @param queryString the query string to filter by
475 * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
476 * @param criteria additional criteria to filter by
477 * @param pageSize The maximum number of objects returned (can be null for all objects)
478 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
479 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
480 * @param orderHints
481 * Supports path like <code>orderHints.propertyNames</code> which
482 * include *-to-one properties like createdBy.username or
483 * authorTeam.persistentTitleCache
484 * @return a paged list of instances of type T matching the queryString
485 */
486 public Pager<TaxonName> findByName(Class<? extends TaxonName> clazz, String queryString,MatchMode matchmode, List<Criterion> criteria, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
487
488 /**
489 * Returns a homotypical group with the given UUID or null if not homotypical group exists with that UUID
490 *
491 * @param uuid the uuid of the homotypical group
492 * @return a homotypical group
493 */
494 public HomotypicalGroup findHomotypicalGroup(UUID uuid);
495
496 /**
497 * @param uuid
498 * @return
499 */
500 public List<TaggedText> getTaggedName(UUID uuid);
501
502 /**
503 * @param nameUuid
504 * @return
505 */
506 public UpdateResult setAsGroupsBasionym(UUID nameUuid);
507
508 public List<HashMap<String, String>> getNameRecords();
509
510 /**
511 * @param name
512 * @param config
513 * @return
514 */
515 DeleteResult delete(TaxonName name, NameDeletionConfigurator config);
516
517
518 }