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.util.Collection;
  14 import java.util.List;
  15 import java.util.Map;
  16 import java.util.UUID;
  17
  18 import org.hibernate.criterion.Criterion;
  19
  20 import eu.etaxonomy.cdm.api.service.config.NameDeletionConfigurator;
  21 import eu.etaxonomy.cdm.api.service.exception.ReferencedObjectUndeletableException;
  22 import eu.etaxonomy.cdm.api.service.pager.Pager;
  23 import eu.etaxonomy.cdm.model.common.CdmBase;
  24 import eu.etaxonomy.cdm.model.common.OrderedTermVocabulary;
  25 import eu.etaxonomy.cdm.model.common.ReferencedEntityBase;
  26 import eu.etaxonomy.cdm.model.common.RelationshipBase;
  27 import eu.etaxonomy.cdm.model.common.TermVocabulary;
  28 import eu.etaxonomy.cdm.model.common.UuidAndTitleCache;
  29 import eu.etaxonomy.cdm.model.name.HomotypicalGroup;
  30 import eu.etaxonomy.cdm.model.name.HybridRelationship;
  31 import eu.etaxonomy.cdm.model.name.HybridRelationshipType;
  32 import eu.etaxonomy.cdm.model.name.NameRelationship;
  33 import eu.etaxonomy.cdm.model.name.NameRelationshipType;
  34 import eu.etaxonomy.cdm.model.name.NomenclaturalStatus;
  35 import eu.etaxonomy.cdm.model.name.NomenclaturalStatusType;
  36 import eu.etaxonomy.cdm.model.name.NonViralName;
  37 import eu.etaxonomy.cdm.model.name.Rank;
  38 import eu.etaxonomy.cdm.model.name.SpecimenTypeDesignationStatus;
  39 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  40 import eu.etaxonomy.cdm.model.name.TypeDesignationBase;
  41 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  42 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  43 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  44 import eu.etaxonomy.cdm.strategy.cache.TaggedText;
  45
  46 public interface INameService extends IIdentifiableEntityService<TaxonNameBase> {
  47
  48         /**
  49          * Deletes a name. Depening on the configurator state links to the name will either be
  50          * deleted or throw exceptions.<BR>
  51          * If name is <code>null</code> this method has no effect.
  52          * @param name
  53          * @param config
  54          * @throws ReferencedObjectUndeletableException
  55          */
  56         public UUID delete(TaxonNameBase name, NameDeletionConfigurator config) throws ReferencedObjectUndeletableException;
  57
  58         /**
  59          * Removes the given type designation from the given taxon name and deletes it from
  60          * the database if it is not connected to any other name.
  61          * If <code>typeDesignation</code> is <code>null</code> all type designations are deleted
  62          * from the given taxon name. If <code>name</code> is <code>null</code> all names are removed from
  63          * the given type designation. If both are <code>null</code> nothing happens.
  64          * @param typeDesignation
  65          * @param name
  66          * @return
  67          */
  68         public void deleteTypeDesignation(TaxonNameBase name, TypeDesignationBase typeDesignation);
  69
  70
  71         /**
  72          * Saves the given type designations.
  73          * @param typeDesignationCollection
  74          * @return
  75          */
  76         public Map<UUID, TypeDesignationBase> saveTypeDesignationAll(Collection<TypeDesignationBase> typeDesignationCollection);
  77
  78         public Map<UUID, ReferencedEntityBase> saveReferencedEntitiesAll(Collection<ReferencedEntityBase> referencedEntityCollection);
  79
  80         /**
  81          * Saves the given homotypical groups.
  82          * @param homotypicalGroups
  83          * @return
  84          */
  85         public Map<UUID, HomotypicalGroup> saveAllHomotypicalGroups(Collection<HomotypicalGroup> homotypicalGroups);
  86
  87         /**
  88          * Returns all nomenclatural status.
  89          * @param limit
  90          * @param start
  91          * @return
  92          */
  93         public List<NomenclaturalStatus> getAllNomenclaturalStatus(int limit, int start);
  94
  95         /**
  96          * Returns all type designations.
  97          * @param limit
  98          * @param start
  99          * @return
 100          */
 101         public List<TypeDesignationBase> getAllTypeDesignations(int limit, int start);
 102
 103         /**
 104          * @param name
 105          * @return
 106          */
 107         public List<TaxonNameBase> getNamesByName(String name);
 108
 109         /**
 110          * Returns all NonViralNames with a name cache that matches the given string
 111          * @param name
 112          * @return
 113          */
 114         public List<NonViralName> getNamesByNameCache(String nameCache);
 115
 116         /**
 117          * @param name
 118          * @param sessionObject An object that is attached to the session before executing the query
 119          * @return
 120          */
 121         public List getNamesByName(String name, CdmBase sessionObject);
 122
 123         // TODO: Remove getNamesByName() methods. Use findNamesByTitle() instead.
 124
 125         // FIXME candidate for harmonization?
 126         public List findNamesByTitle(String title);
 127
 128         public List findNamesByTitle(String title, CdmBase sessionObject);
 129
 130     public List<HomotypicalGroup> getAllHomotypicalGroups(int limit, int start);
 131
 132         @Deprecated
 133     public List<RelationshipBase> getAllRelationships(int limit, int start);
 134
 135         /**
 136          * Returns all Ranks
 137          * @return
 138          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 139          */
 140         public OrderedTermVocabulary<Rank> getRankVocabulary();
 141
 142         /**
 143          * Returns all NomenclaturalStatusTypes
 144          * @return
 145          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 146          */
 147         public TermVocabulary<NomenclaturalStatusType> getStatusTypeVocabulary();
 148
 149         /**
 150          * Returns TypeDesignationStatus vocabulary
 151          * @return
 152          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 153          */
 154         public TermVocabulary<SpecimenTypeDesignationStatus> getSpecimenTypeDesignationStatusVocabulary();
 155
 156         /**
 157          * Returns TypeDesignationStatus ordered vocabulary
 158          * @return
 159          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 160          */
 161         public OrderedTermVocabulary<SpecimenTypeDesignationStatus> getSpecimenTypeDesignationVocabulary();
 162
 163         /**
 164          * Returns all NameRelationshipTypes
 165          * @return
 166          * @deprecated use VocabularyService#getVocabulary(VocabularyEnum) instead
 167          */
 168         public TermVocabulary<NameRelationshipType> getNameRelationshipTypeVocabulary();
 169
 170         /**
 171          * Return a List of name relationships in which this name is related to
 172          * another name, optionally filtered by relationship type
 173          *
 174          * @param name
 175          *            the name on either the <i>"from side"</i> or on the
 176          *            <i>"to side"</i> of the relationship, depending on the
 177          *            <code>direction</code> of the relationship.
 178          * @param direction
 179          *            the direction of the NameRelationship, may be null to return all relationships
 180          * @param type
 181          *            the relationship type (or null to return all relationships)
 182          * @param pageSize
 183          *            The maximum number of relationships returned (can be null for
 184          *            all relationships)
 185          * @param pageNumber
 186          *            The offset (in pageSize chunks) from the start of the result
 187          *            set (0 - based)
 188          * @param orderHints
 189          *            may be null
 190          * @param propertyPaths
 191          *            properties to initialize - see
 192          *            {@link BeanInitializer#initialize(Object, List)}
 193          * @return a Pager of NameRelationship instances
 194          */
 195         public List<NameRelationship> listNameRelationships(TaxonNameBase name,  NameRelationship.Direction direction, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 196
 197         /**
 198          * Return a List of name relationships in which this name is related to another name, optionally filtered
 199          * by relationship type
 200          *
 201          * @param name the name on the <i>"from side"</i> of the relationship
 202          * @param direction the direction of the NameRelationship
 203          * @param type the relationship type (or null to return all relationships)
 204          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 205          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 206          * @param orderHints may be null
 207          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 208          * @return a Pager of NameRelationship instances
 209          */
 210         public Pager<NameRelationship> pageNameRelationships(TaxonNameBase name,  NameRelationship.Direction direction, NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 211
 212         /**
 213          * Return a List of relationships in which this name is related to another name, optionally filtered
 214          * by relationship type
 215          *
 216          * @param name the name on the <i>"from side"</i> of the relationship
 217          * @param type the relationship type (or null to return all relationships)
 218          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 219          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 220          * @param orderHints may be null
 221          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 222          * @return a Pager of NameRelationship instances
 223          * @deprecated use {@link #listNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
 224          */
 225         @Deprecated
 226         public List<NameRelationship> listFromNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 227
 228         /**
 229          * Return a List of relationships in which this name is related to another name, optionally filtered
 230          * by relationship type
 231          *
 232          * @param name the name on the <i>"from side"</i> of the relationship
 233          * @param type the relationship type (or null to return all relationships)
 234          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 235          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 236          * @param orderHints may be null
 237          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 238          * @return a Pager of NameRelationship instances
 239          * @deprecated use {@link #pageNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
 240          */
 241         @Deprecated
 242         public Pager<NameRelationship> pageFromNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 243
 244         /**
 245          * Return a List of relationships in which another name is related to this name, optionally filtered
 246          * by relationship type
 247          *
 248          * @param name the name on the <i>"to side"</i> of the relationship
 249          * @param type the relationship type (or null to return all relationships)
 250          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 251          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 252          * @param orderHints may be null
 253          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 254          * @return a Pager of NameRelationship instances
 255          * @deprecated use {@link #listNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
 256          */
 257         @Deprecated
 258         public List<NameRelationship> listToNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 259
 260         /**
 261          * Return a List of relationships in which another name is related to this name, optionally filtered
 262          * by relationship type
 263          *
 264          * @param name the name on the <i>"to side"</i> of the relationship
 265          * @param type the relationship type (or null to return all relationships)
 266          * @param pageSize The maximum number of relationships returned (can be null for all relationships)
 267          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 268          * @param orderHints may be null
 269          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 270          * @return a Pager of NameRelationship instances
 271          * @deprecated use {@link #pageNameRelationships(TaxonNameBase, eu.etaxonomy.cdm.model.common.RelationshipBase.Direction, NameRelationshipType, Integer, Integer, List, List)} instead
 272          */
 273         @Deprecated
 274         public Pager<NameRelationship> pageToNameRelationships(TaxonNameBase name,  NameRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 275
 276
 277         /**
 278          * Return a List of hybrids related to this name, optionally filtered
 279          * by hybrid relationship type
 280          *
 281          * @param name the name
 282          * @param type the hybrid relationship type (or null to return all hybrids)
 283          * @param pageSize The maximum number of hybrid relationships returned (can be null for all relationships)
 284          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 285          * @param orderHints may be null
 286          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 287          * @return a Pager of HybridRelationship instances
 288          */
 289         public Pager<HybridRelationship> getHybridNames(NonViralName name, HybridRelationshipType type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 290
 291         /**
 292          * Return a List of types related to this name, optionally filtered
 293          * by type designation status
 294          *
 295          * @param name the name
 296          * @param status the type designation status (or null to return all types)
 297          * @param pageSize The maximum number of types returned (can be null for all types)
 298          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 299          * @return a Pager of TypeDesignationBase instances
 300          */
 301         public Pager<TypeDesignationBase> getTypeDesignations(TaxonNameBase name,
 302                         SpecimenTypeDesignationStatus status, Integer pageSize, Integer pageNumber);
 303
 304         public Pager<TypeDesignationBase> getTypeDesignations(TaxonNameBase name,
 305                         SpecimenTypeDesignationStatus status, Integer pageSize, Integer pageNumber, List<String> propertyPaths);
 306
 307
 308         /**
 309          * Returns a List of TaxonNameBase instances that match the properties passed
 310          *
 311          * @param uninomial
 312          * @param infraGenericEpithet
 313          * @param specificEpithet
 314          * @param infraspecificEpithet
 315          * @param rank
 316          * @param pageSize The maximum number of names returned (can be null for all names)
 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 BeanInitializer#initialize(Object, List)}
 320          * @return a Pager of TaxonNameBase instances
 321          */
 322         public Pager<TaxonNameBase> searchNames(String uninomial, String infraGenericEpithet, String specificEpithet, String infraspecificEpithet, Rank rank, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 323
 324         /**
 325          * Returns a Paged List of TaxonNameBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)
 326          *
 327          * @param clazz filter the results by class (or pass null to return all TaxonNameBase instances)
 328          * @param queryString
 329          * @param pageSize The maximum number of names returned (can be null for all matching names)
 330          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 331          * @param orderHints
 332          *            Supports path like <code>orderHints.propertyNames</code> which
 333          *            include *-to-one properties like createdBy.username or
 334          *            authorTeam.persistentTitleCache
 335          * @param propertyPaths properties to be initialized
 336          * @return a Pager TaxonNameBase instances
 337          * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>
 338          */
 339         public Pager<TaxonNameBase> search(Class<? extends TaxonNameBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 340
 341         /**
 342          * Returns a map that holds uuid, titleCache pairs of all names in the current database
 343          *
 344          * @return
 345          *                      a <code>Map</code> containing uuid and titleCache of names
 346          */
 347         public List<UuidAndTitleCache> getUuidAndTitleCacheOfNames();
 348
 349         /**
 350          * Return a Pager of names matching the given query string, optionally filtered by class, optionally with a particular MatchMode
 351          *
 352          * @param clazz filter by class - can be null to include all instances of type T
 353          * @param queryString the query string to filter by
 354          * @param matchmode use a particular type of matching (can be null - defaults to exact matching)
 355          * @param criteria additional criteria to filter by
 356          * @param pageSize The maximum number of objects returned (can be null for all objects)
 357          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
 358          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 359          * @param orderHints
 360          *            Supports path like <code>orderHints.propertyNames</code> which
 361          *            include *-to-one properties like createdBy.username or
 362          *            authorTeam.persistentTitleCache
 363          * @return a paged list of instances of type T matching the queryString
 364          */
 365     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);
 366
 367     /**
 368      * Returns a homotypical group with the given UUID or null if not homotypical group exists with that UUID
 369      *
 370      * @param uuid the uuid of the homotypical group
 371      * @return a homotypical group
 372      */
 373     public HomotypicalGroup findHomotypicalGroup(UUID uuid);
 374
 375     /**
 376      * @param uuid
 377      * @return
 378      */
 379     public List<TaggedText> getTaggedName(UUID uuid);
 380 }