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
.HashMap
;
16 import java
.util
.List
;
18 import java
.util
.UUID
;
20 import org
.apache
.lucene
.index
.CorruptIndexException
;
21 import org
.apache
.lucene
.queryParser
.ParseException
;
22 import org
.hibernate
.criterion
.Criterion
;
24 import eu
.etaxonomy
.cdm
.api
.service
.config
.NameDeletionConfigurator
;
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
.initializer
.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
;
51 import eu
.etaxonomy
.cdm
.strategy
.parser
.NonViralNameParserImpl
;
53 public interface INameService
extends IIdentifiableEntityService
<TaxonNameBase
> {
56 * Deletes a name. Depening on the configurator state links to the name will either be
57 * deleted or throw exceptions.<BR>
58 * If name is <code>null</code> this method has no effect.
63 public DeleteResult
delete(TaxonNameBase name
, NameDeletionConfigurator config
);
66 * Removes the given type designation from the given taxon name and deletes it from
67 * the database if it is not connected to any other name.
68 * If <code>typeDesignation</code> is <code>null</code> all type designations are deleted
69 * from the given taxon name. If <code>name</code> is <code>null</code> all names are removed from
70 * the given type designation. If both are <code>null</code> nothing happens.
71 * @param typeDesignation
75 public void deleteTypeDesignation(TaxonNameBase name
, TypeDesignationBase typeDesignation
);
79 * Saves the given type designations.
80 * @param typeDesignationCollection
83 public Map
<UUID
, TypeDesignationBase
> saveTypeDesignationAll(Collection
<TypeDesignationBase
> typeDesignationCollection
);
85 public Map
<UUID
, ReferencedEntityBase
> saveReferencedEntitiesAll(Collection
<ReferencedEntityBase
> referencedEntityCollection
);
88 * Saves the given homotypical groups.
89 * @param homotypicalGroups
92 public Map
<UUID
, HomotypicalGroup
> saveAllHomotypicalGroups(Collection
<HomotypicalGroup
> homotypicalGroups
);
95 * Returns all nomenclatural status.
100 public List
<NomenclaturalStatus
> getAllNomenclaturalStatus(int limit
, int start
);
103 * Returns all type designations.
108 public List
<TypeDesignationBase
> getAllTypeDesignations(int limit
, int start
);
114 public List
<TaxonNameBase
> getNamesByName(String name
);
117 * Returns all NonViralNames with a name cache that matches the given string
121 public List
<NonViralName
> getNamesByNameCache(String nameCache
);
124 * Returns all NonViralNames with a title cache that matches the given string
125 * using the given match mode and initialization strategy
129 * @param propertyPaths
132 public List
<NonViralName
> findNamesByTitleCache(String titleCache
, MatchMode matchMode
, List
<String
> propertyPaths
);
135 * Returns all NonViralNames with a name cache that matches the given string
136 * using the given match mode and initialization strategy
140 * @param propertyPaths
143 public List
<NonViralName
> findNamesByNameCache(String nameCache
, MatchMode matchMode
, List
<String
> propertyPaths
);
146 * Returns the NonViralName with the given UUID
147 * using the given match mode and initialization strategy
150 * @param propertyPaths
153 public NonViralName
findNameByUuid(UUID uuid
, List
<String
> propertyPaths
);
156 * @param sessionObject An object that is attached to the session before executing the query
159 public List
getNamesByName(String name
, CdmBase sessionObject
);
162 * Fuzzy matching for the taxon name elements. The input name is first atomised using the {@link NonViralNameParserImpl}
163 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
164 * Each field is then matched separately with the same accuracy parameter.
166 * @param name taxon name to fuzzy match
167 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
168 * @param languages list of languages to consider when matching (currently not used)
169 * @param highlightFragments
170 * @param propertyPaths
171 * @param maxNoOfResults
173 * @throws CorruptIndexException
174 * @throws IOException
175 * @throws ParseException
177 public List
<SearchResult
<TaxonNameBase
>> findByNameFuzzySearch(
180 List
<Language
> languages
,
181 boolean highlightFragments
,
182 List
<String
> propertyPaths
,
183 int maxNoOfResults
) throws CorruptIndexException
, IOException
, ParseException
;
186 * Fuzzy matching for the taxon name elements using only the lucene index.
188 * The input name is first atomised using the {@link NonViralNameParserImpl}
189 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
190 * Each field is then matched separately with the same accuracy parameter.
192 * @param name taxon name to fuzzy match
193 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
194 * @param languages list of languages to consider when matching (currently not used)
195 * @param highlightFragments
196 * @param maxNoOfResults
198 * @throws CorruptIndexException
199 * @throws IOException
200 * @throws ParseException
202 public List
<DocumentSearchResult
> findByNameFuzzySearch(
205 List
<Language
> languages
,
206 boolean highlightFragments
,
207 int maxNoOfResults
) throws CorruptIndexException
, IOException
, ParseException
;
210 * Fuzzy matching against the name cache using only the lucene index.
213 * @param name taxon name to fuzzy match
214 * @param accuracy value > 0.0 and < 1.0 which determines the accuracy of the result.
215 * @param languages list of languages to consider when matching (currently not used)
216 * @param highlightFragments
217 * @param maxNoOfResults
219 * @throws CorruptIndexException
220 * @throws IOException
221 * @throws ParseException
223 public List
<DocumentSearchResult
> findByFuzzyNameCacheSearch(
226 List
<Language
> languages
,
227 boolean highlightFragments
,
228 int maxNoOfResults
) throws CorruptIndexException
, IOException
, ParseException
;
231 * Exact matching for the taxon name elements using only the lucene index.
233 * The input name is first atomised using the {@link NonViralNameParserImpl}
234 * into its separate parts (genusOrUninomial,infraGenericEpithet,specificEpithet,infraGenericEpithet,authorshipCache).
235 * Each field is then matched separately with the same accuracy parameter.
237 * @param name taxon name to fuzzy match
238 * @param wildcard boolean flag to indicate whether a wildcard '*' should be added at the end of the query
239 * @param languages list of languages to consider when matching (currently not used)
240 * @param highlightFragments
241 * @param maxNoOfResults
243 * @throws CorruptIndexException
244 * @throws IOException
245 * @throws ParseException
248 public List
<DocumentSearchResult
> findByNameExactSearch(
251 List
<Language
> languages
,
252 boolean highlightFragments
,
253 int maxNoOfResults
) throws CorruptIndexException
, IOException
, ParseException
;
255 // TODO: Remove getNamesByName() methods. Use findNamesByTitle() instead.
257 // FIXME candidate for harmonization?
258 public List
findNamesByTitle(String title
);
260 public List
findNamesByTitle(String title
, CdmBase sessionObject
);
262 public List
<HomotypicalGroup
> getAllHomotypicalGroups(int limit
, int start
);
265 public List
<RelationshipBase
> getAllRelationships(int limit
, int start
);
269 * Return a List of name relationships in which this name is related to
270 * another name, optionally filtered by relationship type
273 * the name on either the <i>"from side"</i> or on the
274 * <i>"to side"</i> of the relationship, depending on the
275 * <code>direction</code> of the relationship.
277 * the direction of the NameRelationship, may be null to return all relationships
279 * the relationship type (or null to return all relationships)
281 * The maximum number of relationships returned (can be null for
284 * The offset (in pageSize chunks) from the start of the result
288 * @param propertyPaths
289 * properties to initialize - see
290 * {@link IBeanInitializer#initialize(Object, List)}
291 * @return a Pager of NameRelationship instances
293 public List
<NameRelationship
> listNameRelationships(TaxonNameBase name
, NameRelationship
.Direction direction
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
296 * Return a List of name relationships in which this name is related to another name, optionally filtered
297 * by relationship type
299 * @param name the name on the <i>"from side"</i> of the relationship
300 * @param direction the direction of the NameRelationship
301 * @param type the relationship type (or null to return all relationships)
302 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
303 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
304 * @param orderHints may be null
305 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
306 * @return a Pager of NameRelationship instances
308 public Pager
<NameRelationship
> pageNameRelationships(TaxonNameBase name
, NameRelationship
.Direction direction
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
311 * Return a List of relationships in which this name is related to another name, optionally filtered
312 * by relationship type
314 * @param name the name on the <i>"from side"</i> of the relationship
315 * @param type the relationship type (or null to return all relationships)
316 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
317 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
318 * @param orderHints may be null
319 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
320 * @return a Pager of NameRelationship instances
321 * @deprecated use {@link #listNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
324 public List
<NameRelationship
> listFromNameRelationships(TaxonNameBase name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
327 * Return a List of relationships in which this name is related to another name, optionally filtered
328 * by relationship type
330 * @param name the name on the <i>"from side"</i> of the relationship
331 * @param type the relationship type (or null to return all relationships)
332 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
333 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
334 * @param orderHints may be null
335 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
336 * @return a Pager of NameRelationship instances
337 * @deprecated use {@link #pageNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
340 public Pager
<NameRelationship
> pageFromNameRelationships(TaxonNameBase name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
343 * Return a List of relationships in which another name is related to this name, optionally filtered
344 * by relationship type
346 * @param name the name on the <i>"to side"</i> of the relationship
347 * @param type the relationship type (or null to return all relationships)
348 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
349 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
350 * @param orderHints may be null
351 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
352 * @return a Pager of NameRelationship instances
353 * @deprecated use {@link #listNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
356 public List
<NameRelationship
> listToNameRelationships(TaxonNameBase name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
359 * Return a List of relationships in which another name is related to this name, optionally filtered
360 * by relationship type
362 * @param name the name on the <i>"to side"</i> of the relationship
363 * @param type the relationship type (or null to return all relationships)
364 * @param pageSize The maximum number of relationships returned (can be null for all relationships)
365 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
366 * @param orderHints may be null
367 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
368 * @return a Pager of NameRelationship instances
369 * @deprecated use {@link #pageNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
372 public Pager
<NameRelationship
> pageToNameRelationships(TaxonNameBase name
, NameRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
376 * Return a List of hybrids related to this name, optionally filtered
377 * by hybrid relationship type
379 * @param name the name
380 * @param type the hybrid relationship type (or null to return all hybrids)
381 * @param pageSize The maximum number of hybrid relationships returned (can be null for all relationships)
382 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
383 * @param orderHints may be null
384 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
385 * @return a Pager of HybridRelationship instances
387 public Pager
<HybridRelationship
> getHybridNames(NonViralName name
, HybridRelationshipType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
390 * Return a List of types related to this name, optionally filtered
391 * by type designation status
393 * @param name the name
394 * @param status the type designation status (or null to return all types)
395 * @param pageSize The maximum number of types returned (can be null for all types)
396 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
397 * @return a Pager of TypeDesignationBase instances
399 public Pager
<TypeDesignationBase
> getTypeDesignations(TaxonNameBase name
,
400 SpecimenTypeDesignationStatus status
, Integer pageSize
, Integer pageNumber
);
402 public Pager
<TypeDesignationBase
> getTypeDesignations(TaxonNameBase name
,
403 SpecimenTypeDesignationStatus status
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
407 * Returns a List of TaxonNameBase instances that match the properties passed
410 * @param infraGenericEpithet
411 * @param specificEpithet
412 * @param infraspecificEpithet
414 * @param pageSize The maximum number of names returned (can be null for all names)
415 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
416 * @param orderHints may be null
417 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
418 * @return a Pager of TaxonNameBase instances
420 public Pager
<TaxonNameBase
> searchNames(String uninomial
, String infraGenericEpithet
, String specificEpithet
, String infraspecificEpithet
, Rank rank
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
423 * Returns a Paged List of TaxonNameBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
425 * @param clazz filter the results by class (or pass null to return all TaxonNameBase instances)
427 * @param pageSize The maximum number of names returned (can be null for all matching names)
428 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
430 * Supports path like <code>orderHints.propertyNames</code> which
431 * include *-to-one properties like createdBy.username or
432 * authorTeam.persistentTitleCache
433 * @param propertyPaths properties to be initialized
434 * @return a Pager TaxonNameBase instances
435 * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
438 public Pager
<TaxonNameBase
> search(Class
<?
extends TaxonNameBase
> clazz
, String queryString
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
441 * Returns a map that holds uuid, titleCache pairs of all names in the current database
444 * a <code>Map</code> containing uuid and titleCache of names
446 public List
<UuidAndTitleCache
> getUuidAndTitleCacheOfNames();
449 * Return a Pager of names matching the given query string, optionally filtered by class, optionally with a particular MatchMode
451 * @param clazz filter by class - can be null to include all instances of type T
452 * @param queryString the query string to filter by
453 * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
454 * @param criteria additional criteria to filter by
455 * @param pageSize The maximum number of objects returned (can be null for all objects)
456 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
457 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
459 * Supports path like <code>orderHints.propertyNames</code> which
460 * include *-to-one properties like createdBy.username or
461 * authorTeam.persistentTitleCache
462 * @return a paged list of instances of type T matching the queryString
464 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
);
467 * Returns a homotypical group with the given UUID or null if not homotypical group exists with that UUID
469 * @param uuid the uuid of the homotypical group
470 * @return a homotypical group
472 public HomotypicalGroup
findHomotypicalGroup(UUID uuid
);
478 public List
<TaggedText
> getTaggedName(UUID uuid
);
480 List
<HashMap
<String
, String
>> getNameRecords();