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