cdmlib-persistence/src/main/java/eu/etaxonomy/cdm/persistence/dao/common/ICdmEntityDao.java

   1 /**
   2 * Copyright (C) 2007 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9
  10 package eu.etaxonomy.cdm.persistence.dao.common;
  11
  12 import java.util.Collection;
  13 import java.util.List;
  14 import java.util.Map;
  15 import java.util.Set;
  16 import java.util.UUID;
  17
  18 import org.hibernate.LockOptions;
  19 import org.hibernate.Session;
  20 import org.hibernate.criterion.Criterion;
  21 import org.springframework.dao.DataAccessException;
  22
  23 import eu.etaxonomy.cdm.model.common.CdmBase;
  24 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  25 import eu.etaxonomy.cdm.persistence.dto.MergeResult;
  26 import eu.etaxonomy.cdm.persistence.query.Grouping;
  27 import eu.etaxonomy.cdm.persistence.query.MatchMode;
  28 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  29 import javassist.tools.rmi.ObjectNotFoundException;
  30
  31 /**
  32  * An data access interface that all data access classes implement
  33  * @author m.doering
  34  * @since 02-Nov-2007 19:36:10
  35  */
  36 public interface ICdmEntityDao<T extends CdmBase> {
  37
  38     public UUID saveOrUpdate(T transientObject) throws DataAccessException;
  39
  40     public <S extends T> S save(S newInstance) throws DataAccessException;
  41
  42     public T merge(T transientObject) throws DataAccessException;
  43
  44     /**
  45      * This method allows for the possibility of returning the input transient
  46      * entity instead of the merged persistent entity
  47      *
  48      * WARNING : This method should never be used when the objective of the merge
  49      * is to attach to an existing session which is the standard use case.
  50      * This method should only be used in the case of an external call which does
  51      * not use hibernate sessions and is only interested in the entity as a POJO.
  52      * This method returns the root merged transient entity as well as all newly merged
  53      * persistent entities within the return object.
  54      *
  55      * @param transientObject
  56      * @param returnTransientEntity
  57      * @return transient or persistent object depending on the value of returnTransientEntity
  58      * @throws DataAccessException
  59      */
  60     public MergeResult<T> merge(T transientObject, boolean returnTransientEntity) throws DataAccessException;
  61
  62     /**
  63      * Obtains the specified LockMode on the supplied object
  64      *
  65      * @param t
  66      * @param lockOptions
  67      * @throws DataAccessException
  68      */
  69     public void lock(T t, LockOptions lockOptions) throws DataAccessException;
  70
  71     /**
  72      * Globally replace all references to instance t1 with t2 (including
  73      *
  74      * NOTE: This replaces all non-bidirectional relationships where type T is on the
  75      * "owning" side of the relationship (since the "owned" objects are, in theory,
  76      * sub-components of the entity and this kind of global replace doesn't really make sense
  77      *
  78      * Consequently it is a good idea to either map such owned relationships with cascading
  79      * semantics (i.e. CascadeType.DELETE, @OneToMany(orphanRemoval=true)) allowing them to be saved,
  80      * updated, and deleted along with the owning entity automatically.
  81      *
  82      * @param x the object to replace, must not be null
  83      * @param y the object that will replace. If y is null, then x will be removed from all collections
  84      *          and all properties that refer to x will be replaced with null
  85      * @return T the replaced object
  86      */
  87     public T replace(T x, T y);
  88
  89     /**
  90      * Refreshes the state of the supplied object using the given LockMode (e.g. use LockMode.READ
  91      * to bypass the second-level cache and session cache and query the database directly)
  92      *
  93      * All bean properties given in the <code>propertyPaths</code> parameter are recursively initialized.
  94      * <p>
  95      * For detailed description and examples <b>please refer to:</b>
  96      * {@link IBeanInitializer#initialize(Object, List)}
  97      *
  98      * @param t
  99      * @param lockMode
 100      * @param propertyPaths
 101      * @throws DataAccessException
 102      */
 103     public void refresh(T t, LockOptions lockOptions, List<String> propertyPaths) throws DataAccessException;
 104
 105     public void clear() throws DataAccessException;
 106
 107     public Session getSession() throws DataAccessException;
 108
 109     public Map<UUID, T> saveAll(Collection<? extends T> cdmObjCollection) throws DataAccessException;
 110
 111     public Map<UUID, T> saveOrUpdateAll(Collection<T> cdmObjCollection);
 112
 113     /**
 114      * @param transientObject
 115      * @return
 116      * @throws DataAccessException
 117      */
 118     public UUID update(T transientObject) throws DataAccessException;
 119
 120     /**
 121      * @param persistentObject
 122      * @return
 123      * @throws DataAccessException
 124      */
 125     public UUID refresh(T persistentObject) throws DataAccessException;
 126
 127     /**
 128      * @param persistentObject
 129      * @return
 130      * @throws DataAccessException
 131      */
 132     public UUID delete(T persistentObject) throws DataAccessException;
 133
 134     /**
 135      * Returns a sublist of CdmBase instances stored in the database.
 136      * A maximum of 'limit' objects are returned, starting at object with index 'start'.
 137      * @param limit the maximum number of entities returned (can be null to return all entities)
 138      * @param start
 139      * @return
 140      * @throws DataAccessException
 141      */
 142     public List<T> list(Integer limit, Integer start) throws DataAccessException;
 143
 144     /**
 145      * Returns a sublist of CdmBase instances stored in the database. A maximum
 146      * of 'limit' objects are returned, starting at object with index 'start'.
 147      *
 148      * @param limit
 149      *            the maximum number of entities returned (can be null to return
 150      *            all entities)
 151      * @param start
 152      * @param orderHints
 153      *            Supports path like <code>orderHints.propertyNames</code> which
 154      *            include *-to-one properties like createdBy.username or
 155      *            authorTeam.persistentTitleCache
 156      * @return
 157      * @throws DataAccessException
 158      */
 159     public List<T> list(Integer limit, Integer start, List<OrderHint> orderHints);
 160
 161
 162     /**
 163      * Returns a sublist of CdmBase instances stored in the database. A maximum
 164      * of 'limit' objects are returned, starting at object with index 'start'.
 165      *
 166      * @param type
 167      * @param limit
 168      *            the maximum number of entities returned (can be null to return
 169      *            all entities)
 170      * @param start
 171      * @param orderHints
 172      *            Supports path like <code>orderHints.propertyNames</code> which
 173      *            include *-to-one properties like createdBy.username or
 174      *            authorTeam.persistentTitleCache
 175      * @return
 176      * @throws DataAccessException
 177      */
 178     public <S extends T> List<S> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 179
 180     /**
 181      * Returns a sublist of CdmBase instances stored in the database. A maximum
 182      * of 'limit' objects are returned, starting at object with index 'start'.
 183      * The bean properties specified by the parameter <code>propertyPaths</code>
 184      * and recursively initialized for each of the entities in the resultset
 185      *
 186      * For detailed description and examples regarding
 187      * <code>propertyPaths</code> <b>please refer to:</b>
 188      * {@link IBeanInitializer#initialize(Object, List)}
 189      *
 190      * @param limit
 191      *            the maximum number of entities returned (can be null to return
 192      *            all entities)
 193      * @param start
 194      * @param orderHints
 195      *            Supports path like <code>orderHints.propertyNames</code> which
 196      *            include *-to-one properties like createdBy.username or
 197      *            authorTeam.persistentTitleCache
 198      * @param propertyPaths
 199      * @return
 200      * @throws DataAccessException
 201      */
 202     public List<T> list(Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 203
 204     /**
 205      * Returns a list of Cdm entities stored in the database filtered by the restrictions defined by
 206      * the <code>parameters</code> <code>propertyName</code>, value and <code>matchMode</code>
 207      * A maximum
 208      * of 'limit' objects are returned, starting at object with index 'start'.
 209      * The bean properties specified by the parameter <code>propertyPaths</code>
 210      * and recursively initialized for each of the entities in the resultset
 211      *
 212      * For detailed description and examples regarding
 213      * <code>propertyPaths</code> <b>please refer to:</b>
 214      * {@link IBeanInitializer#initialize(Object, List)}
 215      *
 216      * @param type
 217      *          Restrict the query to objects of a certain class, or null for
 218      *          all objects of type T or subclasses
 219      * @param restrictions
 220      *      This defines a filter for multiple properties represented by the map keys. Sine the keys are of the type
 221      *      {@link Restriction} for each property a single MatchMode is defined. Multiple alternative values
 222      *      can be supplied per property, that is the values per property are combined with OR. The per property
 223      *      restrictions are combined with AND. </br>
 224      *      <b>NOTE:</b> For non string type properties you must use
 225      *      {@link MatchMode#EXACT}. If set <code>null</code> {@link MatchMode#EXACT} will be used
 226      *      as default.
 227      * @param limit
 228      *         the maximum number of entities returned (can be null to return
 229      *         all entities)
 230      * @param start
 231      *       The list of criterion objects representing the restriction to be applied.
 232      * @param orderHints
 233      *            Supports path like <code>orderHints.propertyNames</code> which
 234      *            include *-to-one properties like createdBy.username or
 235      *            authorTeam.persistentTitleCache
 236      * @param propertyPaths
 237      * @return
 238      * @throws DataAccessException
 239      */
 240     public <S extends T> List<S> list(Class<S> type, List<Restriction<?>> restrictions, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 241
 242     /**
 243      * Counts the Cdm entities matching the restrictions defined by
 244      * the <code>parameters</code> <code>propertyName</code>, value and <code>matchMode</code>.
 245      *
 246      * @param type
 247      *          Restrict the query to objects of a certain class, or null for
 248      *          all objects of type T or subclasses
 249      * @param restrictions
 250      *      This defines a filter for multiple properties represented by the map keys. Sine the keys are of the type
 251      *      {@link Restriction} for each property a single MatchMode is defined. Multiple alternative values
 252      *      can be supplied per property, that is the values per property are combined with OR. The per property
 253      *      restrictions are combined with AND. </br>
 254      *      <b>NOTE:</b> For non string type properties you must use
 255      *      {@link MatchMode#EXACT}. If set <code>null</code> {@link MatchMode#EXACT} will be used
 256      *      as default.
 257      * @param criteria
 258      *       The list of criterion objects representing the restriction to be applied.
 259      *
 260      * @return
 261      */
 262     public long count(Class<? extends T> type, List<Restriction<?>> restrictions);
 263
 264     /**
 265      * Returns a sublist of CdmBase instances of type <TYPE> stored in the database.
 266      * A maximum of 'limit' objects are returned, starting at object with index 'start'.
 267      * @param limit the maximum number of entities returned (can be null to return all entities)
 268      * @param start
 269      * @return
 270      * @throws DataAccessException
 271      */
 272     public <S extends T> List<S> list(Class<S> type, Integer limit, Integer start) throws DataAccessException;
 273
 274     /**
 275      * Returns a sublist of objects matching the grouping projections supplied using the groups parameter
 276      *
 277      * It would be nice to have an equivalent countGroups method, but for the moment hibernate doesn't
 278      * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)
 279      *
 280      * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses
 281      * @param limit the maximum number of entities returned (can be null to return
 282      *            all entities)
 283      * @param start The (0-based) offset from the start of the recordset
 284      * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property
 285      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 286      * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.
 287      */
 288     public List<Object[]> group(Class<? extends T> clazz,Integer limit, Integer start, List<Grouping> groups, List<String> propertyPaths);
 289
 290     /**
 291      * @param id
 292      * @return
 293      * @throws DataAccessException
 294      */
 295     public T findById(int id) throws DataAccessException;
 296
 297     /**
 298      * Finds the cdm entity specified by the id parameter and
 299      * recursively initializes all bean properties given in the
 300      * <code>propertyPaths</code> parameter.
 301      * <p>
 302      * For detailed description and examples <b>please refer to:</b>
 303      * {@link IBeanInitializer#initialize(Object, List)}
 304      *
 305      * @param id
 306      * @param propertyPaths properties to be initialized
 307      * @return
 308      */
 309     public T load(int id, List<String> propertyPaths);
 310
 311     /**
 312      * Returns the object for the given id without initializing it. So the returned
 313      * object usually is a proxy object except for the case when it was already initialized
 314      * before in the same session.<BR>
 315      * This methods wraps {@link Session#load(Class, java.io.Serializable)}.<BR>
 316      * It does not check, if the object really exists but throws an {@link ObjectNotFoundException}
 317      * exception when no record with the given id exists in the database.
 318      * @return
 319      *         the (uninitialized proxy) object
 320      */
 321     public T loadWithoutInitializing(int id);
 322
 323     public List<T> loadList(Collection<Integer> ids, List<OrderHint> orderHints, List<String> propertyPaths) throws DataAccessException;
 324
 325     public T findByUuid(UUID Uuid) throws DataAccessException;
 326
 327     /**
 328      * Method to find CDM Entity by Uuid, by making sure that the underlying
 329      * hibernate session is not flushed (Session.FLUSH_MODE set to MANUAL temporarily)
 330      * when performing the read query.
 331      *
 332      * @param Uuid
 333      * @return
 334      * @throws DataAccessException
 335      */
 336     public T findByUuidWithoutFlush(UUID uuid) throws DataAccessException;
 337
 338     public List<T> list(Collection<UUID> uuids, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws DataAccessException;
 339
 340     public <S extends T> List<S> list(Class<S> clazz, Collection<UUID> uuids, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws DataAccessException;
 341
 342     /**
 343      * Finds the cdm entity specified by the <code>uuid</code> parameter and
 344      * initializes all its *ToOne relations.
 345      */
 346     public T load(UUID uuid);
 347
 348     /**
 349      * Finds the cdm entity specified by the <code>uuid</code> parameter and
 350      * recursively initializes all bean properties given in the
 351      * <code>propertyPaths</code> parameter.
 352      * <p>
 353      * For detailed description and examples <b>please refer to:</b>
 354      * {@link IBeanInitializer#initialize(Object, List)}
 355      *
 356      * @param uuid
 357      * @param propertyPaths properties to be initialized
 358      * @return
 359      */
 360     public T load(UUID uuid, List<String> propertyPaths);
 361
 362     /**
 363      * @param uuid
 364      * @return
 365      * @throws DataAccessException
 366      */
 367     public Boolean exists(UUID uuid) throws DataAccessException;
 368
 369     public long count();
 370
 371     /**
 372      * Returns the number of objects of type <T> - which must extend T
 373      * @param <T>
 374      * @param clazz
 375      * @return
 376      */
 377     public long count(Class<? extends T> clazz);
 378
 379     /**
 380      * FIXME Should this method exist : I would expect flushing of a session to be
 381      * something that a DAO should hide?
 382      */
 383     public void flush();
 384
 385     /**
 386      * Convenience method which makes it easy to discover what type of object this DAO returns at runtime
 387      *
 388      * @return
 389      */
 390     public Class<T> getType();
 391
 392     /**
 393      * Method that counts the number of objects matching the example provided.
 394      * The includeProperties property is used to specify which properties of the example are used.
 395      *
 396      * If includeProperties is null or empty, then all literal properties are used (restrictions are
 397      * applied as in the Hibernate Query-By-Example API call Example.create(object)).
 398      *
 399      * If includeProperties is not empty then only literal properties that are named in the set are used to
 400      * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
 401      * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
 402      * criteria.createCriteria(property).add(Example.create(relatedObject)))
 403      *
 404      * @param example
 405      * @param includeProperties
 406      * @return a count of matching objects
 407      */
 408     public long count(T example, Set<String> includeProperties);
 409
 410     /**
 411      * Method that lists the objects matching the example provided.
 412      * The includeProperties property is used to specify which properties of the example are used.
 413      *
 414      * If includeProperties is null or empty, then all literal properties are used (restrictions are
 415      * applied as in the Hibernate Query-By-Example API call Example.create(object)).
 416      *
 417      * If includeProperties is not empty then only literal properties that are named in the set are used to
 418      * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
 419      * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
 420      * criteria.createCriteria(property).add(Example.create(relatedObject)))
 421      *
 422      * @param example
 423      * @param includeProperties
 424      * @param limit the maximum number of entities returned (can be null to return
 425      *            all entities)
 426      * @param start The (0-based) offset from the start of the recordset
 427      * @param orderHints
 428      *            Supports path like <code>orderHints.propertyNames</code> which
 429      *            include *-to-one properties like createdBy.username or
 430      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 431      * @return a list of matching objects
 432      */
 433     public <S extends T> List<S> list(S example, Set<String> includeProperties, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 434
 435     public  <S extends T> List<S> findByParamWithRestrictions(Class<S> clazz, String param, String queryString, MatchMode matchmode, List<Restriction<?>> restrictions, Integer pageSize,
 436             Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 437
 438     public long countByParamWithRestrictions(Class<? extends T> clazz, String param, String queryString, MatchMode matchmode, List<Restriction<?>> restrictions);
 439
 440     public long countByParam(Class<? extends T> clazz, String param, String queryString, MatchMode matchmode, List<Criterion> criterion);
 441
 442     public <S extends T> List<S> findByParam(Class<S> clazz, String param, String queryString, MatchMode matchmode, List<Criterion> criterion, Integer pageSize, Integer pageNumber,
 443             List<OrderHint> orderHints, List<String> propertyPaths);
 444
 445     public <S extends T> List<S> findByParam(Class<S> clazz, Set<String> params, String queryString, MatchMode matchmode,
 446             List<Criterion> criterion, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints,
 447             List<String> propertyPaths);
 448
 449 }