2 * Copyright (C) 2007 EDIT
3 * European Distributed Institute of Taxonomy
4 * http://www.e-taxonomy.eu
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.
10 package eu
.etaxonomy
.cdm
.api
.service
;
12 import java
.io
.IOException
;
13 import java
.util
.Collection
;
14 import java
.util
.HashMap
;
15 import java
.util
.List
;
17 import java
.util
.Optional
;
18 import java
.util
.UUID
;
20 import org
.apache
.lucene
.index
.CorruptIndexException
;
21 import org
.hibernate
.criterion
.Criterion
;
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
;
51 public interface INameService
52 extends IIdentifiableEntityService
<TaxonName
> {
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.
62 public DeleteResult
delete(UUID nameUUID
, NameDeletionConfigurator config
);
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
74 public DeleteResult
deleteTypeDesignation(TaxonName name
, TypeDesignationBase typeDesignation
);
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
86 public DeleteResult
deleteTypeDesignation(UUID nameUuid
, UUID typeDesignationUuid
);
90 * Saves the given type designations.
91 * @param typeDesignationCollection
94 public Map
<UUID
, TypeDesignationBase
> saveTypeDesignationAll(Collection
<TypeDesignationBase
> typeDesignationCollection
);
96 public Map
<UUID
, ReferencedEntityBase
> saveReferencedEntitiesAll(Collection
<ReferencedEntityBase
> referencedEntityCollection
);
99 * Saves the given homotypical groups.
100 * @param homotypicalGroups
103 public Map
<UUID
, HomotypicalGroup
> saveAllHomotypicalGroups(Collection
<HomotypicalGroup
> homotypicalGroups
);
106 * Returns all nomenclatural status.
111 public List
<NomenclaturalStatus
> getAllNomenclaturalStatus(int limit
, int start
);
114 * Returns all type designations.
119 public List
<TypeDesignationBase
> getAllTypeDesignations(int limit
, int start
);
121 public TypeDesignationBase
loadTypeDesignation(int id
, List
<String
> propertyPaths
);
123 public TypeDesignationBase
loadTypeDesignation(UUID uuid
, List
<String
> propertyPaths
);
126 * Returns all NonViralNames with a name cache that matches the given string
130 public List
<TaxonName
> getNamesByNameCache(String nameCache
);
133 * Returns all NonViralNames with a title cache that matches the given string
134 * using the given match mode and initialization strategy
138 * @param propertyPaths
141 public List
<TaxonName
> findNamesByTitleCache(String titleCache
, MatchMode matchMode
, List
<String
> propertyPaths
);
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.
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>.
151 * @param infraGenericEpithet
152 * @param specificEpithet
153 * @param infraSpecificEpithet
155 * Only names having the specified rank are taken into account.
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
);
163 * <b>This method behaves differently compared to {@link #findTaxonNameParts(Optional, Optional, Optional, Optional, Rank, Integer, Integer, List)}!</b>
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.
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)}
176 public Pager
<TaxonNameParts
> findTaxonNameParts(TaxonNamePartsFilter filter
, String namePartQueryString
, Integer pageSize
, Integer pageIndex
, List
<OrderHint
> orderHints
);
179 * Returns all NonViralNames with a name cache that matches the given string
180 * using the given match mode and initialization strategy
184 * @param propertyPaths
187 public List
<TaxonName
> findNamesByNameCache(String nameCache
, MatchMode matchMode
, List
<String
> propertyPaths
);
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.
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
201 * @throws CorruptIndexException
202 * @throws IOException
203 * @throws ParseException
205 public List
<SearchResult
<TaxonName
>> findByNameFuzzySearch(
208 List
<Language
> languages
,
209 boolean highlightFragments
,
210 List
<String
> propertyPaths
,
211 int maxNoOfResults
) throws IOException
, LuceneParseException
;
214 * Fuzzy matching for the taxon name elements using only the lucene index.
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.
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
226 * @throws CorruptIndexException
227 * @throws IOException
228 * @throws ParseException
230 public List
<DocumentSearchResult
> findByNameFuzzySearch(
233 List
<Language
> languages
,
234 boolean highlightFragments
,
235 int maxNoOfResults
) throws IOException
, LuceneParseException
;
238 * Fuzzy matching against the name cache using only the lucene index.
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
247 * @throws CorruptIndexException
248 * @throws IOException
249 * @throws ParseException
251 public List
<DocumentSearchResult
> findByFuzzyNameCacheSearch(
254 List
<Language
> languages
,
255 boolean highlightFragments
,
256 int maxNoOfResults
) throws IOException
, LuceneParseException
;
259 * Exact matching for the taxon name elements using only the lucene index.
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.
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
271 * @throws CorruptIndexException
272 * @throws IOException
273 * @throws ParseException
276 public List
<DocumentSearchResult
> findByNameExactSearch(
279 List
<Language
> languages
,
280 boolean highlightFragments
,
281 int maxNoOfResults
) throws IOException
, LuceneParseException
;
283 // TODO: Remove getNamesByName() methods. Use findNamesByTitle() instead.
285 public List
<HomotypicalGroup
> getAllHomotypicalGroups(int limit
, int start
);
288 public List
<RelationshipBase
> getAllRelationships(int limit
, int start
);
292 * Return a List of name relationships in which this name is related to
293 * another name, optionally filtered by relationship type
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.
300 * the direction of the NameRelationship, may be null to return all relationships
302 * the relationship type (or null to return all relationships)
304 * The maximum number of relationships returned (can be null for
307 * The offset (in pageSize chunks) from the start of the result
311 * @param propertyPaths
312 * properties to initialize - see
313 * {@link IBeanInitializer#initialize(Object, List)}
314 * @return a Pager of NameRelationship instances
316 public List
<NameRelationship
> listNameRelationships(TaxonName name
, NameRelationship
.Direction direction
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
319 * Return a List of name relationships in which this name is related to another name, optionally filtered
320 * by relationship type
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
331 public Pager
<NameRelationship
> pageNameRelationships(TaxonName name
, NameRelationship
.Direction direction
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
334 * Return a List of relationships in which this name is related to another name, optionally filtered
335 * by relationship type
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
347 public List
<NameRelationship
> listFromNameRelationships(TaxonName name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
350 * Return a List of relationships in which this name is related to another name, optionally filtered
351 * by relationship type
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
363 public Pager
<NameRelationship
> pageFromNameRelationships(TaxonName name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
366 * Return a List of relationships in which another name is related to this name, optionally filtered
367 * by relationship type
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
379 public List
<NameRelationship
> listToNameRelationships(TaxonName name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
382 * Return a List of relationships in which another name is related to this name, optionally filtered
383 * by relationship type
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
395 public Pager
<NameRelationship
> pageToNameRelationships(TaxonName name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
399 * Return a List of hybrids related to this name, optionally filtered
400 * by hybrid relationship type
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
410 public Pager
<HybridRelationship
> getHybridNames(INonViralName name
, HybridRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
413 * Return a List of types related to this name, optionally filtered
414 * by type designation status
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
422 public Pager
<TypeDesignationBase
> getTypeDesignations(TaxonName name
,
423 SpecimenTypeDesignationStatus status
, Integer pageSize
, Integer pageNumber
);
425 public Pager
<TypeDesignationBase
> getTypeDesignations(TaxonName name
,
426 SpecimenTypeDesignationStatus status
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
430 * Returns a List of TaxonName instances that match the properties passed
433 * @param infraGenericEpithet
434 * @param specificEpithet
435 * @param infraspecificEpithet
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
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
);
446 * Returns a Paged List of TaxonName instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
448 * @param clazz filter the results by class (or pass null to return all TaxonName instances)
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)
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>
461 public Pager
<TaxonName
> search(Class
<?
extends TaxonName
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
464 * Returns a map that holds uuid, titleCache pairs of all names in the current database
467 * a <code>Map</code> containing uuid and titleCache of names
469 public List
<UuidAndTitleCache
> getUuidAndTitleCacheOfNames(Integer limit
, String pattern
);
472 * Return a Pager of names matching the given query string, optionally filtered by class, optionally with a particular MatchMode
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)}
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
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
);
491 * Returns a homotypical group with the given UUID or null if not homotypical group exists with that UUID
493 * @param uuid the uuid of the homotypical group
494 * @return a homotypical group
496 public HomotypicalGroup
findHomotypicalGroup(UUID uuid
);
502 public List
<TaggedText
> getTaggedName(UUID uuid
);
508 public UpdateResult
setAsGroupsBasionym(UUID nameUuid
);
510 public List
<HashMap
<String
, String
>> getNameRecords();
517 DeleteResult
delete(TaxonName name
, NameDeletionConfigurator config
);