1 /*
2 * EL4J, the Extension Library for the J2EE, adds incremental enhancements to
3 * the spring framework, http://el4j.sf.net
4 * Copyright (C) 2005 by ELCA Informatique SA, Av. de la Harpe 22-24,
5 * 1000 Lausanne, Switzerland, http://www.elca.ch
6 *
7 * EL4J is published under the GNU Lesser General Public License (LGPL)
8 * Version 2.1. See http://www.gnu.org/licenses/
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU Lesser General Public License for more details.
14 *
15 * For alternative licensing, please contact info@elca.ch
16 */
17 package ch.elca.el4j.services.persistence.jpa.helper;
18
19 import javax.persistence.EntityManager;
20
21 import ch.elca.el4j.services.persistence.jpa.util.JpaQuery;
22
23 /**
24 * Utility class and methods to make database access easier.
25 *
26 * Type safety is given under the following conditions:
27 *
28 * When searching, the class provided must be a domain class and any properties
29 * provided must be applicable to that class.
30 * For example, selectFrom(A.class).with("b", some_b)
31 * requires that A is a domain class with a property b of a type corresponding
32 * to the class of some_b.
33 *
34 * @svnLink $Revision: 4122 $;$Date: 2010-08-19 13:27:36 +0200 (Do, 19. Aug 2010) $;$Author: swrelca $;$URL: https://el4j.svn.sourceforge.net/svnroot/el4j/branches/el4j_3_1/el4j/framework/modules/hibernate/src/main/java/ch/elca/el4j/services/persistence/jpa/helper/JpaHelper.java $
35 *
36 * @author David Bernhard (dab)
37 */
38 public interface JpaHelper {
39
40 /**
41 * Initiate a select query.
42 * @param <T> Generic type parameter for the class to select from.
43 * @param cls The class to select from.
44 * @return The query object.
45 */
46 public <T> JpaQuery<T> selectFrom(Class<T> cls);
47
48 /**
49 * Contains an entry.
50 * @param <T> The type parameter.
51 * @param instance The object to check if the entity manager contains it.
52 * @return Boolean, true it is contained.
53 */
54 public <T> Boolean contains(T instance);
55
56 /**
57 * Merge the state of the given entity into the current persistence context.
58 * Transition from <code>DETACHED</code> to <code>MANAGED</code>.
59 *
60 * @param <T> The type parameter, to allow us to return the merged object.
61 * @param instance The object to merge.
62 * @return The managed entity.
63 */
64 public <T> T merge(T instance);
65
66 /**
67 * Remove the given entity from the persistence context, causing a managed entity to become detached.
68 * Unflushed changes made to the entity if any (including removal of the entity), will not be synchronized
69 * to the database. Entities which previously referenced the detached entity will continue to reference it.
70 * Transition from <code>MANAGED</code> to <code>DETACHED</code>.
71 *
72 * @param <T> The type parameter.
73 * @param instance The object to detach.
74 */
75 public <T> void detach(T instance);
76
77 /**
78 * Makes an entity managed and persistent. Transition from state <code>NEW</code>/<code>REMOVED</code>
79 * to <code>MANAGED</code>.
80 * On the next <code>flush</code> or <code>commit</code> it is inserted into the database.<br>
81 * @param <T> The type parameter.
82 * @param instance The object to persist.
83 */
84 public <T> void persist(T instance);
85
86 /**
87 * Delete a <code>MANAGED</code> entity. Transition from state <code>MANAGED</code> to <code>REMOVED</code>.
88 * On the next <code>flush</code> or <code>commit</code> it is removed from the database.<br>
89 * @param <T> The type parameter.
90 * @param instance The instance to delete.
91 */
92 public <T> void remove(T instance);
93
94 /**
95 * Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
96 * Transition from state <code>MANAGED</code> to <code>MANAGED</code> again.
97 * @param <T> The type parameter.
98 * @param instance The instance to refresh.
99 */
100 public <T> void refresh(T instance);
101
102 /**
103 * Finds an entity by its primary key. The returned entity is <code>MANAGED</code>.
104 *
105 * @param <T> The type parameter, to allow us to return the searched object.
106 * @param clazz The entity class.
107 * @param key The primary key.
108 * @return The searched entity (<code>MANAGED</code>).
109 */
110 public <T> T findByKey(Class<T> clazz, Integer key);
111
112 /**
113 * Clear the session.
114 */
115 public void clear();
116
117 /**
118 * Flush the session.
119 */
120 public void flush();
121
122 public void doInTransaction(Runnable r);
123 }