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