3 * Copyright (C) 2007 EDIT
4 * European Distributed Institute of Taxonomy
5 * http://www.e-taxonomy.eu
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.
11 package eu
.etaxonomy
.cdm
.api
.service
;
14 import java
.util
.Collection
;
15 import java
.util
.List
;
18 import java
.util
.UUID
;
20 import org
.hibernate
.Session
;
22 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
23 import eu
.etaxonomy
.cdm
.model
.common
.CdmBase
;
24 import eu
.etaxonomy
.cdm
.persistence
.dao
.BeanInitializer
;
25 import eu
.etaxonomy
.cdm
.persistence
.query
.Grouping
;
26 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
34 * @author a.kohlbecker
39 public interface IService
<T
extends CdmBase
>{
41 // FIXME what does this method do?
46 * Returns a count of all entities of type <T> optionally restricted
47 * to objects belonging to a class that that extends <T>
49 * @param clazz the class of entities to be counted (can be null to count all entities of type <T>)
50 * @return a count of entities
52 public int count(Class
<?
extends T
> clazz
);
55 * Delete an existing persistent object
57 * @param persistentObject the object to be deleted
58 * @return the unique identifier of the deleted entity
60 public UUID
delete(T persistentObject
);
63 * Returns true if an entity of type <T> with a unique identifier matching the
64 * identifier supplied exists in the database, or false if no such entity can be
66 * @param uuid the unique identifier of the entity required
67 * @return an entity of type <T> matching the uuid, or null if that entity does not exist
69 public boolean exists(UUID uuid
);
72 * Return a list of persisted entities that match the unique identifier
73 * set supplied as an argument
75 * @param uuidSet the set of unique identifiers of the entities required
76 * @return a list of entities of type <T>
78 public List
<T
> find(Set
<UUID
> uuidSet
);
81 * Return a persisted entity that matches the unique identifier
82 * supplied as an argument, or null if the entity does not exist
84 * @param uuid the unique identifier of the entity required
85 * @return an entity of type <T>, or null if the entity does not exist
87 public T
find(UUID uuid
);
89 // FIXME should we expose this method?
90 public Session
getSession();
93 * Returns a sublist of objects matching the grouping projections supplied using the groups parameter
95 * It would be nice to be able to return a pager, but for the moment hibernate doesn't
96 * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)
98 * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses
99 * @param limit the maximum number of entities returned (can be null to return
101 * @param start The (0-based) offset from the start of the recordset (can be null, equivalent of starting at the beginning of the recordset)
102 * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property
103 * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
104 * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.
106 public List
<Object
[]> group(Class
<?
extends T
> clazz
,Integer limit
, Integer start
, List
<Grouping
> groups
, List
<String
> propertyPaths
);
109 * Returns a list of entities of type <T> optionally restricted
110 * to objects belonging to a class that that extends <T>
112 * @param type The type of entities to return (can be null to count all entities of type <T>)
113 * @param limit The maximum number of objects returned (can be null for all matching objects)
114 * @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)
116 * Supports path like <code>orderHints.propertyNames</code> which
117 * include *-to-one properties like createdBy.username or
118 * authorTeam.persistentTitleCache
119 * @param propertyPaths properties to be initialized
122 public List
<T
> list(Class
<?
extends T
> type
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
125 * Finds the cdm entity specified by the <code>uuid</code> parameter and
126 * initializes all its *ToOne relations.
131 public T
load(UUID uuid
);
134 * Finds the cdm entity specified by the <code>uuid</code> parameter and
135 * recursively initializes all bean properties given in the
136 * <code>propertyPaths</code> parameter.
138 * For detailed description and examples <b>please refer to:</b>
139 * {@link BeanInitializer#initialize(Object, List)}
144 public T
load(UUID uuid
, List
<String
> propertyPaths
);
147 * Copy the state of the given object onto the persistent object with the same identifier.
149 * @param transientObject the entity to be merged
150 * @return The unique identifier of the persisted entity
152 public UUID
merge(T transientObject
);
155 * Returns a paged list of entities of type <T> optionally restricted
156 * to objects belonging to a class that that extends <T>
158 * @param type The type of entities to return (can be null to count all entities of type <T>)
159 * @param pageSize The maximum number of objects returned (can be null for all matching objects)
160 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based,
161 * can be null, equivalent of starting at the beginning of the recordset)
163 * Supports path like <code>orderHints.propertyNames</code> which
164 * include *-to-one properties like createdBy.username or
165 * authorTeam.persistentTitleCache
166 * @param propertyPaths properties to be initialized
167 * @return a pager of objects of type <T>
169 public Pager
<T
> page(Class
<?
extends T
> type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
172 * Re-read the state of the given instance from the underlying database.
174 * Hibernate claims that it is inadvisable to use refresh in long-running-sessions.
175 * I don't really see where we would get into a situation where problems as discussed
176 * this forum thread would apply for our scenario
178 * http://forum.hibernate.org/viewtopic.php?t=974544
180 * @param persistentObject the object to be refreshed
181 * @return the unique identifier
183 public UUID
refresh(T persistentObject
);
185 public List
<T
> rows(String tableName
, int limit
, int start
);
188 * Save a collection containing new entities (persists the entities)
189 * @param newInstances the new entities to be persisted
190 * @return A Map containing the new entities, keyed using the generated UUID's
193 public Map
<UUID
,T
> save(Collection
<T
> newInstances
);
196 * Save a new entity (persists the entity)
197 * @param newInstance the new entity to be persisted
198 * @return A generated UUID for the new persistent entity
200 public UUID
save(T newInstance
);
203 * Save a new entity or update the persistent state of an existing
204 * transient entity that has been persisted previously
206 * @param transientObject the entity to be persisted
207 * @return The unique identifier of the persisted entity
209 public UUID
saveOrUpdate(T transientObject
);
212 * Update the persistent state of an existing transient entity
213 * that has been persisted previously
215 * @param transientObject the entity to be persisted
216 * @return The unique identifier of the persisted entity
218 public UUID
update(T transientObject
);
221 * Method that lists the objects matching the example provided.
222 * The includeProperties property is used to specify which properties of the example are used.
224 * If includeProperties is null or empty, then all literal properties are used (restrictions are
225 * applied as in the Hibernate Query-By-Example API call Example.create(object)).
227 * If includeProperties is not empty then only literal properties that are named in the set are used to
228 * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
229 * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
230 * criteria.createCriteria(property).add(Example.create(relatedObject)))
233 * @param includeProperties
234 * @param limit the maximum number of entities returned (can be null to return
236 * @param start The (0-based) offset from the start of the recordset
238 * Supports path like <code>orderHints.propertyNames</code> which
239 * include *-to-one properties like createdBy.username or
240 * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
241 * @return a list of matching objects
243 public List
<T
> list(T example
, Set
<String
> includeProperties
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);