2 * Copyright (C) 2007 EDIT
3 * European Distributed Institute of Taxonomy
4 * http://www.e-taxonomy.eu
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.
10 package eu
.etaxonomy
.cdm
.api
.service
;
13 import java
.util
.Collection
;
14 import java
.util
.List
;
17 import java
.util
.UUID
;
19 import org
.hibernate
.LockOptions
;
20 import org
.hibernate
.Session
;
21 import org
.hibernate
.criterion
.Criterion
;
22 import org
.hibernate
.event
.spi
.MergeEvent
;
24 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
25 import eu
.etaxonomy
.cdm
.model
.common
.CdmBase
;
26 import eu
.etaxonomy
.cdm
.model
.common
.ICdmBase
;
27 import eu
.etaxonomy
.cdm
.persistence
.dao
.common
.Restriction
;
28 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
29 import eu
.etaxonomy
.cdm
.persistence
.dto
.MergeResult
;
30 import eu
.etaxonomy
.cdm
.persistence
.hibernate
.PostMergeEntityListener
;
31 import eu
.etaxonomy
.cdm
.persistence
.query
.Grouping
;
32 import eu
.etaxonomy
.cdm
.persistence
.query
.MatchMode
;
33 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
36 * @author a.kohlbecker
41 public interface IService
<T
extends ICdmBase
>{
43 // FIXME what does this method do?
47 * Obtain the specified lock mode on the given object t
49 * NOTE: with hibernate 4 we changed parameter lockMode to lockOptions. LockOptions can be created from LockMode.
51 public void lock(T t
, LockOptions lockOptions
);
54 * Refreshes a given object t using the specified lockmode
56 * All bean properties given in the <code>propertyPaths</code> parameter are recursively initialized.
58 * For detailed description and examples <b>please refer to:</b>
59 * {@link IBeanInitializer#initialize(Object, List)}
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).
65 * NOTE: with hibernate 4 we changed parameter lockMode to lockOptions. LockOptions can be created from LockMode.
70 public void refresh(T t
, LockOptions lockOptions
, List
<String
> propertyPaths
);
73 * Returns a count of all entities of type <T> optionally restricted
74 * to objects belonging to a class that that extends <T>
76 * @param clazz the class of entities to be counted (can be null to count all entities of type <T>)
77 * @return a count of entities
79 public int count(Class
<?
extends T
> clazz
);
82 * Delete an existing persistent object
84 * @param persistentObject the object to be deleted
85 * @return the unique identifier of the deleted entity
86 * @return deleteResult
88 public DeleteResult
delete(UUID persistentObjectUUID
) ;
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
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
97 public boolean exists(UUID uuid
);
100 * Return a list of persisted entities that match the unique identifier
101 * set supplied as an argument
103 * @param uuidSet the set of unique identifiers of the entities required
104 * @return a list of entities of type <T>
106 public List
<T
> find(Set
<UUID
> uuidSet
);
109 * Return a list of persisted entities that match the unique identifier
110 * set supplied as an argument and that do match the supplied class.
112 * @param uuidSet the set of unique identifiers of the entities required
113 * @return a list of entities of type <T>
115 public <S
extends T
> List
<S
> find(Class
<S
> clazz
, Set
<UUID
> uuidSet
);
118 * Return a persisted entity that matches the unique identifier
119 * supplied as an argument, or null if the entity does not exist
121 * @param uuid the unique identifier of the entity required
122 * @return an entity of type <T>, or null if the entity does not exist or uuid is <code>null</code>
124 public T
find(UUID uuid
);
127 * Return a persisted entity that matches the unique identifier
128 * supplied as an argument, or null if the entity does not exist.
130 * The difference between this method and {@link #find(UUID) find} is
131 * that this method makes the hibernate read query with the
132 * {@link org.hibernate.FlushMode FlushMode} for the session set to 'MANUAL'
134 * <b>WARNING:</b>This method should <em>ONLY</em> be used when it is absolutely
135 * necessary and safe to ensure that the hibernate session is not flushed before a read
136 * query. A use case for this is the {@link eu.etaxonomy.cdm.api.cache.CdmPermanentCacheBase CdmCacher},
137 * (ticket #4276) where a call to {@link eu.etaxonomy.cdm.api.cache.CdmPermanentCacheBase#load(UUID) load}
138 * the CDM Entity using the standard {@link #find(UUID) find} method results in recursion
139 * due to the fact that the {@link #find(UUID) find} method triggers a hibernate session
140 * flush which eventually could call {@link eu.etaxonomy.cdm.model.name.NonViralName#getNameCache getNameCache},
141 * which in turn (in the event that name cache is null) eventually calls the
142 * {@link eu.etaxonomy.cdm.api.cache.CdmPermanentCacheBase#load(UUID uuid) load} again.
143 * Apart from these kind of exceptional circumstances, the standard {@link #find(UUID) find}
144 * method should always be used to ensure that the persistence layer is always in sync with the
145 * underlying database.
148 * @return an entity of type <T>, or null if the entity does not exist or uuid is <code>null</code>
150 public T
findWithoutFlush(UUID uuid
);
153 * Return a persisted entity that matches the database identifier
154 * supplied as an argument, or null if the entity does not exist
156 * @param id the database identifier of the entity required
157 * @return an entity of type <T>, or null if the entity does not exist
159 public T
find(int id
);
162 * Returns a <code>List</code> of persisted entities that match the database identifiers.
163 * Returns an empty list if no identifier matches.
167 * @deprecated use {@link #loadByIds(Set, List)} instead
170 public List
<T
> findById(Set
<Integer
> idSet
); //can't be called find(Set<Integer>) as this conflicts with find(Set<UUID)
173 // FIXME should we expose this method?
174 public Session
getSession();
177 * Returns a sublist of objects matching the grouping projections supplied using the groups parameter
179 * It would be nice to be able to return a pager, but for the moment hibernate doesn't
180 * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)
182 * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses
183 * @param limit the maximum number of entities returned (can be null to return
185 * @param start The (0-based) offset from the start of the recordset (can be null, equivalent of starting at the beginning of the recordset)
186 * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property
187 * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
188 * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.
190 public List
<Object
[]> group(Class
<?
extends T
> clazz
,Integer limit
, Integer start
, List
<Grouping
> groups
, List
<String
> propertyPaths
);
193 * Returns a list of entities of type <T> optionally restricted
194 * to objects belonging to a class that extends <T>
196 * @param type The type of entities to return (can be null to count all entities of type <T>)
197 * @param limit The maximum number of objects returned (can be null for all matching objects)
198 * @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)
200 * Supports path like <code>orderHints.propertyNames</code> which
201 * include *-to-one properties like createdBy.username or
202 * authorTeam.persistentTitleCache
203 * @param propertyPaths properties to be initialized
206 //TODO refactor to public <S extends T> List<T> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
207 public <S
extends T
> List
<S
> list(Class
<S
> type
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
210 * Finds the cdm entity specified by the <code>uuid</code> parameter and
211 * initializes all its *ToOne relations.
214 * @return the cdm entity or <code>null</code> if not object with given uuid exists or uuid is <code>null</code>
216 public T
load(UUID uuid
);
219 * Return a persisted entity that matches the database identifier
220 * supplied as an argument, or null if the entity does not exist
222 * @param id the database identifier of the entity required
223 * @param propertyPaths
226 public T
load(int id
, List
<String
> propertyPaths
);
229 * Returns the object for the given id without initializing it. So the returned
230 * object usually is a proxy object except for the case when it was already initialized
231 * before in the same session.<BR>
232 * This methods wraps {@link Session#load(Class, java.io.Serializable)}.<BR>
233 * It does not check, if the object really exists but throws an
234 * exception when no record with the given id exists in the database.
237 * the (uninitialized proxy) object
239 public T
loadWithoutInitializing(int id
);
242 * Finds the cdm entity specified by the <code>uuid</code> parameter and
243 * recursively initializes all bean properties given in the
244 * <code>propertyPaths</code> parameter.
246 * For detailed description and examples <b>please refer to:</b>
247 * {@link IBeanInitializer#initialize(Object, List)}
250 * @return the cdm entity or <code>null</code> if not object with given uuid exists or uuid is <code>null</code>
252 public T
load(UUID uuid
, List
<String
> propertyPaths
);
256 * Finds the cdm entities specified by the <code>uuids</code>,
257 * recursively initializes all bean properties given in the
258 * <code>propertyPaths</code> parameter and returns the initialised
261 * For detailed description and examples <b>please refer to:</b>
262 * {@link IBeanInitializer#initialize(Object, List)}
264 * @param propertyPaths
267 public List
<T
> load(List
<UUID
> uuids
, List
<String
> propertyPaths
);
270 * Copy the state of the given object onto the persistent object with the same identifier.
272 * @param detachedObject the detached entity to be merged
273 * @return the persisted entity
275 public T
merge(T detachedObject
);
277 public T
merge(T detachedObject
, CdmBase
... removedObjects
);
280 * Returns a paged list of entities of type <T> optionally restricted
281 * to objects belonging to a class that that extends <T>
283 * @param type The type of entities to return (can be null to count all entities of type <T>)
284 * @param pageSize The maximum number of objects returned (can be null for all matching objects)
285 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based,
286 * can be null, equivalent of starting at the beginning of the recordset)
288 * Supports path like <code>orderHints.propertyNames</code> which
289 * include *-to-one properties like createdBy.username or
290 * authorTeam.persistentTitleCache
291 * @param propertyPaths properties to be initialized
292 * @return a pager of objects of type <T>
294 public <S
extends T
> Pager
<S
> page(Class
<S
> type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
297 * Re-read the state of the given instance from the underlying database.
299 * Hibernate claims that it is inadvisable to use refresh in long-running-sessions.
300 * I don't really see where we would get into a situation where problems as discussed
301 * this forum thread would apply for our scenario
303 * http://forum.hibernate.org/viewtopic.php?t=974544
305 * @param persistentObject the object to be refreshed
306 * @return the unique identifier
308 public UUID
refresh(T persistentObject
);
311 * Save a collection containing new entities (persists the entities)
312 * @param newInstances the new entities to be persisted
313 * @return A Map containing the new entities, keyed using the generated UUID's
316 public Map
<UUID
,T
> save(Collection
<?
extends T
> newInstances
);
319 * Save a new entity (persists the entity)
320 * @param newInstance the new entity to be persisted
321 * @return The new persistent entity
323 public <S
extends T
> S
save(S newInstance
);
326 * Save a new entity or update the persistent state of an existing
327 * transient entity that has been persisted previously
329 * @param transientObject the entity to be persisted
330 * @return The unique identifier of the persisted entity
332 public UUID
saveOrUpdate(T transientObject
);
335 * Save new entities or update the persistent state of existing
336 * transient entities that have been persisted previously
338 * @param transientObjects the entities to be persisted
339 * @return The unique identifier of the persisted entity
341 public Map
<UUID
,T
> saveOrUpdate(Collection
<T
> transientObjects
);
344 * Update the persistent state of an existing transient entity
345 * that has been persisted previously
347 * @param transientObject the entity to be persisted
348 * @return The unique identifier of the persisted entity
350 public UUID
update(T transientObject
);
353 * Simply calls the load method.
354 * Required specifically for the editor to allow load calls which
355 * can also update the session cache.
360 public T
loadWithUpdate(UUID uuid
);
363 * Method that lists the objects matching the example provided.
364 * The includeProperties property is used to specify which properties of the example are used.
366 * If includeProperties is null or empty, then all literal properties are used (restrictions are
367 * applied as in the Hibernate Query-By-Example API call Example.create(object)).
369 * If includeProperties is not empty then only literal properties that are named in the set are used to
370 * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
371 * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
372 * criteria.createCriteria(property).add(Example.create(relatedObject)))
375 * @param includeProperties
376 * @param limit the maximum number of entities returned (can be null to return
378 * @param start The (0-based) offset from the start of the recordset
380 * Supports path like <code>orderHints.propertyNames</code> which
381 * include *-to-one properties like createdBy.username or
382 * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
383 * @return a list of matching objects
385 public <S
extends T
> List
<S
> list(S example
, Set
<String
> includeProperties
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
387 public DeleteResult
delete(T persistentObject
);
390 * Deletes a collection of persistent objects correponding to the
391 * given list of uuids. The result will have status as ok if even one
392 * of the deletes is successful, else error.
394 * @param persistentObjectUUIDs uuids of persistent objects to delete
395 * @return DeleteResult object
397 public DeleteResult
delete(Collection
<UUID
> persistentObjectUUIDs
);
400 * Merges a list of detached objects and returns the new
401 * list of merged objects
403 * @param detachedObjects
404 * @return a list of merged objects
406 public List
<T
> merge(List
<T
> detachedObjects
);
409 * Loads a batch of entities referenced by their ids.
412 * @param propertyPaths
415 List
<T
> loadByIds(List
<Integer
> idSet
, List
<String
> propertyPaths
);
418 * Loads a batch of entities referenced by their ids.
421 * @param propertyPaths
424 List
<T
> loadByIds(List
<Integer
> idSet
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
428 * This method allows for the possibility of returning the input transient
429 * entities instead of the merged persistent entity
431 * WARNING : This method should never be used when the objective of the merge
432 * is to attach to an existing session which is the standard use case.
433 * This method should only be used in the
434 * case of an external call which does not use hibernate sessions and is
435 * only interested in the entity as a POJO. Apart from the session information
436 * the only other difference between the transient and persisted object is in the case
437 * of new objects (id=0) where hibernate sets the id after commit. This id is copied
438 * over to the transient entity in {@link PostMergeEntityListener#onMerge(MergeEvent,Map)}
439 * making the two objects identical and allowing the transient object to be used further
442 * @param detachedObjects
443 * @param returnTransientEntity
446 public List
<MergeResult
<T
>> merge(List
<T
> detachedObjects
, boolean returnTransientEntity
);
449 * This method allows for the possibility of returning the input transient
450 * entity instead of the merged persistent entity
452 * WARNING : This method should never be used when the objective of the merge
453 * is to attach to an existing session which is the standard use case.
454 * This method should only be used in the case of an external call which does
455 * not use hibernate sessions and is only interested in the entity as a POJO.
456 * This method returns the root merged transient entity as well as all newly merged
457 * persistent entities within the return object.
460 * @param returnTransientEntity
463 public MergeResult
<T
> merge(T newInstance
, boolean returnTransientEntity
);
465 public <S
extends T
> Pager
<S
> page(Class
<S
> clazz
, String param
, String queryString
, MatchMode matchmode
, List
<Criterion
> criteria
, Integer pageSize
, Integer pageIndex
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
467 public <S
extends T
> Pager
<S
> pageByParamWithRestrictions(Class
<S
> clazz
, String param
, String queryString
, MatchMode matchmode
, List
<Restriction
<?
>> restrictions
, Integer pageSize
, Integer pageIndex
, List
<OrderHint
> orderHints
,
468 List
<String
> propertyPaths
);
470 public <S
extends T
> Pager
<S
> page(Class
<S
> clazz
, List
<Restriction
<?
>> restrictions
, Integer pageSize
, Integer pageIndex
,
471 List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);