cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IService.java

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10
  11 package eu.etaxonomy.cdm.api.service;
  12
  13
  14 import java.util.Collection;
  15 import java.util.List;
  16 import java.util.Map;
  17 import java.util.Set;
  18 import java.util.UUID;
  19
  20 import org.hibernate.LockOptions;
  21 import org.hibernate.Session;
  22 import org.hibernate.event.spi.MergeEvent;
  23
  24 import eu.etaxonomy.cdm.api.service.pager.Pager;
  25 import eu.etaxonomy.cdm.model.common.ICdmBase;
  26 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  27 import eu.etaxonomy.cdm.persistence.hibernate.PostMergeEntityListener;
  28 import eu.etaxonomy.cdm.persistence.query.Grouping;
  29 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  30
  31
  32 /**
  33  * @author a.mueller
  34  *
  35  */
  36 /**
  37  * @author a.kohlbecker
  38  * @date 23.03.2009
  39  *
  40  * @param <T>
  41  */
  42 public interface IService<T extends ICdmBase>{
  43
  44     // FIXME what does this method do?
  45     public void clear();
  46
  47     /**
  48      * Obtain the specified lock mode on the given object t
  49      * <BR>
  50      * NOTE: with hibernate 4 we changed parameter lockMode to lockOptions. LockOptions can be created from LockMode.
  51      */
  52     public void lock(T t, LockOptions lockOptions);
  53
  54     /**
  55      * Refreshes a given object t using the specified lockmode
  56      *
  57      * All bean properties given in the <code>propertyPaths</code> parameter are recursively initialized.
  58      * <p>
  59      * For detailed description and examples <b>please refer to:</b>
  60      * {@link IBeanInitializer#initialize(Object, List)}
  61      *
  62      * NOTE: in the case of lockmodes that hit the database (e.g. LockMode.READ), you will need to re-initialize
  63      * child propertiesto avoid a HibernateLazyInitializationException (even if the properties of the child
  64      * were initialized prior to the refresh).
  65      *
  66      * NOTE: with hibernate 4 we changed parameter lockMode to lockOptions. LockOptions can be created from LockMode.
  67      *
  68      * @param t
  69      * @param lockOptions
  70      */
  71     public void refresh(T t, LockOptions lockOptions, List<String> propertyPaths);
  72
  73     /**
  74      * Returns a count of all entities of type <T>  optionally restricted
  75      * to objects belonging to a class that that extends <T>
  76      *
  77      * @param clazz the class of entities to be counted (can be null to count all entities of type <T>)
  78      * @return a count of entities
  79      */
  80     public int count(Class<? extends T> clazz);
  81
  82     /**
  83      * Delete an existing persistent object
  84      *
  85      * @param persistentObject the object to be deleted
  86      * @return the unique identifier of the deleted entity
  87      * @return deleteResult
  88      */
  89     public DeleteResult delete(UUID persistentObjectUUID) ;
  90
  91
  92
  93     /**
  94      * Returns true if an entity of type <T> with a unique identifier matching the
  95      * identifier supplied exists in the database, or false if no such entity can be
  96      * found.
  97      * @param uuid the unique identifier of the entity required
  98      * @return an entity of type <T> matching the uuid, or null if that entity does not exist
  99      */
 100     public boolean exists(UUID uuid);
 101
 102     /**
 103      * Return a list of persisted entities that match the unique identifier
 104      * set supplied as an argument
 105      *
 106      * @param uuidSet the set of unique identifiers of the entities required
 107      * @return a list of entities of type <T>
 108      */
 109     public List<T> find(Set<UUID> uuidSet);
 110
 111     /**
 112      * Return a persisted entity that matches the unique identifier
 113      * supplied as an argument, or null if the entity does not exist
 114      *
 115      * @param uuid the unique identifier of the entity required
 116      * @return an entity of type <T>, or null if the entity does not exist or uuid is <code>null</code>
 117      */
 118     public T find(UUID uuid);
 119
 120
 121
 122         /**
 123          * Return a persisted entity that matches the unique identifier
 124      * supplied as an argument, or null if the entity does not exist.
 125      * <p>
 126      * The difference between this method and {@link #find(UUID) find} is
 127      * that this method makes the hibernate read query with the
 128      * {@link org.hibernate.FlushMode FlushMode} for the session set to 'MANUAL'
 129      * <p>
 130      * <b>WARNING:</b>This method should <em>ONLY</em> be used when it is absolutely
 131      * necessary and safe to ensure that the hibernate session is not flushed before a read
 132      * query. A use case for this is the {@link eu.etaxonomy.cdm.api.cache.CdmCacher CdmCacher},
 133      * (ticket #4276) where a call to {@link eu.etaxonomy.cdm.api.cache.CdmCacher#load(UUID) load}
 134      * the CDM Entity using the standard {@link #find(UUID) find} method results in recursion
 135      * due to the fact that the {@link #find(UUID) find} method triggers a hibernate session
 136      * flush which eventually could call {@link eu.etaxonomy.cdm.model.name.NonViralName#getNameCache getNameCache},
 137          * which in turn (in the event that name cache is null) eventually calls the
 138          * {@link eu.etaxonomy.cdm.api.cache.CdmCacher#load(UUID uuid) load} again.
 139          * Apart from these kind of exceptional circumstances, the standard {@link #find(UUID) find}
 140          * method should always be used to ensure that the persistence layer is always in sync with the
 141          * underlying database.
 142          *
 143          * @param uuid
 144          * @return an entity of type <T>, or null if the entity does not exist or uuid is <code>null</code>
 145          */
 146         public T findWithoutFlush(UUID uuid);
 147
 148     /**
 149      * Return a persisted entity that matches the database identifier
 150      * supplied as an argument, or null if the entity does not exist
 151      *
 152      * @param id the database identifier of the entity required
 153      * @return an entity of type <T>, or null if the entity does not exist
 154      */
 155     public T find(int id);
 156
 157     /**
 158      * Returns a <code>List</code> of persisted entities that match the database identifiers.
 159      * Returns an empty list if no identifier matches.
 160      *
 161      * @param idSet
 162      * @return
 163      */
 164     public List<T> findById(Set<Integer> idSet);  //can't be called find(Set<Integer>) as this conflicts with find(Set<UUID)
 165
 166
 167     // FIXME should we expose this method?
 168     public Session getSession();
 169
 170     /**
 171      * Returns a sublist of objects matching the grouping projections supplied using the groups parameter
 172      *
 173      * It would be nice to be able to return a pager, but for the moment hibernate doesn't
 174      * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)
 175      *
 176      * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses
 177      * @param limit the maximum number of entities returned (can be null to return
 178      *            all entities)
 179      * @param start The (0-based) offset from the start of the recordset (can be null, equivalent of starting at the beginning of the recordset)
 180      * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property
 181      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 182      * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.
 183      */
 184     public List<Object[]> group(Class<? extends T> clazz,Integer limit, Integer start, List<Grouping> groups, List<String> propertyPaths);
 185
 186     /**
 187      * Returns a list of entities of type <T> optionally restricted
 188      * to objects belonging to a class that that extends <T>
 189      *
 190      * @param type  The type of entities to return (can be null to count all entities of type <T>)
 191      * @param limit The maximum number of objects returned (can be null for all matching objects)
 192      * @param start The offset from the start of the result set (0 - based, can be null - equivalent of starting at the beginning of the recordset)
 193      * @param orderHints
 194      *            Supports path like <code>orderHints.propertyNames</code> which
 195      *            include *-to-one properties like createdBy.username or
 196      *            authorTeam.persistentTitleCache
 197      * @param propertyPaths properties to be initialized
 198      * @return
 199      */
 200     //TODO refactor to public <S extends T> List<T> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 201     public <S extends T>  List<S> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 202
 203     /**
 204      * Finds the cdm entity specified by the <code>uuid</code> parameter and
 205      * initializes all its *ToOne relations.
 206      *
 207      * @param uuid
 208      * @return the cdm entity or <code>null</code> if not object with given uuid exists or uuid is <code>null</code>
 209      */
 210     public T load(UUID uuid);
 211
 212     /**
 213      * Finds the cdm entity specified by the <code>uuid</code> parameter and
 214      * recursively initializes all bean properties given in the
 215      * <code>propertyPaths</code> parameter.
 216      * <p>
 217      * For detailed description and examples <b>please refer to:</b>
 218      * {@link IBeanInitializer#initialize(Object, List)}
 219      *
 220      * @param uuid
 221      * @return the cdm entity or <code>null</code> if not object with given uuid exists or uuid is <code>null</code>
 222      */
 223     public T load(UUID uuid, List<String> propertyPaths);
 224
 225     /**
 226      * Copy the state of the given object onto the persistent object with the same identifier.
 227      *
 228      * @param transientObject the entity to be merged
 229      * @return The unique identifier of the persisted entity
 230      */
 231     public T merge(T transientObject);
 232
 233     /**
 234      * Returns a paged list of entities of type <T> optionally restricted
 235      * to objects belonging to a class that that extends <T>
 236      *
 237      * @param type  The type of entities to return (can be null to count all entities of type <T>)
 238      * @param pageSize The maximum number of objects returned (can be null for all matching objects)
 239      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based,
 240      *                   can be null, equivalent of starting at the beginning of the recordset)
 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 properties to be initialized
 246      * @return a pager of objects of type <T>
 247      */
 248     public <S extends T> Pager<S> page(Class<S> type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 249
 250     /**
 251      * Re-read the state of the given instance from the underlying database.
 252      *
 253      * Hibernate claims that it is inadvisable to use refresh in long-running-sessions.
 254      * I don't really see where we would get into a situation where problems as discussed
 255      * this forum thread would apply for our scenario
 256      *
 257      * http://forum.hibernate.org/viewtopic.php?t=974544
 258      *
 259      * @param persistentObject the object to be refreshed
 260      * @return the unique identifier
 261      */
 262     public UUID refresh(T persistentObject);
 263
 264     public List<T> rows(String tableName, int limit, int start);
 265
 266     /**
 267      * Save a collection containing new entities (persists the entities)
 268      * @param newInstances the new entities to be persisted
 269      * @return A Map containing the new entities, keyed using the generated UUID's
 270      *         of those entities
 271      */
 272     public Map<UUID,T> save(Collection<T> newInstances);
 273
 274     /**
 275      * Save a new entity (persists the entity)
 276      * @param newInstance the new entity to be persisted
 277      * @return A generated UUID for the new persistent entity
 278      */
 279     public T save(T newInstance);
 280
 281     /**
 282      * Save a new entity or update the persistent state of an existing
 283      * transient entity that has been persisted previously
 284      *
 285      * @param transientObject the entity to be persisted
 286      * @return The unique identifier of the persisted entity
 287      */
 288     public UUID saveOrUpdate(T transientObject);
 289
 290     /**
 291      * Save new entities or update the persistent state of existing
 292      * transient entities that have been persisted previously
 293      *
 294      * @param transientObjects the entities to be persisted
 295      * @return The unique identifier of the persisted entity
 296      */
 297     public Map<UUID,T> saveOrUpdate(Collection<T> transientObjects);
 298
 299     /**
 300      * Update the persistent state of an existing transient entity
 301      * that has been persisted previously
 302      *
 303      * @param transientObject the entity to be persisted
 304      * @return The unique identifier of the persisted entity
 305      */
 306     public UUID update(T transientObject);
 307
 308     /**
 309      * Method that lists the objects matching the example provided.
 310      * The includeProperties property is used to specify which properties of the example are used.
 311      *
 312      * If includeProperties is null or empty, then all literal properties are used (restrictions are
 313      * applied as in the Hibernate Query-By-Example API call Example.create(object)).
 314      *
 315      * If includeProperties is not empty then only literal properties that are named in the set are used to
 316      * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
 317      * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
 318      * criteria.createCriteria(property).add(Example.create(relatedObject)))
 319      *
 320      * @param example
 321      * @param includeProperties
 322      * @param limit the maximum number of entities returned (can be null to return
 323      *            all entities)
 324      * @param start The (0-based) offset from the start of the recordset
 325      * @param orderHints
 326      *            Supports path like <code>orderHints.propertyNames</code> which
 327      *            include *-to-one properties like createdBy.username or
 328      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 329      * @return a list of matching objects
 330      */
 331     public List<T> list(T example, Set<String> includeProperties, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 332
 333         public DeleteResult delete(T persistentObject);
 334
 335     /**
 336      * Deletes a collection of persistent objects correponding to the
 337      * given list of uuids. The result will have status as ok if even one
 338      * of the deletes is successful, else error.
 339      *
 340      * @param persistentObjectUUIDs uuids of persistent objects to delete
 341      * @return DeleteResult object
 342      */
 343     public DeleteResult delete(Collection<UUID> persistentObjectUUIDs);
 344
 345     /**
 346      * Merges a list of detached objects and returns the new
 347      * list of merged objects
 348      *
 349      * @param detachedObjects
 350      * @return a list of merged objects
 351      */
 352     public List<T> merge(List<T> detachedObjects);
 353
 354     /**
 355      * This method allows for the possibility of returning the input transient
 356      * entities instead of the merged persistent entity
 357      *
 358      * WARNING : This method should never be used when the objective of the merge
 359      * is to attach to an existing session which is the standard use case.
 360      * This method should only be used in the
 361      * case of an external call which does not use hibernate sessions and is
 362      * only interested in the entity as a POJO. Apart from the session information
 363      * the only other difference between the transient and persisted object is in the case
 364      * of new objects (id=0) where hibernate sets the id after commit. This id is copied
 365      * over to the transient entity in {@link PostMergeEntityListener#onMerge(MergeEvent,Map)}
 366      * making the two objects identical and allowing the transient object to be used further
 367      * as a POJO
 368      *
 369      * @param detachedObjects
 370      * @param returnTransientEntity
 371      * @return
 372      */
 373     public List<T> merge(List<T> detachedObjects, boolean returnTransientEntity);
 374
 375     /**
 376      * This method allows for the possibility of returning the input transient
 377      * entity instead of the merged persistent entity
 378      *
 379      * WARNING : This method should never be used when the objective of the merge
 380      * is to attach to an existing session which is the standard use case.
 381      * This method should only be used in the
 382      * case of an external call which does not use hibernate sessions and is
 383      * only interested in the entity as a POJO. Apart from the session information
 384      * the only other difference between the transient and persisted object is in the case
 385      * of new objects (id=0) where hibernate sets the id after commit. This id is copied
 386      * over to the transient entity in {@link PostMergeEntityListener#onMerge(MergeEvent,Map)}
 387      * making the two objects identical and allowing the transient object to be used further
 388      * as a POJO
 389      *
 390      * @param newInstance
 391      * @param returnTransientEntity
 392      * @return
 393      */
 394     public T merge(T newInstance, boolean returnTransientEntity);
 395
 396
 397
 398
 399
 400 }