cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/INameService.java

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   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.
   9 */
  10
  11 package eu.etaxonomy.cdm.api.service;
  12
  13 import java.io.IOException;
  14 import java.util.Collection;
  15 import java.util.List;
  16 import java.util.Map;
  17 import java.util.UUID;
  18
  19 import org.apache.lucene.index.CorruptIndexException;
  20 import org.apache.lucene.queryParser.ParseException;
  21 import org.hibernate.criterion.Criterion;
  22
  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.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
  52 public interface INameService extends IIdentifiableEntityService<TaxonNameBase> {
  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(TaxonNameBase name, 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 void deleteTypeDesignation(TaxonNameBase name, TypeDesignationBase typeDesignation);
  75
  76
  77         /**
  78          * Saves the given type designations.
  79          * @param typeDesignationCollection
  80          * @return
  81          */
  82         public Map<UUID, TypeDesignationBase> saveTypeDesignationAll(Collection<TypeDesignationBase> typeDesignationCollection);
  83
  84         public Map<UUID, ReferencedEntityBase> saveReferencedEntitiesAll(Collection<ReferencedEntityBase> referencedEntityCollection);
  85
  86         /**
  87          * Saves the given homotypical groups.
  88          * @param homotypicalGroups
  89          * @return
  90          */
  91         public Map<UUID, HomotypicalGroup> saveAllHomotypicalGroups(Collection<HomotypicalGroup> homotypicalGroups);
  92
  93         /**
  94          * Returns all nomenclatural status.
  95          * @param limit
  96          * @param start
  97          * @return
  98          */
  99         public List<NomenclaturalStatus> getAllNomenclaturalStatus(int limit, int start);
 100
 101         /**
 102          * Returns all type designations.
 103          * @param limit
 104          * @param start
 105          * @return
 106          */
 107         public List<TypeDesignationBase> getAllTypeDesignations(int limit, int start);
 108
 109         /**
 110          * @param name
 111          * @return
 112          */
 113         public List<TaxonNameBase> getNamesByName(String name);
 114
 115         /**
 116          * Returns all NonViralNames with a name cache that matches the given string
 117          * @param name
 118          * @return
 119          */
 120         public List<NonViralName> getNamesByNameCache(String nameCache);
 121
 122         /**
 123          * Returns all NonViralNames with a title cache that matches the given string
 124          * using the given match mode and initialization strategy
 125          *
 126          * @param name
 127          * @param matchMode
 128          * @param propertyPaths
 129          * @return
 130          */
 131         public List<NonViralName> findNamesByTitleCache(String titleCache, MatchMode matchMode, List<String> propertyPaths);
 132
 133         /**
 134          * Returns all NonViralNames with a name cache that matches the given string
 135          * using the given match mode and initialization strategy
 136          *
 137          * @param name
 138          * @param matchMode
 139          * @param propertyPaths
 140          * @return
 141          */
 142         public List<NonViralName> findNamesByNameCache(String nameCache, MatchMode matchMode, List<String> propertyPaths);
 143
 144         /**
 145          * Returns the NonViralName with the given UUID
 146          * using the given match mode and initialization strategy
 147          *
 148          * @param uuid
 149          * @param propertyPaths
 150          * @return
 151          */
 152         public NonViralName findNameByUuid(UUID uuid, List<String> propertyPaths);
 153         /**
 154          * @param name
 155          * @param sessionObject An object that is attached to the session before executing the query
 156          * @return
 157          */
 158         public List getNamesByName(String name, CdmBase sessionObject);
 159
 160         /**
 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.
 164          *
 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
 171          * @return
 172          * @throws CorruptIndexException
 173          * @throws IOException
 174          * @throws ParseException
 175          */
 176         public List<SearchResult<TaxonNameBase>> findByNameFuzzySearch(
 177             String name,
 178             float accuracy,
 179             List<Language> languages,
 180             boolean highlightFragments,
 181             List<String> propertyPaths,
 182             int maxNoOfResults) throws CorruptIndexException, IOException, ParseException;
 183
 184         /**
 185          * Fuzzy matching for the taxon name elements using only the lucene index.
 186          *
 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.
 190          *
 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
 196          * @return
 197          * @throws CorruptIndexException
 198          * @throws IOException
 199          * @throws ParseException
 200          */
 201     public List<DocumentSearchResult> findByNameFuzzySearch(
 202             String name,
 203             float accuracy,
 204             List<Language> languages,
 205             boolean highlightFragments,
 206             int maxNoOfResults) throws CorruptIndexException, IOException, ParseException;
 207
 208         /**
 209          * Fuzzy matching against the name cache using only the lucene index.
 210          *
 211          *
 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
 217          * @return
 218          * @throws CorruptIndexException
 219          * @throws IOException
 220          * @throws ParseException
 221          */
 222     public List<DocumentSearchResult> findByFuzzyNameCacheSearch(
 223             String name,
 224             float accuracy,
 225             List<Language> languages,
 226             boolean highlightFragments,
 227             int maxNoOfResults) throws CorruptIndexException, IOException, ParseException;
 228
 229         /**
 230          * Exact matching for the taxon name elements using only the lucene index.
 231          *
 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.
 235          *
 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
 241          * @return
 242          * @throws CorruptIndexException
 243          * @throws IOException
 244          * @throws ParseException
 245          */
 246
 247     public List<DocumentSearchResult> findByNameExactSearch(
 248             String name,
 249             boolean wildcard,
 250             List<Language> languages,
 251             boolean highlightFragments,
 252             int maxNoOfResults) throws CorruptIndexException, IOException, ParseException;
 253
 254         // TODO: Remove getNamesByName() methods. Use findNamesByTitle() instead.
 255
 256         // FIXME candidate for harmonization?
 257         public List findNamesByTitle(String title);
 258
 259         public List findNamesByTitle(String title, CdmBase sessionObject);
 260
 261     public List<HomotypicalGroup> getAllHomotypicalGroups(int limit, int start);
 262
 263         @Deprecated
 264     public List<RelationshipBase> getAllRelationships(int limit, int start);
 265
 266         /**
 267          * Returns all Ranks
 268          * @return
 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
 272          */
 273         @Deprecated
 274     public OrderedTermVocabulary<Rank> getRankVocabulary();
 275
 276         /**
 277          * Returns all NomenclaturalStatusTypes
 278          * @return
 279          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 280          */
 281         @Deprecated
 282     public TermVocabulary<NomenclaturalStatusType> getStatusTypeVocabulary();
 283
 284         /**
 285          * Returns TypeDesignationStatus vocabulary
 286          * @return
 287          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 288          */
 289         @Deprecated
 290     public TermVocabulary<SpecimenTypeDesignationStatus> getSpecimenTypeDesignationStatusVocabulary();
 291
 292         /**
 293          * Returns TypeDesignationStatus ordered vocabulary
 294          * @return
 295          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 296          */
 297         @Deprecated
 298     public OrderedTermVocabulary<SpecimenTypeDesignationStatus> getSpecimenTypeDesignationVocabulary();
 299
 300         /**
 301          * Returns all NameRelationshipTypes
 302          * @return
 303          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 304          */
 305         @Deprecated
 306     public TermVocabulary<NameRelationshipType> getNameRelationshipTypeVocabulary();
 307
 308         /**
 309          * Return a List of name relationships in which this name is related to
 310          * another name, optionally filtered by relationship type
 311          *
 312          * @param name
 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.
 316          * @param direction
 317          *            the direction of the NameRelationship, may be null to return all relationships
 318          * @param type
 319          *            the relationship type (or null to return all relationships)
 320          * @param pageSize
 321          *            The maximum number of relationships returned (can be null for
 322          *            all relationships)
 323          * @param pageNumber
 324          *            The offset (in pageSize chunks) from the start of the result
 325          *            set (0 - based)
 326          * @param orderHints
 327          *            may be null
 328          * @param propertyPaths
 329          *            properties to initialize - see
 330          *            {@link IBeanInitializer#initialize(Object, List)}
 331          * @return a Pager of NameRelationship instances
 332          */
 333         public List<NameRelationship> listNameRelationships(TaxonNameBase name,  NameRelationship.Direction direction, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 334
 335         /**
 336          * Return a List of name relationships in which this name is related to another name, optionally filtered
 337          * by relationship type
 338          *
 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
 347          */
 348         public Pager<NameRelationship> pageNameRelationships(TaxonNameBase name,  NameRelationship.Direction direction, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 349
 350         /**
 351          * Return a List of relationships in which this name is related to another name, optionally filtered
 352          * by relationship type
 353          *
 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
 362          */
 363         @Deprecated
 364         public List<NameRelationship> listFromNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 365
 366         /**
 367          * Return a List of relationships in which this name is related to another name, optionally filtered
 368          * by relationship type
 369          *
 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
 378          */
 379         @Deprecated
 380         public Pager<NameRelationship> pageFromNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 381
 382         /**
 383          * Return a List of relationships in which another name is related to this name, optionally filtered
 384          * by relationship type
 385          *
 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
 394          */
 395         @Deprecated
 396         public List<NameRelationship> listToNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 397
 398         /**
 399          * Return a List of relationships in which another name is related to this name, optionally filtered
 400          * by relationship type
 401          *
 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
 410          */
 411         @Deprecated
 412         public Pager<NameRelationship> pageToNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 413
 414
 415         /**
 416          * Return a List of hybrids related to this name, optionally filtered
 417          * by hybrid relationship type
 418          *
 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
 426          */
 427         public Pager<HybridRelationship> getHybridNames(NonViralName name, HybridRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 428
 429         /**
 430          * Return a List of types related to this name, optionally filtered
 431          * by type designation status
 432          *
 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
 438          */
 439         public Pager<TypeDesignationBase> getTypeDesignations(TaxonNameBase name,
 440                         SpecimenTypeDesignationStatus status, Integer pageSize, Integer pageNumber);
 441
 442         public Pager<TypeDesignationBase> getTypeDesignations(TaxonNameBase name,
 443                         SpecimenTypeDesignationStatus status, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 444
 445
 446         /**
 447          * Returns a List of TaxonNameBase instances that match the properties passed
 448          *
 449          * @param uninomial
 450          * @param infraGenericEpithet
 451          * @param specificEpithet
 452          * @param infraspecificEpithet
 453          * @param rank
 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
 459          */
 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);
 461
 462         /**
 463          * Returns a Paged List of TaxonNameBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 464          *
 465          * @param clazz filter the results by class (or pass null to return all TaxonNameBase instances)
 466          * @param queryString
 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)
 469          * @param orderHints
 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>
 476          */
 477         @Override
 478     public Pager<TaxonNameBase> search(Class<? extends TaxonNameBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 479
 480         /**
 481          * Returns a map that holds uuid, titleCache pairs of all names in the current database
 482          *
 483          * @return
 484          *                      a <code>Map</code> containing uuid and titleCache of names
 485          */
 486         public List<UuidAndTitleCache> getUuidAndTitleCacheOfNames();
 487
 488         /**
 489          * Return a Pager of names matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 490          *
 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)}
 498          * @param orderHints
 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
 503          */
 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);
 505
 506     /**
 507      * Returns a homotypical group with the given UUID or null if not homotypical group exists with that UUID
 508      *
 509      * @param uuid the uuid of the homotypical group
 510      * @return a homotypical group
 511      */
 512     public HomotypicalGroup findHomotypicalGroup(UUID uuid);
 513
 514     /**
 515      * @param uuid
 516      * @return
 517      */
 518     public List<TaggedText> getTaggedName(UUID uuid);
 519 }