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