Project

General

Profile

Download (15 KB) Statistics
| Branch: | Tag: | Revision:
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.persistence.dao.common;
11

    
12
import java.util.Collection;
13
import java.util.List;
14
import java.util.Map;
15
import java.util.Set;
16
import java.util.UUID;
17

    
18
import org.hibernate.LockOptions;
19
import org.hibernate.Session;
20
import org.springframework.dao.DataAccessException;
21

    
22
import eu.etaxonomy.cdm.model.common.CdmBase;
23
import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
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
 * An data access interface that all data access classes implement
30
 * @author m.doering
31
 * @version 1.0
32
 * @created 02-Nov-2007 19:36:10
33
 */
34
public interface ICdmEntityDao<T extends CdmBase> {
35

    
36
    /**
37
     * @param transientObject
38
     * @return
39
     * @throws DataAccessException
40
     */
41
    public UUID saveOrUpdate(T transientObject) throws DataAccessException;
42

    
43
    /**
44
     * @param newOrManagedObject
45
     * @return
46
     * @throws DataAccessException
47
     */
48
    public T save(T newOrManagedObject) throws DataAccessException;
49

    
50
    public T merge(T transientObject) throws DataAccessException;
51

    
52
    /**
53
     * This method allows for the possibility of returning the input transient
54
     * entity instead of the merged persistent entity
55
     *
56
     * WARNING : This method should never be used when the objective of the merge
57
     * is to attach to an existing session which is the standard use case.
58
     * This method should only be used in the case of an external call which does
59
     * not use hibernate sessions and is only interested in the entity as a POJO.
60
     * This method returns the root merged transient entity as well as all newly merged
61
     * persistent entities within the return object.
62
     *
63
     * @param transientObject
64
     * @param returnTransientEntity
65
     * @return transient or persistent object depending on the value of returnTransientEntity
66
     * @throws DataAccessException
67
     */
68
    public MergeResult<T> merge(T transientObject, boolean returnTransientEntity) throws DataAccessException;
69

    
70
    /**
71
     * Obtains the specified LockMode on the supplied object
72
     *
73
     * @param t
74
     * @param lockOptions
75
     * @throws DataAccessException
76
     */
77
    public void lock(T t, LockOptions lockOptions) throws DataAccessException;
78

    
79
    /**
80
     * Globally replace all references to instance t1 with t2 (including
81
     *
82
     * NOTE: This replaces all non-bidirectional relationships where type T is on the
83
     * "owning" side of the relationship (since the "owned" objects are, in theory,
84
     * sub-components of the entity and this kind of global replace doesn't really make sense
85
     *
86
     * Consequently it is a good idea to either map such owned relationships with cascading
87
     * semantics (i.e. CascadeType.DELETE, @OneToMany(orphanRemoval=true)) allowing them to be saved,
88
     * updated, and deleted along with the owning entity automatically.
89
     *
90
     * @param x the object to replace, must not be null
91
     * @param y the object that will replace. If y is null, then x will be removed from all collections
92
     *          and all properties that refer to x will be replaced with null
93
     * @return T the replaced object
94
     */
95
    public T replace(T x, T y);
96

    
97
    /**
98
     * Refreshes the state of the supplied object using the given LockMode (e.g. use LockMode.READ
99
     * to bypass the second-level cache and session cache and query the database directly)
100
     *
101
     * All bean properties given in the <code>propertyPaths</code> parameter are recursively initialized.
102
     * <p>
103
     * For detailed description and examples <b>please refer to:</b>
104
     * {@link IBeanInitializer#initialize(Object, List)}
105
     *
106
     * @param t
107
     * @param lockMode
108
     * @param propertyPaths
109
     * @throws DataAccessException
110
     */
111
    public void refresh(T t, LockOptions lockOptions, List<String> propertyPaths) throws DataAccessException;
112

    
113
    public void clear() throws DataAccessException;
114

    
115
    public Session getSession() throws DataAccessException;
116

    
117
    public Map<UUID, T> saveAll(Collection<T> cdmObjCollection) throws DataAccessException;
118

    
119
    public Map<UUID, T> saveOrUpdateAll(Collection<T> cdmObjCollection);
120

    
121
    /**
122
     * @param transientObject
123
     * @return
124
     * @throws DataAccessException
125
     */
126
    public UUID update(T transientObject) throws DataAccessException;
127

    
128
    /**
129
     * @param persistentObject
130
     * @return
131
     * @throws DataAccessException
132
     */
133
    public UUID refresh(T persistentObject) throws DataAccessException;
134

    
135
    /**
136
     * @param persistentObject
137
     * @return
138
     * @throws DataAccessException
139
     */
140
    public UUID delete(T persistentObject) throws DataAccessException;
141

    
142
    /**
143
     * Returns a sublist of CdmBase instances stored in the database.
144
     * A maximum of 'limit' objects are returned, starting at object with index 'start'.
145
     * @param limit the maximum number of entities returned (can be null to return all entities)
146
     * @param start
147
     * @return
148
     * @throws DataAccessException
149
     */
150
    public List<T> list(Integer limit, Integer start) throws DataAccessException;
151

    
152
    /**
153
     * Returns a sublist of CdmBase instances stored in the database. A maximum
154
     * of 'limit' objects are returned, starting at object with index 'start'.
155
     *
156
     * @param limit
157
     *            the maximum number of entities returned (can be null to return
158
     *            all entities)
159
     * @param start
160
     * @param orderHints
161
     *            Supports path like <code>orderHints.propertyNames</code> which
162
     *            include *-to-one properties like createdBy.username or
163
     *            authorTeam.persistentTitleCache
164
     * @return
165
     * @throws DataAccessException
166
     */
167
    public List<T> list(Integer limit, Integer start, List<OrderHint> orderHints);
168

    
169

    
170
    /**
171
     * Returns a sublist of CdmBase instances stored in the database. A maximum
172
     * of 'limit' objects are returned, starting at object with index 'start'.
173
     *
174
     * @param type
175
     * @param limit
176
     *            the maximum number of entities returned (can be null to return
177
     *            all entities)
178
     * @param start
179
     * @param orderHints
180
     *            Supports path like <code>orderHints.propertyNames</code> which
181
     *            include *-to-one properties like createdBy.username or
182
     *            authorTeam.persistentTitleCache
183
     * @return
184
     * @throws DataAccessException
185
     */
186
    public <S extends T> List<S> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
187

    
188
    /**
189
     * Returns a sublist of CdmBase instances stored in the database. A maximum
190
     * of 'limit' objects are returned, starting at object with index 'start'.
191
     * The bean properties specified by the parameter <code>propertyPaths</code>
192
     * and recursively initialized for each of the entities in the resultset
193
     *
194
     * For detailed description and examples redarding
195
     * <code>propertyPaths</code> <b>please refer to:</b>
196
     * {@link IBeanInitializer#initialize(Object, List)}
197
     *
198
     * @param limit
199
     *            the maximum number of entities returned (can be null to return
200
     *            all entities)
201
     * @param start
202
     * @param orderHints
203
     *            Supports path like <code>orderHints.propertyNames</code> which
204
     *            include *-to-one properties like createdBy.username or
205
     *            authorTeam.persistentTitleCache
206
     * @param propertyPaths
207
     * @return
208
     * @throws DataAccessException
209
     */
210
    public List<T> list(Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
211

    
212
    /**
213
     * Returns a sublist of CdmBase instances of type <TYPE> stored in the database.
214
     * A maximum of 'limit' objects are returned, starting at object with index 'start'.
215
     * @param limit the maximum number of entities returned (can be null to return all entities)
216
     * @param start
217
     * @return
218
     * @throws DataAccessException
219
     */
220
    public <S extends T> List<S> list(Class<S> type, Integer limit, Integer start) throws DataAccessException;
221

    
222
    /**
223
     * Returns a sublist of objects matching the grouping projections supplied using the groups parameter
224
     *
225
     * It would be nice to have an equivalent countGroups method, but for the moment hibernate doesn't
226
     * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)
227
     *
228
     * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses
229
     * @param limit the maximum number of entities returned (can be null to return
230
     *            all entities)
231
     * @param start The (0-based) offset from the start of the recordset
232
     * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property
233
     * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
234
     * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.
235
     */
236
    public List<Object[]> group(Class<? extends T> clazz,Integer limit, Integer start, List<Grouping> groups, List<String> propertyPaths);
237

    
238
    public List<T> rows(String tableName, int limit, int start) throws DataAccessException;
239

    
240
    /**
241
     * @param id
242
     * @return
243
     * @throws DataAccessException
244
     */
245
    public T findById(int id) throws DataAccessException;
246

    
247
    /**
248
     * Finds the cdm entity specified by the id parameter and
249
     * recursively initializes all bean properties given in the
250
     * <code>propertyPaths</code> parameter.
251
     * <p>
252
     * For detailed description and examples <b>please refer to:</b>
253
     * {@link IBeanInitializer#initialize(Object, List)}
254
     *
255
     * @param id
256
     * @param propertyPaths properties to be initialized
257
     * @return
258
     */
259
    public T load(int id, List<String> propertyPaths);
260

    
261
    /**
262
     * @param ids
263
     * @param propertyPaths
264
     * @return
265
     * @throws DataAccessException
266
     */
267
    public List<T> loadList(Collection<Integer> ids, List<String> propertyPaths) throws DataAccessException;
268

    
269
    /**
270
     * @param Uuid
271
     * @return
272
     * @throws DataAccessException
273
     */
274
    public T findByUuid(UUID Uuid) throws DataAccessException;
275

    
276
    /**
277
     * Method to find CDM Entity by Uuid, by making sure that the underlying
278
     * hibernate session is not flushed (Session.FLUSH_MODE set to MANUAL temporarily)
279
     * when performing the read query.
280
     *
281
     * @param Uuid
282
     * @return
283
     * @throws DataAccessException
284
     */
285
    public T findByUuidWithoutFlush(UUID uuid) throws DataAccessException;
286

    
287

    
288
    /**
289
     * @param uuids
290
     * @param pageSize
291
     * @param pageNumber
292
     * @param orderHints
293
     * @param propertyPaths
294
     * @return
295
     * @throws DataAccessException
296
     */
297
    public List<T> list(Collection<UUID> uuids, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths) throws DataAccessException;
298

    
299
    /**
300
     * Finds the cdm entity specified by the <code>uuid</code> parameter and
301
     * initializes all its *ToOne relations.
302
     *
303
     * @param uuid
304
     * @return
305
     */
306
    public T load(UUID uuid);
307

    
308
    /**
309
     * Finds the cdm entity specified by the <code>uuid</code> parameter and
310
     * recursively initializes all bean properties given in the
311
     * <code>propertyPaths</code> parameter.
312
     * <p>
313
     * For detailed description and examples <b>please refer to:</b>
314
     * {@link IBeanInitializer#initialize(Object, List)}
315
     *
316
     * @param uuid
317
     * @param propertyPaths properties to be initialized
318
     * @return
319
     */
320
    public T load(UUID uuid, List<String> propertyPaths);
321

    
322
    /**
323
     * @param uuid
324
     * @return
325
     * @throws DataAccessException
326
     */
327
    public Boolean exists(UUID uuid) throws DataAccessException;
328

    
329
    public int count();
330

    
331
    /**
332
     * Returns the number of objects of type <T> - which must extend T
333
     * @param <T>
334
     * @param clazz
335
     * @return
336
     */
337
    public int count(Class<? extends T> clazz);
338

    
339
    /**
340
     * FIXME Should this method exist : I would expect flushing of a session to be
341
     * something that a DAO should hide?
342
     */
343
    public void flush();
344

    
345
    /**
346
     * Convenience method which makes it easy to discover what type of object this DAO returns at runtime
347
     *
348
     * @return
349
     */
350
    public Class<T> getType();
351

    
352
    /**
353
     * Method that counts the number of objects matching the example provided.
354
     * The includeProperties property is used to specify which properties of the example are used.
355
     *
356
     * If includeProperties is null or empty, then all literal properties are used (restrictions are
357
     * applied as in the Hibernate Query-By-Example API call Example.create(object)).
358
     *
359
     * If includeProperties is not empty then only literal properties that are named in the set are used to
360
     * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
361
     * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
362
     * criteria.createCriteria(property).add(Example.create(relatedObject)))
363
     *
364
     * @param example
365
     * @param includeProperties
366
     * @return a count of matching objects
367
     */
368
    public int count(T example, Set<String> includeProperties);
369

    
370
    /**
371
     * Method that lists the objects matching the example provided.
372
     * The includeProperties property is used to specify which properties of the example are used.
373
     *
374
     * If includeProperties is null or empty, then all literal properties are used (restrictions are
375
     * applied as in the Hibernate Query-By-Example API call Example.create(object)).
376
     *
377
     * If includeProperties is not empty then only literal properties that are named in the set are used to
378
     * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
379
     * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
380
     * criteria.createCriteria(property).add(Example.create(relatedObject)))
381
     *
382
     * @param example
383
     * @param includeProperties
384
     * @param limit the maximum number of entities returned (can be null to return
385
     *            all entities)
386
     * @param start The (0-based) offset from the start of the recordset
387
     * @param orderHints
388
     *            Supports path like <code>orderHints.propertyNames</code> which
389
     *            include *-to-one properties like createdBy.username or
390
     * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
391
     * @return a list of matching objects
392
     */
393
    public List<T> list(T example, Set<String> includeProperties, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
394

    
395
}
(4-4/25)