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