cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IService.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
  14 import java.util.Collection;
  15 import java.util.List;
  16 import java.util.Map;
  17 import java.util.Set;
  18 import java.util.UUID;
  19
  20 import org.hibernate.Session;
  21 import org.springframework.transaction.annotation.Propagation;
  22 import org.springframework.transaction.annotation.Transactional;
  23
  24 import eu.etaxonomy.cdm.api.service.pager.Pager;
  25 import eu.etaxonomy.cdm.model.common.CdmBase;
  26 import eu.etaxonomy.cdm.model.reference.ReferenceBase;
  27 import eu.etaxonomy.cdm.model.taxon.TaxonBase;
  28 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  29 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  30
  31
  32 /**
  33  * @author a.mueller
  34  *
  35  */
  36 /**
  37  * @author a.kohlbecker
  38  * @date 23.03.2009
  39  *
  40  * @param <T>
  41  */
  42 @Transactional(propagation=Propagation.SUPPORTS, readOnly=true)
  43 public interface IService<T extends CdmBase>{
  44
  45         /**
  46          * Returns a count of all entities of type <T>
  47          * @return a count of all entities
  48          */
  49         public int count();
  50
  51         /**
  52          * Returns a count of all entities of type <TYPE> that extend <T>
  53          * @param clazz the class of entities to be counted
  54          * @return a count of entities
  55          */
  56         public <TYPE extends T> int count(Class<TYPE> clazz);
  57
  58         /**
  59          * Returns a List of entities of type <T>
  60          * TODO would like to substitute List with Pager, but we need
  61          * to agree on how to implement paging first
  62          *
  63          * @param limit The maximum number of entities returned
  64          * @param start The offset from the start of the dataset
  65          * @return a List of entities
  66          */
  67         public List<T> list(int limit, int start);
  68
  69         /**
  70          * Returns a List of entities of type <TYPE> which must extend
  71          * <T>
  72          * TODO would like to substitute List with Pager, but we need
  73          * to agree on how to implement paging first
  74          *
  75          * @param type  The type of entities to return
  76          * @param limit The maximum number of entities returned
  77          * @param start The offset from the start of the dataset
  78          * @return a List of entities
  79          */
  80         public <TYPE extends T> List<TYPE> list(Class<TYPE> type, int limit, int start);
  81
  82
  83         /**
  84          * @param pageSize
  85          *            the maximum number of entities returned per page (can be null
  86          *            to return all entities in a single page)
  87          * @param pageNumber the number of the page to be returned, the first page has the
  88          *            pageNumber = 1
  89          * @return
  90          */
  91         public Pager<T> list(Integer pageSize, Integer pageNumber);
  92
  93
  94         /**
  95          * @param pageSize
  96          *            the maximum number of entities returned per page (can be null
  97          *            to return all entities in a single page)
  98          * @param pageNumber
  99          *            the number of the page to be returned, the first page has the
 100          *            pageNumber = 1
 101          * @param orderHints
 102          *            may be null
 103          * @return
 104          */
 105         public Pager<T> list(Integer pageSize, Integer pageNumber, List<OrderHint> orderHints);
 106
 107         /**
 108           Returns a paged list of entities of type <TYPE> which must extend
 109          * <T>
 110          *
 111          * @param type  The type of entities to return
 112          * @param pageSize
 113          * @param pageNumber
 114          * @param orderHints may be null
 115          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 116          * @return
 117          */
 118         public <TYPE extends T> Pager<TYPE> list(Class<TYPE> type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 119
 120         /**
 121          * @param pageSize
 122          * @param pageNumber
 123          * @param orderHints may be null
 124          * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}
 125          * @return
 126          */
 127         public Pager<T> list(Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 128
 129         public List<T> rows(String tableName, int limit, int start);
 130
 131         /**
 132          * Save a new entity (persists the entity)
 133          * @param newInstance the new entity to be persisted
 134          * @return A generated UUID for the new persistent entity
 135          */
 136         @Transactional(readOnly=false)
 137         public UUID save(T newInstance);
 138
 139         /**
 140          * Save a new entity or update the persistent state of an existing
 141          * transient entity that has been persisted previously
 142          *
 143          * @param transientObject the entity to be persisted
 144          * @return The unique identifier of the persisted entity
 145          */
 146         @Transactional(readOnly=false)
 147         public UUID saveOrUpdate(T transientObject);
 148
 149         /**
 150          * Update the persistent state of an existing transient entity
 151          * that has been persisted previously
 152          *
 153          * @param transientObject the entity to be persisted
 154          * @return The unique identifier of the persisted entity
 155          */
 156         @Transactional(readOnly=false)
 157         public UUID update(T transientObject);
 158
 159         /**
 160          * Copy the state of the given object onto the persistent object with the same identifier.
 161          *
 162          * @param transientObject the entity to be merged
 163          * @return The unique identifier of the persisted entity
 164          */
 165         @Transactional(readOnly=false)
 166         public UUID merge(T transientObject);
 167
 168         /**
 169          * Copy the state of the given object onto the persistent object with the same identifier.
 170          *
 171          * @param transientObject the entity to be merged
 172          * @return The unique identifier of the persisted entity
 173          */
 174 //      @Transactional(readOnly=false)
 175         public void clear();
 176
 177         public Session getSession();
 178
 179         /**
 180          * Save a collection containing new entities (persists the entities)
 181          * @param newInstances the new entities to be persisted
 182          * @return A Map containing the new entities, keyed using the generated UUID's
 183          *         of those entities
 184          */
 185         @Transactional(readOnly=false)
 186         public Map<UUID,T> saveAll(Collection<T> newInstances);
 187
 188         /**
 189          * Re-read the state of the given instance from the underlying database.
 190          *
 191          * Hibernate claims that it is inadvisable to use refresh in long-running-sessions.
 192          * I don't really see where we would get into a situation where problems as discussed
 193          * this forum thread would apply for our scenario
 194          *
 195          * http://forum.hibernate.org/viewtopic.php?t=974544
 196          *
 197          * @param persistentObject the object to be refreshed
 198          * @return the unique identifier
 199          */
 200         @Transactional(readOnly=false)
 201         public UUID refresh(T persistentObject);
 202
 203         /**
 204          * Delete an existing persistent object
 205          *
 206          * @param persistentObject the object to be deleted
 207          * @return the unique identifier of the deleted entity
 208          */
 209         @Transactional(readOnly=false)
 210         public UUID delete(T persistentObject);
 211
 212         /**
 213          * Return a persisted entity that matches the unique identifier
 214          * supplied as an argument, or null if the entity does not exist
 215          *
 216          * @param uuid the unique identifier of the entity required
 217          * @return an entity of type <T>, or null if the entity does not exist
 218          */
 219         public T findByUuid(UUID uuid);
 220
 221         /**
 222          * Return a list of persisted entities that match the unique identifier
 223          * set supplied as an argument
 224          *
 225          * @param uuidSet the set of unique identifiers of the entities required
 226          * @return a list of entities of type <T>
 227          */
 228         public List<T> findByUuid(Set<UUID> uuidSet);
 229
 230         /**
 231          * Finds the cdm entity specified by the <code>uuid</code> parameter and
 232          * initializes all its *ToOne relations.
 233          *
 234          * @param uuid
 235          * @return
 236          */
 237         public T load(UUID uuid);
 238
 239         /**
 240          * Finds the cdm entity specified by the <code>uuid</code> parameter and
 241          * recursively initializes all bean properties given in the
 242          * <code>propertyPaths</code> parameter.
 243          * <p>
 244          * For detailed description and examples <b>please refer to:</b>
 245          * {@link BeanInitializer#initialize(Object, List)}
 246          *
 247          * @param uuid
 248          * @return
 249          */
 250         public T load(UUID uuid, List<String> propertyPaths);
 251
 252
 253
 254         /**
 255          * Returns true if an entity of type <T> with a unique identifier matching the
 256          * identifier supplied exists in the database, or false if no such entity can be
 257          * found.
 258          * @param uuid the unique identifier of the entity required
 259          * @return an entity of type <T> matching the uuid, or null if that entity does not exist
 260          */
 261         public boolean exists(UUID uuid);
 262 }