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          * Update the persistent instance with the identifier of the given detached <BR>
  65          * instance. If there is a persistent instance with the same identifier, an <BR>
  66          * exception is thrown. This operation cascades to associated instances if <BR>
  67          * the association is mapped with cascade="save-update".
  68          *
  69          * @param detachedObject
  70          *            transient instance of the object to update
  71          * @see Session#update(Object)
  72          */
  73         public void update(final T detachedObject);
  74
  75         /**
  76          * Refresh a persistent object.
  77          *
  78          * @param transientObject
  79          *            transient instance of the object to refresh
  80          * @see Session#refresh(Object)
  81          */
  82         void refresh(T transientObject);
  83
  84         /**
  85          * Load a persistent object.
  86          *
  87          * @param transientObject
  88          *            transient instance of the object to load
  89          * @param id
  90          *            object primary key
  91          * @see Session#load(Object, Serializable)
  92          */
  93         public void load(final T transientObject, final PK id);
  94
  95         /**
  96          * Lock a persistent object.
  97          *
  98          * @param transientObject
  99          *            transient instance of the object to lock
 100          * @param lockOptions
 101          *            lock options
 102          * @see Session#refresh(Object, LockOptions)
 103          */
 104         public void refresh(final T transientObject, final LockOptions lockOptions);
 105
 106         /**
 107          * Remove an object from persistent storage in the database.
 108          *
 109          * @param persistentObject
 110          *            a persistent object to delete from the database
 111          * @see Session#delete(Object)
 112          */
 113         void delete(T persistentObject);
 114
 115         /**
 116          * Retrieve an object that was previously persisted to the database using the given criteria.
 117          *
 118          * @param aCondition
 119          *            a search condition
 120          * @return an object found according to the given criteria
 121          */
 122         public T findByCriteria(Criterion aCondition);
 123
 124         /**
 125          * Retrieve an object that was previously persisted to the database using the given criteria.
 126          *
 127          * @param andParams
 128          *            a properties values to filter with AND condition
 129          * @return an object found according to the given criteria
 130          */
 131         public T findByCriteria(Properties andParams);
 132
 133         /**
 134          * Retrieve a list of all objects of the considered type T which were previously persisted to the database.
 135          *
 136          * @return a list of all objects of the considered type T
 137          */
 138         public List<T> getAll();
 139
 140         /**
 141          * Retrieve an ordered list of all objects of the considered type T which were previously persisted to the database.
 142          *
 143          * @param anOrder
 144          *            a result list order. Null is ignored and in such case the result list is unordered.
 145          * @return an ordered list of all objects of the considered type T
 146          */
 147         public List<T> getAll(Order... anOrder);
 148
 149         /**
 150          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 151          *
 152          * @param aDetachedCriteria
 153          *            search criteria
 154          * @return a list of objects filtered according to the given criteria
 155          */
 156         public List<T> getFilteredList(final DetachedCriteria aDetachedCriteria);
 157
 158         /**
 159          * Retrieve a first found object in the database using the given criteria.
 160          *
 161          * @param aDetachedCriteria
 162          *            search criteria
 163          * @return a first found object filtered according to the given criteria
 164          */
 165         public T getFirstResult(final DetachedCriteria aDetachedCriteria);
 166
 167         /**
 168          * Retrieve a list of DTO objects using the given criteria.
 169          *
 170          * @param <DTO>
 171          *            the class of returned DTOs
 172          * @param aDetachedCriteria
 173          *            search criteria
 174          * @return a list of DTO objects filtered according to the given criteria
 175          */
 176         public <DTO> List<DTO> getFilteredDTOList(
 177                         final DetachedCriteria aDetachedCriteria);
 178
 179         /**
 180          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 181          *
 182          * @param aCondition
 183          *            a search condition
 184          * @return a list of objects filtered according to the given criteria
 185          */
 186         public List<T> getFilteredList(Criterion aCondition);
 187
 188         /**
 189          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 190          *
 191          * @param aCondition
 192          *            a search condition
 193          * @param anOrder
 194          *            a result list order. Null is ignored and in such case the result list is unordered.
 195          * @return a list of objects filtered according to the given criteria
 196          */
 197         public List<T> getFilteredList(Criterion aCondition, Order... anOrder);
 198
 199         /**
 200          * Retrieve a list of objects which were previously persisted to the database using the given criteria.<BR>
 201          * Joined field allows applying a filter condition to the child object.<BR>
 202          * In the following example we get all knowledge elements of the "bestpractice" knowledge type:<BR>
 203          * <code>knowledgeElementDAO.getFilteredList(
 204                                 "type", Restrictions.eq("name", "bestpractice"));</code>
 205          *
 206          * @param joinField
 207          *            a field containing object to apply the condition
 208          *
 209          * @param aCondition
 210          *            a search condition
 211          * @return a list of objects filtered according to the given criteria
 212          */
 213         public List<T> getFilteredList(final String joinField,
 214                         final Criterion aCondition);
 215
 216         /**
 217          * Retrieve a list of objects which were previously persisted to the database using the given criteria.<BR>
 218          * Joined field allows applying a filter condition to the child object.<BR>
 219          * In the following example we get all knowledge elements of the "bestpractice" knowledge type:<BR>
 220          * <code>knowledgeElementDAO.getFilteredList(
 221                                 "type", Restrictions.eq("name", "bestpractice"), Order.asc("title"));</code>
 222          *
 223          * @param joinField
 224          *            a field containing object to apply the condition
 225          *
 226          * @param aCondition
 227          *            a search condition
 228          * @param anOrder
 229          *            a result list order. Null is ignored and in such case the result list is unordered.
 230          * @return a list of objects filtered according to the given criteria
 231          */
 232         public List<T> getFilteredList(final String joinField,
 233                         final Criterion aCondition, final Order... anOrder);
 234
 235         /**
 236          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 237          *
 238          * @param andParams
 239          *            a properties values to filter with AND condition
 240          * @return a list of objects filtered according to the given criteria
 241          */
 242         public List<T> getFilteredList(Properties andParams);
 243
 244         /**
 245          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 246          *
 247          * @param andParams
 248          *            a properties values to filter with AND condition
 249          * @param anOrder
 250          *            a result list order. Null is ignored and in such case the result list is unordered.
 251          * @return a list of objects filtered according to the given criteria
 252          */
 253         public List<T> getFilteredList(Properties andParams, Order... anOrder);
 254
 255         /**
 256          * Make a transient instance persistent. This operation cascades to <BR>
 257          * associated instances if the association is mapped with cascade="persist".
 258          *
 259          * @param transientObject
 260          *            transient instance of the object to be made persistent
 261          * @see Session#persist(Object)
 262          */
 263         public void persist(T transientObject);
 264
 265         /**
 266          * Copy the state of the given object onto the persistent object with the <BR>
 267          * same identifier. If there is no persistent instance currently associated<BR>
 268          * with the session, it will be loaded. Return the persistent instance. If <BR>
 269          * the given instance is unsaved, save a copy of and return it as a newly <BR>
 270          * persistent instance. The given instance does not become associated with <BR>
 271          * the session. This operation cascades to associated instances if the <BR>
 272          * association is mapped with cascade="merge".
 273          *
 274          * @param transientObject
 275          *            transient instance of the object to be merged with persistent data
 276          * @return merged persistent object
 277          * @see Session#merge(Object)
 278          */
 279         public T merge(T transientObject);
 280
 281         /**
 282          * Remove this instance from the session cache. Changes to the instance will<BR>
 283          * not be synchronized with the database. This operation cascades to <BR>
 284          * associated instances if the association is mapped with cascade="evict".
 285          *
 286          * @param persistentObject
 287          *            the object to be removed from session cache
 288          * @see Session#evict(Object)
 289          */
 290         public void evict(final T persistentObject);
 291
 292         /**
 293          * Synchronize the session data with the database.
 294          *
 295          * @see Session#flush()
 296          */
 297         public void flush();
 298 }