Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
33 | PointedEar | 1 | // $Id: EntityManager.java 11282 2007-03-14 22:05:59Z epbernard $ |
2 | package javax.persistence; |
||
3 | |||
4 | /** |
||
5 | * Interface used to interact with the persistence context. |
||
6 | * |
||
7 | * An EntityManager instance is associated with a persistence context. A persistence context is a set of |
||
8 | * entity instances in which for any persistent entity identity there is a unique entity instance. |
||
9 | * Within the persistence context, the entity instances and their lifecycle are managed. This interface |
||
10 | * defines the methods that are used to interact with the persistence context. The EntityManager API is |
||
11 | * used to create and remove persistent entity instances, to find entities by their primary key, and to |
||
12 | * query over entities. |
||
13 | * |
||
14 | * The set of entities that can be managed by a given EntityManager instance is defined by a persistence unit. |
||
15 | * A persistence unit defines the set of all classes that are related or grouped by the application, and |
||
16 | * which must be colocated in their mapping to a single database. |
||
17 | * |
||
18 | * @author Emmanuel Bernard |
||
19 | */ |
||
20 | public interface EntityManager { |
||
21 | /** |
||
22 | * Make an entity instance managed and persistent. |
||
23 | * |
||
24 | * @param entity |
||
25 | * @throws EntityExistsException if the entity already exists. |
||
26 | * (The EntityExistsException may be thrown when the persist |
||
27 | * operation is invoked, or the EntityExistsException or |
||
28 | * another PersistenceException may be thrown at commit |
||
29 | * time.) |
||
30 | * @throws IllegalStateException if this EntityManager has been closed. |
||
31 | * @throws IllegalArgumentException if not an entity |
||
32 | * @throws TransactionRequiredException if invoked on a |
||
33 | * container-managed entity manager of type |
||
34 | * PersistenceContextType.TRANSACTION and there is |
||
35 | * no transaction. |
||
36 | */ |
||
37 | public void persist(Object entity); |
||
38 | |||
39 | /** |
||
40 | * Merge the state of the given entity into the |
||
41 | * current persistence context. |
||
42 | * |
||
43 | * @param entity |
||
44 | * @return the instance that the state was merged to |
||
45 | * @throws IllegalStateException if this EntityManager has been closed |
||
46 | * @throws IllegalArgumentException if instance is not an |
||
47 | * entity or is a removed entity |
||
48 | * @throws TransactionRequiredException if invoked on a |
||
49 | * container-managed entity manager of type |
||
50 | * PersistenceContextType.TRANSACTION and there is |
||
51 | * no transaction. |
||
52 | */ |
||
53 | public <T> T merge(T entity); |
||
54 | |||
55 | /** |
||
56 | * Remove the entity instance. |
||
57 | * |
||
58 | * @param entity |
||
59 | * @throws IllegalStateException if this EntityManager has been closed |
||
60 | * @throws IllegalArgumentException if not an entity |
||
61 | * or if a detached entity |
||
62 | * @throws TransactionRequiredException if invoked on a |
||
63 | * container-managed entity manager of type |
||
64 | * PersistenceContextType.TRANSACTION and there is |
||
65 | * no transaction. |
||
66 | */ |
||
67 | public void remove(Object entity); |
||
68 | |||
69 | /** |
||
70 | * Find by primary key. |
||
71 | * |
||
72 | * @param entityClass |
||
73 | * @param primaryKey |
||
74 | * @return the found entity instance or null |
||
75 | * if the entity does not exist |
||
76 | * @throws IllegalStateException if this EntityManager has been closed |
||
77 | * @throws IllegalArgumentException if the first argument does |
||
78 | * not denote an entity type or the second |
||
79 | * argument is not a valid type for that |
||
80 | * entity’s primary key |
||
81 | */ |
||
82 | public <T> T find(Class<T> entityClass, Object primaryKey); |
||
83 | |||
84 | /** |
||
85 | * Get an instance, whose state may be lazily fetched. |
||
86 | * If the requested instance does not exist in the database, |
||
87 | * the EntityNotFoundException is thrown when the instance |
||
88 | * state is first accessed. (The persistence provider runtime is |
||
89 | * permitted to throw the EntityNotFoundException when |
||
90 | * getReference is called.) |
||
91 | * The application should not expect that the instance state will |
||
92 | * be available upon detachment, unless it was accessed by the |
||
93 | * application while the entity manager was open. |
||
94 | * |
||
95 | * @param entityClass |
||
96 | * @param primaryKey |
||
97 | * @return the found entity instance |
||
98 | * @throws IllegalStateException if this EntityManager has been closed |
||
99 | * @throws IllegalArgumentException if the first argument does |
||
100 | * not denote an entity type or the second |
||
101 | * argument is not a valid type for that |
||
102 | * entity’s primary key |
||
103 | * @throws EntityNotFoundException if the entity state |
||
104 | * cannot be accessed |
||
105 | */ |
||
106 | public <T> T getReference(Class<T> entityClass, Object primaryKey); |
||
107 | |||
108 | /** |
||
109 | * Synchronize the persistence context to the |
||
110 | * underlying database. |
||
111 | * |
||
112 | * @throws IllegalStateException if this EntityManager has been closed |
||
113 | * @throws TransactionRequiredException if there is |
||
114 | * no transaction |
||
115 | * @throws PersistenceException if the flush fails |
||
116 | */ |
||
117 | public void flush(); |
||
118 | |||
119 | /** |
||
120 | * Set the flush mode that applies to all objects contained |
||
121 | * in the persistence context. |
||
122 | * |
||
123 | * @param flushMode |
||
124 | * @throws IllegalStateException if this EntityManager has been closed |
||
125 | */ |
||
126 | public void setFlushMode(FlushModeType flushMode); |
||
127 | |||
128 | /** |
||
129 | * Get the flush mode that applies to all objects contained |
||
130 | * in the persistence context. |
||
131 | * |
||
132 | * @return flushMode |
||
133 | * @throws IllegalStateException if this EntityManager has been closed |
||
134 | */ |
||
135 | public FlushModeType getFlushMode(); |
||
136 | |||
137 | /** |
||
138 | * Set the lock mode for an entity object contained |
||
139 | * in the persistence context. |
||
140 | * |
||
141 | * @param entity |
||
142 | * @param lockMode |
||
143 | * @throws IllegalStateException if this EntityManager has been closed |
||
144 | * @throws PersistenceException if an unsupported lock call |
||
145 | * is made |
||
146 | * @throws IllegalArgumentException if the instance is not |
||
147 | * an entity or is a detached entity |
||
148 | * @throws TransactionRequiredException if there is no |
||
149 | * transaction |
||
150 | */ |
||
151 | public void lock(Object entity, LockModeType lockMode); |
||
152 | |||
153 | /** |
||
154 | * Refresh the state of the instance from the database, |
||
155 | * overwriting changes made to the entity, if any. |
||
156 | * |
||
157 | * @param entity |
||
158 | * @throws IllegalStateException if this EntityManager has been closed |
||
159 | * @throws IllegalArgumentException if not an entity |
||
160 | * or entity is not managed |
||
161 | * @throws TransactionRequiredException if invoked on a |
||
162 | * container-managed entity manager of type |
||
163 | * PersistenceContextType.TRANSACTION and there is |
||
164 | * no transaction. |
||
165 | * @throws EntityNotFoundException if the entity no longer |
||
166 | * exists in the database |
||
167 | */ |
||
168 | public void refresh(Object entity); |
||
169 | |||
170 | /** |
||
171 | * Clear the persistence context, causing all managed |
||
172 | * entities to become detached. Changes made to entities that |
||
173 | * have not been flushed to the database will not be |
||
174 | * persisted. |
||
175 | * |
||
176 | * @throws IllegalStateException if this EntityManager has been closed |
||
177 | */ |
||
178 | public void clear(); |
||
179 | |||
180 | /** |
||
181 | * Check if the instance belongs to the current persistence |
||
182 | * context. |
||
183 | * |
||
184 | * @param entity |
||
185 | * @return <code>true</code> if the instance belongs to the current persistence context. |
||
186 | * @throws IllegalStateException if this EntityManager has been closed |
||
187 | * @throws IllegalArgumentException if not an entity |
||
188 | */ |
||
189 | public boolean contains(Object entity); |
||
190 | |||
191 | /** |
||
192 | * Create an instance of Query for executing an |
||
193 | * EJB QL statement. |
||
194 | * |
||
195 | * @param ejbqlString an EJB QL query string |
||
196 | * @return the new query instance |
||
197 | * @throws IllegalStateException if this EntityManager has been closed |
||
198 | * @throws IllegalArgumentException if query string is not valid |
||
199 | */ |
||
200 | public Query createQuery(String ejbqlString); |
||
201 | |||
202 | /** |
||
203 | * Create an instance of Query for executing a |
||
204 | * named query (in EJB QL or native SQL). |
||
205 | * |
||
206 | * @param name the name of a query defined in metadata |
||
207 | * @return the new query instance |
||
208 | * @throws IllegalStateException if this EntityManager has been closed |
||
209 | * @throws IllegalArgumentException if a query has not been |
||
210 | * defined with the given name |
||
211 | */ |
||
212 | public Query createNamedQuery(String name); |
||
213 | |||
214 | /** |
||
215 | * Create an instance of Query for executing |
||
216 | * a native SQL statement, e.g., for update or delete. |
||
217 | * |
||
218 | * @param sqlString a native SQL query string |
||
219 | * @return the new query instance |
||
220 | * @throws IllegalStateException if this EntityManager has been closed |
||
221 | */ |
||
222 | public Query createNativeQuery(String sqlString); |
||
223 | |||
224 | /** |
||
225 | * Create an instance of Query for executing |
||
226 | * a native SQL query. |
||
227 | * |
||
228 | * @param sqlString a native SQL query string |
||
229 | * @param resultClass the class of the resulting instance(s) |
||
230 | * @return the new query instance |
||
231 | * @throws IllegalStateException if this EntityManager has been closed |
||
232 | */ |
||
233 | public Query createNativeQuery(String sqlString, Class resultClass); |
||
234 | |||
235 | /** |
||
236 | * Create an instance of Query for executing |
||
237 | * a native SQL query. |
||
238 | * |
||
239 | * @param sqlString a native SQL query string |
||
240 | * @param resultSetMapping the name of the result set mapping |
||
241 | * @return the new query instance |
||
242 | * @throws IllegalStateException if this EntityManager has been closed |
||
243 | */ |
||
244 | public Query createNativeQuery(String sqlString, String resultSetMapping); |
||
245 | |||
246 | /** |
||
247 | * Indicate to the EntityManager that a JTA transaction is |
||
248 | * active. This method should be called on a JTA application |
||
249 | * managed EntityManager that was created outside the scope |
||
250 | * of the active transaction to associate it with the current |
||
251 | * JTA transaction. |
||
252 | * |
||
253 | * @throws IllegalStateException if this EntityManager has been closed |
||
254 | * @throws TransactionRequiredException if there is |
||
255 | * no transaction. |
||
256 | */ |
||
257 | public void joinTransaction(); |
||
258 | |||
259 | /** |
||
260 | * Return the underlying provider object for the EntityManager, if available. |
||
261 | * The result of this method is implementation specific |
||
262 | * |
||
263 | * @throws IllegalStateException if this EntityManager has been closed |
||
264 | */ |
||
265 | public Object getDelegate(); |
||
266 | |||
267 | /** |
||
268 | * Close an application-managed EntityManager. |
||
269 | * After the close method has been invoked, all methods |
||
270 | * on the EntityManager instance and any Query objects obtained |
||
271 | * from it will throw the IllegalStateException except |
||
272 | * for getTransaction and isOpen (which will return false). |
||
273 | * If this method is called when the EntityManager is |
||
274 | * associated with an active transaction, the persistence |
||
275 | * context remains managed until the transaction completes. |
||
276 | * |
||
277 | * @throws IllegalStateException if the EntityManager is container-managed or has been already closed |
||
278 | */ |
||
279 | public void close(); |
||
280 | |||
281 | /** |
||
282 | * Determine whether the EntityManager is open. |
||
283 | * |
||
284 | * @return true until the EntityManager has been closed. |
||
285 | */ |
||
286 | public boolean isOpen(); |
||
287 | |||
288 | /** |
||
289 | * Return the resource-level transaction object. |
||
290 | * The EntityTransaction instance may be used serially to |
||
291 | * begin and commit multiple transactions. |
||
292 | * |
||
293 | * @return EntityTransaction instance |
||
294 | * @throws IllegalStateException if invoked on a JTA |
||
295 | * EntityManager. |
||
296 | */ |
||
297 | public EntityTransaction getTransaction(); |
||
298 | } |