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