Workspace/Siman-Common/src/org/splat/dal/dao/kernel/GenericDAO.java

   1 /*****************************************************************************
   2  * Company         OPEN CASCADE
   3  * Application     SIMAN
   4  * File            $Id$
   5  * Creation date   08.10.2012
   6  * @author         $Author$
   7  * @version        $Revision$
   8  *****************************************************************************/
   9
  10 package org.splat.dal.dao.kernel;
  11
  12 import java.io.Serializable;
  13 import java.util.List;
  14 import java.util.Properties;
  15
  16 import org.hibernate.LockOptions;
  17 import org.hibernate.Session;
  18 import org.hibernate.criterion.Criterion;
  19 import org.hibernate.criterion.DetachedCriteria;
  20 import org.hibernate.criterion.Order;
  21
  22 /**
  23  * Generic DAO interface.
  24  *
  25  * @author <a href="mailto:roman.kozlov@opencascade.com">Roman Kozlov (RKV)</a>
  26  *
  27  * @param <T>
  28  *            Persistent object class
  29  * @param <PK>
  30  *            Primary key class
  31  */
  32 public interface GenericDAO<T, PK extends Serializable> {
  33
  34         /**
  35          * Persist the newInstance object into database.
  36          *
  37          * @param newInstance
  38          *            new object as a transient instance
  39          * @return new primary key for the created persistent object
  40          * @see Session#save(Object)
  41          */
  42         PK create(T newInstance);
  43
  44         /**
  45          * Persist the newInstance object into database.
  46          *
  47          * @param newInstance
  48          *            new object as a transient instance
  49          * @see Session#saveOrUpdate(Object)
  50          */
  51         public void saveOrUpdate(final T newInstance);
  52
  53         /**
  54          * Retrieve an object that was previously persisted to the database using the indicated id as primary key.
  55          *
  56          * @param id
  57          *            primary key of an object to read
  58          * @return an object found by the given key
  59          * @see Session#get(Class, Serializable)
  60          */
  61         T get(PK id);
  62
  63         /**
  64          * Save changes made to a persistent object.
  65          *
  66          * @param transientObject
  67          *            transient instance of the object to update
  68          */
  69         void update(T transientObject);
  70
  71         /**
  72          * Refresh a persistent object.
  73          *
  74          * @param transientObject
  75          *            transient instance of the object to refresh
  76          * @see Session#refresh(Object)
  77          */
  78         void refresh(T transientObject);
  79
  80         /**
  81          * Load a persistent object.
  82          *
  83          * @param transientObject
  84          *            transient instance of the object to load
  85          * @param id
  86          *            object primary key
  87          * @see Session#load(Object, Serializable)
  88          */
  89         public void load(final T transientObject, final PK id);
  90
  91         /**
  92          * Lock a persistent object.
  93          *
  94          * @param transientObject
  95          *            transient instance of the object to lock
  96          * @param lockOptions
  97          *            lock options
  98          * @see Session#refresh(Object, LockOptions)
  99          */
 100         public void refresh(final T transientObject, final LockOptions lockOptions);
 101
 102         /**
 103          * Remove an object from persistent storage in the database.
 104          *
 105          * @param persistentObject
 106          *            a persistent object to delete from the database
 107          * @see Session#delete(Object)
 108          */
 109         void delete(T persistentObject);
 110
 111         /**
 112          * Retrieve an object that was previously persisted to the database using the given criteria.
 113          *
 114          * @param aCondition
 115          *            a search condition
 116          * @return an object found according to the given criteria
 117          */
 118         public T findByCriteria(Criterion aCondition);
 119
 120         /**
 121          * Retrieve an object that was previously persisted to the database using the given criteria.
 122          *
 123          * @param andParams
 124          *            a properties values to filter with AND condition
 125          * @return an object found according to the given criteria
 126          */
 127         public T findByCriteria(Properties andParams);
 128
 129         /**
 130          * Retrieve a list of all objects of the considered type T which were previously persisted to the database.
 131          *
 132          * @return a list of all objects of the considered type T
 133          */
 134         public List<T> getAll();
 135
 136         /**
 137          * Retrieve an ordered list of all objects of the considered type T which were previously persisted to the database.
 138          *
 139          * @param anOrder
 140          *            a result list order. Null is ignored and in such case the result list is unordered.
 141          * @return an ordered list of all objects of the considered type T
 142          */
 143         public List<T> getAll(Order... anOrder);
 144
 145         /**
 146          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 147          *
 148          * @param aDetachedCriteria
 149          *            search criteria
 150          * @return a list of objects filtered according to the given criteria
 151          */
 152         public List<T> getFilteredList(final DetachedCriteria aDetachedCriteria);
 153
 154         /**
 155          * Retrieve a list of DTO objects using the given criteria.
 156          *
 157          * @param <DTO>
 158          *            the class of returned DTOs
 159          * @param aDetachedCriteria
 160          *            search criteria
 161          * @return a list of DTO objects filtered according to the given criteria
 162          */
 163         public <DTO> List<DTO> getFilteredDTOList(
 164                         final DetachedCriteria aDetachedCriteria);
 165
 166         /**
 167          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 168          *
 169          * @param aCondition
 170          *            a search condition
 171          * @return a list of objects filtered according to the given criteria
 172          */
 173         public List<T> getFilteredList(Criterion aCondition);
 174
 175         /**
 176          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 177          *
 178          * @param aCondition
 179          *            a search condition
 180          * @param anOrder
 181          *            a result list order. Null is ignored and in such case the result list is unordered.
 182          * @return a list of objects filtered according to the given criteria
 183          */
 184         public List<T> getFilteredList(Criterion aCondition, Order... anOrder);
 185
 186         /**
 187          * Retrieve a list of objects which were previously persisted to the database using the given criteria.<BR>
 188          * Joined field allows applying a filter condition to the child object.<BR>
 189          * In the following example we get all knowledge elements of the "bestpractice" knowledge type:<BR>
 190          * <code>knowledgeElementDAO.getFilteredList(
 191                                 "type", Restrictions.eq("name", "bestpractice"));</code>
 192          *
 193          * @param joinField
 194          *            a field containing object to apply the condition
 195          *
 196          * @param aCondition
 197          *            a search condition
 198          * @return a list of objects filtered according to the given criteria
 199          */
 200         public List<T> getFilteredList(final String joinField,
 201                         final Criterion aCondition);
 202
 203         /**
 204          * Retrieve a list of objects which were previously persisted to the database using the given criteria.<BR>
 205          * Joined field allows applying a filter condition to the child object.<BR>
 206          * In the following example we get all knowledge elements of the "bestpractice" knowledge type:<BR>
 207          * <code>knowledgeElementDAO.getFilteredList(
 208                                 "type", Restrictions.eq("name", "bestpractice"), Order.asc("title"));</code>
 209          *
 210          * @param joinField
 211          *            a field containing object to apply the condition
 212          *
 213          * @param aCondition
 214          *            a search condition
 215          * @param anOrder
 216          *            a result list order. Null is ignored and in such case the result list is unordered.
 217          * @return a list of objects filtered according to the given criteria
 218          */
 219         public List<T> getFilteredList(final String joinField,
 220                         final Criterion aCondition, final Order... anOrder);
 221
 222         /**
 223          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 224          *
 225          * @param andParams
 226          *            a properties values to filter with AND condition
 227          * @return a list of objects filtered according to the given criteria
 228          */
 229         public List<T> getFilteredList(Properties andParams);
 230
 231         /**
 232          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 233          *
 234          * @param andParams
 235          *            a properties values to filter with AND condition
 236          * @param anOrder
 237          *            a result list order. Null is ignored and in such case the result list is unordered.
 238          * @return a list of objects filtered according to the given criteria
 239          */
 240         public List<T> getFilteredList(Properties andParams, Order... anOrder);
 241
 242         /**
 243          * Make a transient instance persistent. This operation cascades to <BR>
 244          * associated instances if the association is mapped with cascade="persist".
 245          *
 246          * @param transientObject
 247          *            transient instance of the object to be made persistent
 248          * @see Session#persist(Object)
 249          */
 250         public void persist(T transientObject);
 251
 252         /**
 253          * Copy the state of the given object onto the persistent object with the <BR>
 254          * same identifier. If there is no persistent instance currently associated<BR>
 255          * with the session, it will be loaded. Return the persistent instance. If <BR>
 256          * the given instance is unsaved, save a copy of and return it as a newly <BR>
 257          * persistent instance. The given instance does not become associated with <BR>
 258          * the session. This operation cascades to associated instances if the <BR>
 259          * association is mapped with cascade="merge".
 260          *
 261          * @param transientObject
 262          *            transient instance of the object to be merged with persistent data
 263          * @return merged persistent object
 264          * @see Session#merge(Object)
 265          */
 266         public T merge(T transientObject);
 267
 268         /**
 269          * Remove this instance from the session cache. Changes to the instance will<BR>
 270          * not be synchronized with the database. This operation cascades to <BR>
 271          * associated instances if the association is mapped with cascade="evict".
 272          *
 273          * @param persistentObject
 274          *            the object to be removed from session cache
 275          * @see Session#evict(Object)
 276          */
 277         public void evict(final T persistentObject);
 278
 279         /**
 280          * Synchronize the session data with the database.
 281          *
 282          * @see Session#flush()
 283          */
 284         public void flush();
 285 }