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.LockMode;
  21 import org.hibernate.Session;
  22
  23 import eu.etaxonomy.cdm.api.service.pager.Pager;
  24 import eu.etaxonomy.cdm.model.common.ICdmBase;
  25 import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;
  26 import eu.etaxonomy.cdm.persistence.query.Grouping;
  27 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  28
  29
  30 /**
  31  * @author a.mueller
  32  *
  33  */
  34 /**
  35  * @author a.kohlbecker
  36  * @date 23.03.2009
  37  *
  38  * @param <T>
  39  */
  40 public interface IService<T extends ICdmBase>{
  41
  42         // FIXME what does this method do?
  43         public void clear();
  44
  45         /**
  46          * Obtain the specified lock mode on the given object t
  47          */
  48         public void lock(T t, LockMode lockMode);
  49
  50         /**
  51          * Refreshes a given object t using the specified lockmode
  52          *
  53      * All bean properties given in the <code>propertyPaths</code> parameter are recursively initialized.
  54          * <p>
  55          * For detailed description and examples <b>please refer to:</b>
  56          * {@link BeanInitializer#initialize(Object, List)}
  57          *
  58          * NOTE: in the case of lockmodes that hit the database (e.g. LockMode.READ), you will need to re-initialize
  59          * child propertiesto avoid a HibernateLazyInitializationException (even if the properties of the child
  60          * were initialized prior to the refresh).
  61          *
  62          * @param t
  63          * @param lockMode
  64          */
  65         public void refresh(T t, LockMode lockMode, List<String> propertyPaths);
  66
  67         /**
  68          * Returns a count of all entities of type <T>  optionally restricted
  69          * to objects belonging to a class that that extends <T>
  70          *
  71          * @param clazz the class of entities to be counted (can be null to count all entities of type <T>)
  72          * @return a count of entities
  73          */
  74         public int count(Class<? extends T> clazz);
  75
  76         /**
  77          * Delete an existing persistent object
  78          *
  79          * @param persistentObject the object to be deleted
  80          * @return the unique identifier of the deleted entity
  81          */
  82         public UUID delete(T persistentObject);
  83
  84         /**
  85          * Returns true if an entity of type <T> with a unique identifier matching the
  86          * identifier supplied exists in the database, or false if no such entity can be
  87          * found.
  88          * @param uuid the unique identifier of the entity required
  89          * @return an entity of type <T> matching the uuid, or null if that entity does not exist
  90          */
  91         public boolean exists(UUID uuid);
  92
  93         /**
  94          * Return a list of persisted entities that match the unique identifier
  95          * set supplied as an argument
  96          *
  97          * @param uuidSet the set of unique identifiers of the entities required
  98          * @return a list of entities of type <T>
  99          */
 100         public List<T> find(Set<UUID> uuidSet);
 101
 102         /**
 103          * Return a persisted entity that matches the unique identifier
 104          * supplied as an argument, or null if the entity does not exist
 105          *
 106          * @param uuid the unique identifier of the entity required
 107          * @return an entity of type <T>, or null if the entity does not exist
 108          */
 109         public T find(UUID uuid);
 110
 111         // FIXME should we expose this method?
 112         public Session getSession();
 113
 114         /**
 115      * Returns a sublist of objects matching the grouping projections supplied using the groups parameter
 116      *
 117      * It would be nice to be able to return a pager, but for the moment hibernate doesn't
 118      * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)
 119      *
 120      * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses
 121      * @param limit the maximum number of entities returned (can be null to return
 122          *            all entities)
 123      * @param start The (0-based) offset from the start of the recordset (can be null, equivalent of starting at the beginning of the recordset)
 124      * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property
 125      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 126      * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.
 127      */
 128         public List<Object[]> group(Class<? extends T> clazz,Integer limit, Integer start, List<Grouping> groups, List<String> propertyPaths);
 129
 130         /**
 131          * Returns a list of entities of type <T> optionally restricted
 132          * to objects belonging to a class that that extends <T>
 133          *
 134          * @param type  The type of entities to return (can be null to count all entities of type <T>)
 135          * @param limit The maximum number of objects returned (can be null for all matching objects)
 136          * @param start The offset from the start of the result set (0 - based, can be null - equivalent of starting at the beginning of the recordset)
 137          * @param orderHints
 138          *            Supports path like <code>orderHints.propertyNames</code> which
 139          *            include *-to-one properties like createdBy.username or
 140          *            authorTeam.persistentTitleCache
 141          * @param propertyPaths properties to be initialized
 142          * @return
 143          */
 144         public List<T> list(Class<? extends T> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 145
 146         /**
 147          * Finds the cdm entity specified by the <code>uuid</code> parameter and
 148          * initializes all its *ToOne relations.
 149          *
 150          * @param uuid
 151          * @return
 152          */
 153         public T load(UUID uuid);
 154
 155         /**
 156          * Finds the cdm entity specified by the <code>uuid</code> parameter and
 157          * recursively initializes all bean properties given in the
 158          * <code>propertyPaths</code> parameter.
 159          * <p>
 160          * For detailed description and examples <b>please refer to:</b>
 161          * {@link BeanInitializer#initialize(Object, List)}
 162          *
 163          * @param uuid
 164          * @return
 165          */
 166         public T load(UUID uuid, List<String> propertyPaths);
 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         public UUID merge(T transientObject);
 175
 176         /**
 177          * Returns a paged list of entities of type <T> optionally restricted
 178          * to objects belonging to a class that that extends <T>
 179          *
 180          * @param type  The type of entities to return (can be null to count all entities of type <T>)
 181          * @param pageSize The maximum number of objects returned (can be null for all matching objects)
 182          * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based,
 183          *                   can be null, equivalent of starting at the beginning of the recordset)
 184          * @param orderHints
 185          *            Supports path like <code>orderHints.propertyNames</code> which
 186          *            include *-to-one properties like createdBy.username or
 187          *            authorTeam.persistentTitleCache
 188          * @param propertyPaths properties to be initialized
 189          * @return a pager of objects of type <T>
 190          */
 191         public Pager<T> page(Class<? extends T> type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 192
 193         /**
 194          * Re-read the state of the given instance from the underlying database.
 195          *
 196          * Hibernate claims that it is inadvisable to use refresh in long-running-sessions.
 197          * I don't really see where we would get into a situation where problems as discussed
 198          * this forum thread would apply for our scenario
 199          *
 200          * http://forum.hibernate.org/viewtopic.php?t=974544
 201          *
 202          * @param persistentObject the object to be refreshed
 203          * @return the unique identifier
 204          */
 205         public UUID refresh(T persistentObject);
 206
 207         public List<T> rows(String tableName, int limit, int start);
 208
 209         /**
 210          * Save a collection containing new entities (persists the entities)
 211          * @param newInstances the new entities to be persisted
 212          * @return A Map containing the new entities, keyed using the generated UUID's
 213          *         of those entities
 214          */
 215         public Map<UUID,T> save(Collection<T> newInstances);
 216
 217         /**
 218          * Save a new entity (persists the entity)
 219          * @param newInstance the new entity to be persisted
 220          * @return A generated UUID for the new persistent entity
 221          */
 222         public UUID save(T newInstance);
 223
 224         /**
 225          * Save a new entity or update the persistent state of an existing
 226          * transient entity that has been persisted previously
 227          *
 228          * @param transientObject the entity to be persisted
 229          * @return The unique identifier of the persisted entity
 230          */
 231         public UUID saveOrUpdate(T transientObject);
 232
 233         /**
 234          * Save new entities or update the persistent state of existing
 235          * transient entities that have been persisted previously
 236          *
 237          * @param transientObjects the entities to be persisted
 238          * @return The unique identifier of the persisted entity
 239          */
 240         public Map<UUID,T> saveOrUpdate(Collection<T> transientObjects);
 241
 242     /**
 243          * Update the persistent state of an existing transient entity
 244          * that has been persisted previously
 245          *
 246          * @param transientObject the entity to be persisted
 247          * @return The unique identifier of the persisted entity
 248          */
 249         public UUID update(T transientObject);
 250
 251         /**
 252          * Method that lists the objects matching the example provided.
 253          * The includeProperties property is used to specify which properties of the example are used.
 254          *
 255          * If includeProperties is null or empty, then all literal properties are used (restrictions are
 256          * applied as in the Hibernate Query-By-Example API call Example.create(object)).
 257          *
 258          * If includeProperties is not empty then only literal properties that are named in the set are used to
 259          * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
 260          * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
 261          * criteria.createCriteria(property).add(Example.create(relatedObject)))
 262          *
 263          * @param example
 264          * @param includeProperties
 265          * @param limit the maximum number of entities returned (can be null to return
 266          *            all entities)
 267      * @param start The (0-based) offset from the start of the recordset
 268      * @param orderHints
 269          *            Supports path like <code>orderHints.propertyNames</code> which
 270          *            include *-to-one properties like createdBy.username or
 271      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 272          * @return a list of matching objects
 273          */
 274         public List<T> list(T example, Set<String> includeProperties, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 275 }