3 * Copyright (C) 2007 EDIT
4 * European Distributed Institute of Taxonomy
5 * http://www.e-taxonomy.eu
7 * The contents of this file are subject to the Mozilla Public License Version 1.1
8 * See LICENSE.TXT at the top of this package for the full license terms.
11 package eu
.etaxonomy
.cdm
.api
.service
;
13 import java
.io
.IOException
;
14 import java
.util
.Collection
;
15 import java
.util
.List
;
17 import java
.util
.UUID
;
19 import org
.apache
.lucene
.index
.CorruptIndexException
;
20 import org
.apache
.lucene
.queryParser
.ParseException
;
21 import org
.hibernate
.criterion
.Criterion
;
23 import eu
.etaxonomy
.cdm
.api
.service
.config
.NameDeletionConfigurator
;
24 import eu
.etaxonomy
.cdm
.api
.service
.exception
.ReferencedObjectUndeletableException
;
25 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
26 import eu
.etaxonomy
.cdm
.api
.service
.search
.DocumentSearchResult
;
27 import eu
.etaxonomy
.cdm
.api
.service
.search
.SearchResult
;
28 import eu
.etaxonomy
.cdm
.model
.common
.CdmBase
;
29 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
30 import eu
.etaxonomy
.cdm
.model
.common
.OrderedTermVocabulary
;
31 import eu
.etaxonomy
.cdm
.model
.common
.ReferencedEntityBase
;
32 import eu
.etaxonomy
.cdm
.model
.common
.RelationshipBase
;
33 import eu
.etaxonomy
.cdm
.model
.common
.TermVocabulary
;
34 import eu
.etaxonomy
.cdm
.model
.common
.UuidAndTitleCache
;
35 import eu
.etaxonomy
.cdm
.model
.name
.HomotypicalGroup
;
36 import eu
.etaxonomy
.cdm
.model
.name
.HybridRelationship
;
37 import eu
.etaxonomy
.cdm
.model
.name
.HybridRelationshipType
;
38 import eu
.etaxonomy
.cdm
.model
.name
.NameRelationship
;
39 import eu
.etaxonomy
.cdm
.model
.name
.NameRelationshipType
;
40 import eu
.etaxonomy
.cdm
.model
.name
.NomenclaturalStatus
;
41 import eu
.etaxonomy
.cdm
.model
.name
.NomenclaturalStatusType
;
42 import eu
.etaxonomy
.cdm
.model
.name
.NonViralName
;
43 import eu
.etaxonomy
.cdm
.model
.name
.Rank
;
44 import eu
.etaxonomy
.cdm
.model
.name
.SpecimenTypeDesignationStatus
;
45 import eu
.etaxonomy
.cdm
.model
.name
.TaxonNameBase
;
46 import eu
.etaxonomy
.cdm
.model
.name
.TypeDesignationBase
;
47 import eu
.etaxonomy
.cdm
.persistence
.dao
.IBeanInitializer
;
48 import eu
.etaxonomy
.cdm
.persistence
.query
.MatchMode
;
49 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
50 import eu
.etaxonomy
.cdm
.strategy
.cache
.TaggedText
;
52 public interface INameService
extends IIdentifiableEntityService
<TaxonNameBase
> {
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.
60 * @throws ReferencedObjectUndeletableException
62 public UUID
delete(TaxonNameBase name
, NameDeletionConfigurator config
) throws ReferencedObjectUndeletableException
;
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 void deleteTypeDesignation(TaxonNameBase name
, TypeDesignationBase typeDesignation
);
78 * Saves the given type designations.
79 * @param typeDesignationCollection
82 public Map
<UUID
, TypeDesignationBase
> saveTypeDesignationAll(Collection
<TypeDesignationBase
> typeDesignationCollection
);
84 public Map
<UUID
, ReferencedEntityBase
> saveReferencedEntitiesAll(Collection
<ReferencedEntityBase
> referencedEntityCollection
);
87 * Saves the given homotypical groups.
88 * @param homotypicalGroups
91 public Map
<UUID
, HomotypicalGroup
> saveAllHomotypicalGroups(Collection
<HomotypicalGroup
> homotypicalGroups
);
94 * Returns all nomenclatural status.
99 public List
<NomenclaturalStatus
> getAllNomenclaturalStatus(int limit
, int start
);
102 * Returns all type designations.
107 public List
<TypeDesignationBase
> getAllTypeDesignations(int limit
, int start
);
113 public List
<TaxonNameBase
> getNamesByName(String name
);
116 * Returns all NonViralNames with a name cache that matches the given string
120 public List
<NonViralName
> getNamesByNameCache(String nameCache
);
123 * Returns all NonViralNames with a title cache that matches the given string
124 * using the given match mode and initialization strategy
128 * @param propertyPaths
131 public List
<NonViralName
> findNamesByTitleCache(String titleCache
, MatchMode matchMode
, List
<String
> propertyPaths
);
134 * Returns all NonViralNames with a name cache that matches the given string
135 * using the given match mode and initialization strategy
139 * @param propertyPaths
142 public List
<NonViralName
> findNamesByNameCache(String nameCache
, MatchMode matchMode
, List
<String
> propertyPaths
);
145 * Returns the NonViralName with the given UUID
146 * using the given match mode and initialization strategy
149 * @param propertyPaths
152 public NonViralName
findNameByUuid(UUID uuid
, List
<String
> propertyPaths
);
155 * @param sessionObject An object that is attached to the session before executing the query
158 public List
getNamesByName(String name
, CdmBase sessionObject
);
161 * Fuzzy matching for the taxon name elements. The input name is first atomised using the {@link NonViralNameParserImpl}
162 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
163 * Each field is then matched separately with the same accuracy parameter.
165 * @param name taxon name to fuzzy match
166 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
167 * @param languages list of languages to consider when matching (currently not used)
168 * @param highlightFragments
169 * @param propertyPaths
170 * @param maxNoOfResults
172 * @throws CorruptIndexException
173 * @throws IOException
174 * @throws ParseException
176 public List
<SearchResult
<TaxonNameBase
>> findByNameFuzzySearch(
179 List
<Language
> languages
,
180 boolean highlightFragments
,
181 List
<String
> propertyPaths
,
182 int maxNoOfResults
) throws CorruptIndexException
, IOException
, ParseException
;
185 * Fuzzy matching for the taxon name elements using only the lucene index.
187 * The input name is first atomised using the {@link NonViralNameParserImpl}
188 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
189 * Each field is then matched separately with the same accuracy parameter.
191 * @param name taxon name to fuzzy match
192 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
193 * @param languages list of languages to consider when matching (currently not used)
194 * @param highlightFragments
195 * @param maxNoOfResults
197 * @throws CorruptIndexException
198 * @throws IOException
199 * @throws ParseException
201 public List
<DocumentSearchResult
> findByNameFuzzySearch(
204 List
<Language
> languages
,
205 boolean highlightFragments
,
206 int maxNoOfResults
) throws CorruptIndexException
, IOException
, ParseException
;
209 * Fuzzy matching against the name cache using only the lucene index.
212 * @param name taxon name to fuzzy match
213 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
214 * @param languages list of languages to consider when matching (currently not used)
215 * @param highlightFragments
216 * @param maxNoOfResults
218 * @throws CorruptIndexException
219 * @throws IOException
220 * @throws ParseException
222 public List
<DocumentSearchResult
> findByFuzzyNameCacheSearch(
225 List
<Language
> languages
,
226 boolean highlightFragments
,
227 int maxNoOfResults
) throws CorruptIndexException
, IOException
, ParseException
;
230 * Exact matching for the taxon name elements using only the lucene index.
232 * The input name is first atomised using the {@link NonViralNameParserImpl}
233 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
234 * Each field is then matched separately with the same accuracy parameter.
236 * @param name taxon name to fuzzy match
237 * @param wildcard boolean flag to indicate whether a wildcard '*' should be added at the end of the query
238 * @param languages list of languages to consider when matching (currently not used)
239 * @param highlightFragments
240 * @param maxNoOfResults
242 * @throws CorruptIndexException
243 * @throws IOException
244 * @throws ParseException
247 public List
<DocumentSearchResult
> findByNameExactSearch(
250 List
<Language
> languages
,
251 boolean highlightFragments
,
252 int maxNoOfResults
) throws CorruptIndexException
, IOException
, ParseException
;
254 // TODO: Remove getNamesByName() methods. Use findNamesByTitle() instead.
256 // FIXME candidate for harmonization?
257 public List
findNamesByTitle(String title
);
259 public List
findNamesByTitle(String title
, CdmBase sessionObject
);
261 public List
<HomotypicalGroup
> getAllHomotypicalGroups(int limit
, int start
);
264 public List
<RelationshipBase
> getAllRelationships(int limit
, int start
);
269 * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead,
270 * this is not possible since VocabularyService#getVocabulary(VocabularyEnum)
271 * is not returning a OrderedTermVocabulary !!! see also http://dev.e-taxonomy.eu/trac/ticket/3327
274 public OrderedTermVocabulary
<Rank
> getRankVocabulary();
277 * Returns all NomenclaturalStatusTypes
279 * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
282 public TermVocabulary
<NomenclaturalStatusType
> getStatusTypeVocabulary();
285 * Returns TypeDesignationStatus vocabulary
287 * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
290 public TermVocabulary
<SpecimenTypeDesignationStatus
> getSpecimenTypeDesignationStatusVocabulary();
293 * Returns TypeDesignationStatus ordered vocabulary
295 * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
298 public OrderedTermVocabulary
<SpecimenTypeDesignationStatus
> getSpecimenTypeDesignationVocabulary();
301 * Returns all NameRelationshipTypes
303 * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
306 public TermVocabulary
<NameRelationshipType
> getNameRelationshipTypeVocabulary();
309 * Return a List of name relationships in which this name is related to
310 * another name, optionally filtered by relationship type
313 * the name on either the <i>"from side"</i> or on the
314 * <i>"to side"</i> of the relationship, depending on the
315 * <code>direction</code> of the relationship.
317 * the direction of the NameRelationship, may be null to return all relationships
319 * the relationship type (or null to return all relationships)
321 * The maximum number of relationships returned (can be null for
324 * The offset (in pageSize chunks) from the start of the result
328 * @param propertyPaths
329 * properties to initialize - see
330 * {@link IBeanInitializer#initialize(Object, List)}
331 * @return a Pager of NameRelationship instances
333 public List
<NameRelationship
> listNameRelationships(TaxonNameBase name
, NameRelationship
.Direction direction
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
336 * Return a List of name relationships in which this name is related to another name, optionally filtered
337 * by relationship type
339 * @param name the name on the <i>"from side"</i> of the relationship
340 * @param direction the direction of the NameRelationship
341 * @param type the relationship type (or null to return all relationships)
342 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
343 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
344 * @param orderHints may be null
345 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
346 * @return a Pager of NameRelationship instances
348 public Pager
<NameRelationship
> pageNameRelationships(TaxonNameBase name
, NameRelationship
.Direction direction
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
351 * Return a List of relationships in which this name is related to another name, optionally filtered
352 * by relationship type
354 * @param name the name on the <i>"from side"</i> of the relationship
355 * @param type the relationship type (or null to return all relationships)
356 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
357 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
358 * @param orderHints may be null
359 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
360 * @return a Pager of NameRelationship instances
361 * @deprecated use {@link #listNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
364 public List
<NameRelationship
> listFromNameRelationships(TaxonNameBase name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
367 * Return a List of relationships in which this name is related to another name, optionally filtered
368 * by relationship type
370 * @param name the name on the <i>"from side"</i> of the relationship
371 * @param type the relationship type (or null to return all relationships)
372 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
373 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
374 * @param orderHints may be null
375 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
376 * @return a Pager of NameRelationship instances
377 * @deprecated use {@link #pageNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
380 public Pager
<NameRelationship
> pageFromNameRelationships(TaxonNameBase name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
383 * Return a List of relationships in which another name is related to this name, optionally filtered
384 * by relationship type
386 * @param name the name on the <i>"to side"</i> of the relationship
387 * @param type the relationship type (or null to return all relationships)
388 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
389 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
390 * @param orderHints may be null
391 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
392 * @return a Pager of NameRelationship instances
393 * @deprecated use {@link #listNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
396 public List
<NameRelationship
> listToNameRelationships(TaxonNameBase name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
399 * Return a List of relationships in which another name is related to this name, optionally filtered
400 * by relationship type
402 * @param name the name on the <i>"to side"</i> of the relationship
403 * @param type the relationship type (or null to return all relationships)
404 * @param pageSize The maximum number of 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 NameRelationship instances
409 * @deprecated use {@link #pageNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
412 public Pager
<NameRelationship
> pageToNameRelationships(TaxonNameBase name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
416 * Return a List of hybrids related to this name, optionally filtered
417 * by hybrid relationship type
419 * @param name the name
420 * @param type the hybrid relationship type (or null to return all hybrids)
421 * @param pageSize The maximum number of hybrid relationships returned (can be null for all relationships)
422 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
423 * @param orderHints may be null
424 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
425 * @return a Pager of HybridRelationship instances
427 public Pager
<HybridRelationship
> getHybridNames(NonViralName name
, HybridRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
430 * Return a List of types related to this name, optionally filtered
431 * by type designation status
433 * @param name the name
434 * @param status the type designation status (or null to return all types)
435 * @param pageSize The maximum number of types returned (can be null for all types)
436 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
437 * @return a Pager of TypeDesignationBase instances
439 public Pager
<TypeDesignationBase
> getTypeDesignations(TaxonNameBase name
,
440 SpecimenTypeDesignationStatus status
, Integer pageSize
, Integer pageNumber
);
442 public Pager
<TypeDesignationBase
> getTypeDesignations(TaxonNameBase name
,
443 SpecimenTypeDesignationStatus status
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
447 * Returns a List of TaxonNameBase instances that match the properties passed
450 * @param infraGenericEpithet
451 * @param specificEpithet
452 * @param infraspecificEpithet
454 * @param pageSize The maximum number of names returned (can be null for all names)
455 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
456 * @param orderHints may be null
457 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
458 * @return a Pager of TaxonNameBase instances
460 public Pager
<TaxonNameBase
> searchNames(String uninomial
, String infraGenericEpithet
, String specificEpithet
, String infraspecificEpithet
, Rank rank
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
463 * Returns a Paged List of TaxonNameBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
465 * @param clazz filter the results by class (or pass null to return all TaxonNameBase instances)
467 * @param pageSize The maximum number of names returned (can be null for all matching names)
468 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
470 * Supports path like <code>orderHints.propertyNames</code> which
471 * include *-to-one properties like createdBy.username or
472 * authorTeam.persistentTitleCache
473 * @param propertyPaths properties to be initialized
474 * @return a Pager TaxonNameBase instances
475 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
478 public Pager
<TaxonNameBase
> search(Class
<?
extends TaxonNameBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
481 * Returns a map that holds uuid, titleCache pairs of all names in the current database
484 * a <code>Map</code> containing uuid and titleCache of names
486 public List
<UuidAndTitleCache
> getUuidAndTitleCacheOfNames();
489 * Return a Pager of names matching the given query string, optionally filtered by class, optionally with a particular MatchMode
491 * @param clazz filter by class - can be null to include all instances of type T
492 * @param queryString the query string to filter by
493 * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
494 * @param criteria additional criteria to filter by
495 * @param pageSize The maximum number of objects returned (can be null for all objects)
496 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
497 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
499 * Supports path like <code>orderHints.propertyNames</code> which
500 * include *-to-one properties like createdBy.username or
501 * authorTeam.persistentTitleCache
502 * @return a paged list of instances of type T matching the queryString
504 public Pager
<TaxonNameBase
> findByName(Class
<?
extends TaxonNameBase
> clazz
, String queryString
,MatchMode matchmode
, List
<Criterion
> criteria
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
507 * Returns a homotypical group with the given UUID or null if not homotypical group exists with that UUID
509 * @param uuid the uuid of the homotypical group
510 * @return a homotypical group
512 public HomotypicalGroup
findHomotypicalGroup(UUID uuid
);
518 public List
<TaggedText
> getTaggedName(UUID uuid
);