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