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