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