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 list of DTO objects using the given criteria.
 160          *
 161          * @param <DTO>
 162          *            the class of returned DTOs
 163          * @param aDetachedCriteria
 164          *            search criteria
 165          * @return a list of DTO objects filtered according to the given criteria
 166          */
 167         public <DTO> List<DTO> getFilteredDTOList(
 168                         final DetachedCriteria aDetachedCriteria);
 169
 170         /**
 171          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 172          *
 173          * @param aCondition
 174          *            a search condition
 175          * @return a list of objects filtered according to the given criteria
 176          */
 177         public List<T> getFilteredList(Criterion aCondition);
 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          * @param anOrder
 185          *            a result list order. Null is ignored and in such case the result list is unordered.
 186          * @return a list of objects filtered according to the given criteria
 187          */
 188         public List<T> getFilteredList(Criterion aCondition, Order... anOrder);
 189
 190         /**
 191          * Retrieve a list of objects which were previously persisted to the database using the given criteria.<BR>
 192          * Joined field allows applying a filter condition to the child object.<BR>
 193          * In the following example we get all knowledge elements of the "bestpractice" knowledge type:<BR>
 194          * <code>knowledgeElementDAO.getFilteredList(
 195                                 "type", Restrictions.eq("name", "bestpractice"));</code>
 196          *
 197          * @param joinField
 198          *            a field containing object to apply the condition
 199          *
 200          * @param aCondition
 201          *            a search condition
 202          * @return a list of objects filtered according to the given criteria
 203          */
 204         public List<T> getFilteredList(final String joinField,
 205                         final Criterion aCondition);
 206
 207         /**
 208          * Retrieve a list of objects which were previously persisted to the database using the given criteria.<BR>
 209          * Joined field allows applying a filter condition to the child object.<BR>
 210          * In the following example we get all knowledge elements of the "bestpractice" knowledge type:<BR>
 211          * <code>knowledgeElementDAO.getFilteredList(
 212                                 "type", Restrictions.eq("name", "bestpractice"), Order.asc("title"));</code>
 213          *
 214          * @param joinField
 215          *            a field containing object to apply the condition
 216          *
 217          * @param aCondition
 218          *            a search condition
 219          * @param anOrder
 220          *            a result list order. Null is ignored and in such case the result list is unordered.
 221          * @return a list of objects filtered according to the given criteria
 222          */
 223         public List<T> getFilteredList(final String joinField,
 224                         final Criterion aCondition, final Order... anOrder);
 225
 226         /**
 227          * Retrieve a list of objects which were previously persisted to the database using the given criteria.
 228          *
 229          * @param andParams
 230          *            a properties values to filter with AND condition
 231          * @return a list of objects filtered according to the given criteria
 232          */
 233         public List<T> getFilteredList(Properties andParams);
 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          * @param anOrder
 241          *            a result list order. Null is ignored and in such case the result list is unordered.
 242          * @return a list of objects filtered according to the given criteria
 243          */
 244         public List<T> getFilteredList(Properties andParams, Order... anOrder);
 245
 246         /**
 247          * Make a transient instance persistent. This operation cascades to <BR>
 248          * associated instances if the association is mapped with cascade="persist".
 249          *
 250          * @param transientObject
 251          *            transient instance of the object to be made persistent
 252          * @see Session#persist(Object)
 253          */
 254         public void persist(T transientObject);
 255
 256         /**
 257          * Copy the state of the given object onto the persistent object with the <BR>
 258          * same identifier. If there is no persistent instance currently associated<BR>
 259          * with the session, it will be loaded. Return the persistent instance. If <BR>
 260          * the given instance is unsaved, save a copy of and return it as a newly <BR>
 261          * persistent instance. The given instance does not become associated with <BR>
 262          * the session. This operation cascades to associated instances if the <BR>
 263          * association is mapped with cascade="merge".
 264          *
 265          * @param transientObject
 266          *            transient instance of the object to be merged with persistent data
 267          * @return merged persistent object
 268          * @see Session#merge(Object)
 269          */
 270         public T merge(T transientObject);
 271
 272         /**
 273          * Remove this instance from the session cache. Changes to the instance will<BR>
 274          * not be synchronized with the database. This operation cascades to <BR>
 275          * associated instances if the association is mapped with cascade="evict".
 276          *
 277          * @param persistentObject
 278          *            the object to be removed from session cache
 279          * @see Session#evict(Object)
 280          */
 281         public void evict(final T persistentObject);
 282
 283         /**
 284          * Synchronize the session data with the database.
 285          *
 286          * @see Session#flush()
 287          */
 288         public void flush();
 289 }