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