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.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.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;
  52
  53 public interface INameService extends IIdentifiableEntityService<TaxonNameBase> {
  54
  55         /**
  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.
  59          * @param name
  60          * @param config
  61          *
  62          */
  63         public DeleteResult delete(TaxonNameBase name, NameDeletionConfigurator config);
  64
  65         /**
  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
  72          * @param name
  73          * @return
  74          */
  75         public void deleteTypeDesignation(TaxonNameBase name, TypeDesignationBase typeDesignation);
  76
  77
  78         /**
  79          * Saves the given type designations.
  80          * @param typeDesignationCollection
  81          * @return
  82          */
  83         public Map<UUID, TypeDesignationBase> saveTypeDesignationAll(Collection<TypeDesignationBase> typeDesignationCollection);
  84
  85         public Map<UUID, ReferencedEntityBase> saveReferencedEntitiesAll(Collection<ReferencedEntityBase> referencedEntityCollection);
  86
  87         /**
  88          * Saves the given homotypical groups.
  89          * @param homotypicalGroups
  90          * @return
  91          */
  92         public Map<UUID, HomotypicalGroup> saveAllHomotypicalGroups(Collection<HomotypicalGroup> homotypicalGroups);
  93
  94         /**
  95          * Returns all nomenclatural status.
  96          * @param limit
  97          * @param start
  98          * @return
  99          */
 100         public List<NomenclaturalStatus> getAllNomenclaturalStatus(int limit, int start);
 101
 102         /**
 103          * Returns all type designations.
 104          * @param limit
 105          * @param start
 106          * @return
 107          */
 108         public List<TypeDesignationBase> getAllTypeDesignations(int limit, int start);
 109
 110         /**
 111          * @param name
 112          * @return
 113          */
 114         public List<TaxonNameBase> getNamesByName(String name);
 115
 116         /**
 117          * Returns all NonViralNames with a name cache that matches the given string
 118          * @param name
 119          * @return
 120          */
 121         public List<NonViralName> getNamesByNameCache(String nameCache);
 122
 123         /**
 124          * Returns all NonViralNames with a title cache that matches the given string
 125          * using the given match mode and initialization strategy
 126          *
 127          * @param name
 128          * @param matchMode
 129          * @param propertyPaths
 130          * @return
 131          */
 132         public List<NonViralName> findNamesByTitleCache(String titleCache, MatchMode matchMode, List<String> propertyPaths);
 133
 134         /**
 135          * Returns all NonViralNames with a name cache that matches the given string
 136          * using the given match mode and initialization strategy
 137          *
 138          * @param name
 139          * @param matchMode
 140          * @param propertyPaths
 141          * @return
 142          */
 143         public List<NonViralName> findNamesByNameCache(String nameCache, MatchMode matchMode, List<String> propertyPaths);
 144
 145         /**
 146          * Returns the NonViralName with the given UUID
 147          * using the given match mode and initialization strategy
 148          *
 149          * @param uuid
 150          * @param propertyPaths
 151          * @return
 152          */
 153         public NonViralName findNameByUuid(UUID uuid, List<String> propertyPaths);
 154         /**
 155          * @param name
 156          * @param sessionObject An object that is attached to the session before executing the query
 157          * @return
 158          */
 159         public List getNamesByName(String name, CdmBase sessionObject);
 160
 161         /**
 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.
 165          *
 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
 172          * @return
 173          * @throws CorruptIndexException
 174          * @throws IOException
 175          * @throws ParseException
 176          */
 177         public List<SearchResult<TaxonNameBase>> findByNameFuzzySearch(
 178             String name,
 179             float accuracy,
 180             List<Language> languages,
 181             boolean highlightFragments,
 182             List<String> propertyPaths,
 183             int maxNoOfResults) throws CorruptIndexException, IOException, ParseException;
 184
 185         /**
 186          * Fuzzy matching for the taxon name elements using only the lucene index.
 187          *
 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.
 191          *
 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
 197          * @return
 198          * @throws CorruptIndexException
 199          * @throws IOException
 200          * @throws ParseException
 201          */
 202     public List<DocumentSearchResult> findByNameFuzzySearch(
 203             String name,
 204             float accuracy,
 205             List<Language> languages,
 206             boolean highlightFragments,
 207             int maxNoOfResults) throws CorruptIndexException, IOException, ParseException;
 208
 209         /**
 210          * Fuzzy matching against the name cache using only the lucene index.
 211          *
 212          *
 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
 218          * @return
 219          * @throws CorruptIndexException
 220          * @throws IOException
 221          * @throws ParseException
 222          */
 223     public List<DocumentSearchResult> findByFuzzyNameCacheSearch(
 224             String name,
 225             float accuracy,
 226             List<Language> languages,
 227             boolean highlightFragments,
 228             int maxNoOfResults) throws CorruptIndexException, IOException, ParseException;
 229
 230         /**
 231          * Exact matching for the taxon name elements using only the lucene index.
 232          *
 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.
 236          *
 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
 242          * @return
 243          * @throws CorruptIndexException
 244          * @throws IOException
 245          * @throws ParseException
 246          */
 247
 248     public List<DocumentSearchResult> findByNameExactSearch(
 249             String name,
 250             boolean wildcard,
 251             List<Language> languages,
 252             boolean highlightFragments,
 253             int maxNoOfResults) throws CorruptIndexException, IOException, ParseException;
 254
 255         // TODO: Remove getNamesByName() methods. Use findNamesByTitle() instead.
 256
 257         // FIXME candidate for harmonization?
 258         public List findNamesByTitle(String title);
 259
 260         public List findNamesByTitle(String title, CdmBase sessionObject);
 261
 262     public List<HomotypicalGroup> getAllHomotypicalGroups(int limit, int start);
 263
 264         @Deprecated
 265     public List<RelationshipBase> getAllRelationships(int limit, int start);
 266
 267
 268         /**
 269          * Return a List of name relationships in which this name is related to
 270          * another name, optionally filtered by relationship type
 271          *
 272          * @param name
 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.
 276          * @param direction
 277          *            the direction of the NameRelationship, may be null to return all relationships
 278          * @param type
 279          *            the relationship type (or null to return all relationships)
 280          * @param pageSize
 281          *            The maximum number of relationships returned (can be null for
 282          *            all relationships)
 283          * @param pageNumber
 284          *            The offset (in pageSize chunks) from the start of the result
 285          *            set (0 - based)
 286          * @param orderHints
 287          *            may be null
 288          * @param propertyPaths
 289          *            properties to initialize - see
 290          *            {@link IBeanInitializer#initialize(Object, List)}
 291          * @return a Pager of NameRelationship instances
 292          */
 293         public List<NameRelationship> listNameRelationships(TaxonNameBase name,  NameRelationship.Direction direction, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 294
 295         /**
 296          * Return a List of name relationships in which this name is related to another name, optionally filtered
 297          * by relationship type
 298          *
 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
 307          */
 308         public Pager<NameRelationship> pageNameRelationships(TaxonNameBase name,  NameRelationship.Direction direction, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 309
 310         /**
 311          * Return a List of relationships in which this name is related to another name, optionally filtered
 312          * by relationship type
 313          *
 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
 322          */
 323         @Deprecated
 324         public List<NameRelationship> listFromNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 325
 326         /**
 327          * Return a List of relationships in which this name is related to another name, optionally filtered
 328          * by relationship type
 329          *
 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
 338          */
 339         @Deprecated
 340         public Pager<NameRelationship> pageFromNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 341
 342         /**
 343          * Return a List of relationships in which another name is related to this name, optionally filtered
 344          * by relationship type
 345          *
 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
 354          */
 355         @Deprecated
 356         public List<NameRelationship> listToNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 357
 358         /**
 359          * Return a List of relationships in which another name is related to this name, optionally filtered
 360          * by relationship type
 361          *
 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
 370          */
 371         @Deprecated
 372         public Pager<NameRelationship> pageToNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 373
 374
 375         /**
 376          * Return a List of hybrids related to this name, optionally filtered
 377          * by hybrid relationship type
 378          *
 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
 386          */
 387         public Pager<HybridRelationship> getHybridNames(NonViralName name, HybridRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 388
 389         /**
 390          * Return a List of types related to this name, optionally filtered
 391          * by type designation status
 392          *
 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
 398          */
 399         public Pager<TypeDesignationBase> getTypeDesignations(TaxonNameBase name,
 400                         SpecimenTypeDesignationStatus status, Integer pageSize, Integer pageNumber);
 401
 402         public Pager<TypeDesignationBase> getTypeDesignations(TaxonNameBase name,
 403                         SpecimenTypeDesignationStatus status, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 404
 405
 406         /**
 407          * Returns a List of TaxonNameBase instances that match the properties passed
 408          *
 409          * @param uninomial
 410          * @param infraGenericEpithet
 411          * @param specificEpithet
 412          * @param infraspecificEpithet
 413          * @param rank
 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
 419          */
 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);
 421
 422         /**
 423          * Returns a Paged List of TaxonNameBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 424          *
 425          * @param clazz filter the results by class (or pass null to return all TaxonNameBase instances)
 426          * @param queryString
 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)
 429          * @param orderHints
 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>
 436          */
 437         @Override
 438     public Pager<TaxonNameBase> search(Class<? extends TaxonNameBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 439
 440         /**
 441          * Returns a map that holds uuid, titleCache pairs of all names in the current database
 442          *
 443          * @return
 444          *                      a <code>Map</code> containing uuid and titleCache of names
 445          */
 446         public List<UuidAndTitleCache> getUuidAndTitleCacheOfNames();
 447
 448         /**
 449          * Return a Pager of names matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 450          *
 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)}
 458          * @param orderHints
 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
 463          */
 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);
 465
 466     /**
 467      * Returns a homotypical group with the given UUID or null if not homotypical group exists with that UUID
 468      *
 469      * @param uuid the uuid of the homotypical group
 470      * @return a homotypical group
 471      */
 472     public HomotypicalGroup findHomotypicalGroup(UUID uuid);
 473
 474     /**
 475      * @param uuid
 476      * @return
 477      */
 478     public List<TaggedText> getTaggedName(UUID uuid);
 479
 480         List<HashMap<String, String>> getNameRecords();
 481 }