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