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