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.LockMode;
  21 import org.hibernate.Session;
  22
  23 import eu.etaxonomy.cdm.api.service.config.DeleteConfiguratorBase;
  24 import eu.etaxonomy.cdm.api.service.exception.ReferencedObjectUndeletableException;
  25 import eu.etaxonomy.cdm.api.service.pager.Pager;
  26 import eu.etaxonomy.cdm.model.common.CdmBase;
  27 import eu.etaxonomy.cdm.model.common.ICdmBase;
  28 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  29 import eu.etaxonomy.cdm.persistence.query.Grouping;
  30 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  31
  32
  33 /**
  34  * @author a.mueller
  35  *
  36  */
  37 /**
  38  * @author a.kohlbecker
  39  * @date 23.03.2009
  40  *
  41  * @param <T>
  42  */
  43 public interface IService<T extends ICdmBase>{
  44
  45     // FIXME what does this method do?
  46     public void clear();
  47
  48     /**
  49      * Obtain the specified lock mode on the given object t
  50      */
  51     public void lock(T t, LockMode lockMode);
  52
  53     /**
  54      * Refreshes a given object t using the specified lockmode
  55      *
  56      * All bean properties given in the <code>propertyPaths</code> parameter are recursively initialized.
  57      * <p>
  58      * For detailed description and examples <b>please refer to:</b>
  59      * {@link IBeanInitializer#initialize(Object, List)}
  60      *
  61      * NOTE: in the case of lockmodes that hit the database (e.g. LockMode.READ), you will need to re-initialize
  62      * child propertiesto avoid a HibernateLazyInitializationException (even if the properties of the child
  63      * were initialized prior to the refresh).
  64      *
  65      * @param t
  66      * @param lockMode
  67      */
  68     public void refresh(T t, LockMode lockMode, 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      *
  85      */
  86     public String delete(T persistentObject) ;
  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
 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>NOTE:</b>This method should <em>ONLY</em> be used when it is absolutely
 128      * necessary 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 cahce is null) eventually calls the
 135          * {@link eu.etaxonomy.cdm.api.cache.CdmCacher#load(UUID uuid)} again.
 136          * Apart from these kind of exceptional circumstances, the standard {@link #find(UUID) find}
 137          * method should be used to ensure that the persistence layer is always in sync with the
 138          * underlying dtabase.
 139          *
 140          * @param uuid
 141          * @return an entity of type <T>, or null if the entity does not exist
 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      */
 161     public List<T> findById(Set<Integer> idSet);  //can't be called find(Set<Integer>) as this conflicts with find(Set<UUID)
 162
 163
 164     // FIXME should we expose this method?
 165     public Session getSession();
 166
 167     /**
 168      * Returns a sublist of objects matching the grouping projections supplied using the groups parameter
 169      *
 170      * It would be nice to be able to return a pager, but for the moment hibernate doesn't
 171      * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)
 172      *
 173      * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses
 174      * @param limit the maximum number of entities returned (can be null to return
 175      *            all entities)
 176      * @param start The (0-based) offset from the start of the recordset (can be null, equivalent of starting at the beginning of the recordset)
 177      * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property
 178      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 179      * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.
 180      */
 181     public List<Object[]> group(Class<? extends T> clazz,Integer limit, Integer start, List<Grouping> groups, List<String> propertyPaths);
 182
 183     /**
 184      * Returns a list of entities of type <T> optionally restricted
 185      * to objects belonging to a class that that extends <T>
 186      *
 187      * @param type  The type of entities to return (can be null to count all entities of type <T>)
 188      * @param limit The maximum number of objects returned (can be null for all matching objects)
 189      * @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)
 190      * @param orderHints
 191      *            Supports path like <code>orderHints.propertyNames</code> which
 192      *            include *-to-one properties like createdBy.username or
 193      *            authorTeam.persistentTitleCache
 194      * @param propertyPaths properties to be initialized
 195      * @return
 196      */
 197     //TODO refactor to public <S extends T> List<T> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 198     public <S extends T>  List<S> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 199
 200     /**
 201      * Finds the cdm entity specified by the <code>uuid</code> parameter and
 202      * initializes all its *ToOne relations.
 203      *
 204      * @param uuid
 205      * @return
 206      */
 207     public T load(UUID uuid);
 208
 209     /**
 210      * Finds the cdm entity specified by the <code>uuid</code> parameter and
 211      * recursively initializes all bean properties given in the
 212      * <code>propertyPaths</code> parameter.
 213      * <p>
 214      * For detailed description and examples <b>please refer to:</b>
 215      * {@link IBeanInitializer#initialize(Object, List)}
 216      *
 217      * @param uuid
 218      * @return
 219      */
 220     public T load(UUID uuid, List<String> propertyPaths);
 221
 222     /**
 223      * Copy the state of the given object onto the persistent object with the same identifier.
 224      *
 225      * @param transientObject the entity to be merged
 226      * @return The unique identifier of the persisted entity
 227      */
 228     public T merge(T transientObject);
 229
 230     /**
 231      * Returns a paged list of entities of type <T> optionally restricted
 232      * to objects belonging to a class that that extends <T>
 233      *
 234      * @param type  The type of entities to return (can be null to count all entities of type <T>)
 235      * @param pageSize The maximum number of objects returned (can be null for all matching objects)
 236      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based,
 237      *                   can be null, equivalent of starting at the beginning of the recordset)
 238      * @param orderHints
 239      *            Supports path like <code>orderHints.propertyNames</code> which
 240      *            include *-to-one properties like createdBy.username or
 241      *            authorTeam.persistentTitleCache
 242      * @param propertyPaths properties to be initialized
 243      * @return a pager of objects of type <T>
 244      */
 245     public <S extends T> Pager<S> page(Class<S> type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 246
 247     /**
 248      * Re-read the state of the given instance from the underlying database.
 249      *
 250      * Hibernate claims that it is inadvisable to use refresh in long-running-sessions.
 251      * I don't really see where we would get into a situation where problems as discussed
 252      * this forum thread would apply for our scenario
 253      *
 254      * http://forum.hibernate.org/viewtopic.php?t=974544
 255      *
 256      * @param persistentObject the object to be refreshed
 257      * @return the unique identifier
 258      */
 259     public UUID refresh(T persistentObject);
 260
 261     public List<T> rows(String tableName, int limit, int start);
 262
 263     /**
 264      * Save a collection containing new entities (persists the entities)
 265      * @param newInstances the new entities to be persisted
 266      * @return A Map containing the new entities, keyed using the generated UUID's
 267      *         of those entities
 268      */
 269     public Map<UUID,T> save(Collection<T> newInstances);
 270
 271     /**
 272      * Save a new entity (persists the entity)
 273      * @param newInstance the new entity to be persisted
 274      * @return A generated UUID for the new persistent entity
 275      */
 276     public UUID save(T newInstance);
 277
 278     /**
 279      * Save a new entity or update the persistent state of an existing
 280      * transient entity that has been persisted previously
 281      *
 282      * @param transientObject the entity to be persisted
 283      * @return The unique identifier of the persisted entity
 284      */
 285     public UUID saveOrUpdate(T transientObject);
 286
 287     /**
 288      * Save new entities or update the persistent state of existing
 289      * transient entities that have been persisted previously
 290      *
 291      * @param transientObjects the entities to be persisted
 292      * @return The unique identifier of the persisted entity
 293      */
 294     public Map<UUID,T> saveOrUpdate(Collection<T> transientObjects);
 295
 296     /**
 297      * Update the persistent state of an existing transient entity
 298      * that has been persisted previously
 299      *
 300      * @param transientObject the entity to be persisted
 301      * @return The unique identifier of the persisted entity
 302      */
 303     public UUID update(T transientObject);
 304
 305     /**
 306      * Method that lists the objects matching the example provided.
 307      * The includeProperties property is used to specify which properties of the example are used.
 308      *
 309      * If includeProperties is null or empty, then all literal properties are used (restrictions are
 310      * applied as in the Hibernate Query-By-Example API call Example.create(object)).
 311      *
 312      * If includeProperties is not empty then only literal properties that are named in the set are used to
 313      * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
 314      * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
 315      * criteria.createCriteria(property).add(Example.create(relatedObject)))
 316      *
 317      * @param example
 318      * @param includeProperties
 319      * @param limit the maximum number of entities returned (can be null to return
 320      *            all entities)
 321      * @param start The (0-based) offset from the start of the recordset
 322      * @param orderHints
 323      *            Supports path like <code>orderHints.propertyNames</code> which
 324      *            include *-to-one properties like createdBy.username or
 325      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 326      * @return a list of matching objects
 327      */
 328     public List<T> list(T example, Set<String> includeProperties, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 329
 330
 331 }