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