001: /**
002: * EasyBeans
003: * Copyright (C) 2006 Bull S.A.S.
004: * Contact: easybeans@ow2.org
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation; either
009: * version 2.1 of the License, or any later version.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: *
016: * You should have received a copy of the GNU Lesser General Public
017: * License along with this library; if not, write to the Free Software
018: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
019: * USA
020: *
021: * --------------------------------------------------------------------------
022: * $Id: TxEntityManager.java 1970 2007-10-16 11:49:25Z benoitf $
023: * --------------------------------------------------------------------------
024: */package org.ow2.easybeans.persistence;
025:
026: import javax.persistence.EntityManager;
027: import javax.persistence.EntityNotFoundException;
028: import javax.persistence.EntityTransaction;
029: import javax.persistence.FlushModeType;
030: import javax.persistence.LockModeType;
031: import javax.persistence.PersistenceException;
032: import javax.persistence.Query;
033: import javax.persistence.TransactionRequiredException;
034:
035: /**
036: * This class represents an EntityManager that will be used as a container
037: * managed transaction scoped persistence context. The lifetime of this context
038: * is a single transaction. When the transaction is committed or rollbacked, the
039: * persistence context ends.
040: * @author Florent Benoit
041: */
042: public class TxEntityManager implements EntityManager {
043:
044: /**
045: * Handler of the manager. Do the switch for each TX.
046: */
047: private TxEntityManagerHandler handler;
048:
049: /**
050: * Build a new entity manager which have TransactionScoped type.
051: * @param handler object managing the transaction's EntityManager.
052: */
053: public TxEntityManager(final TxEntityManagerHandler handler) {
054: this .handler = handler;
055: }
056:
057: /**
058: * Gets (or create) a new EntityManager for the current tx (if any).
059: * @return an entity manager.
060: */
061: public EntityManager getCurrentEntityManager() {
062: return handler.getCurrent();
063: }
064:
065: /**
066: * Make an instance managed and persistent.
067: * @param entity entity bean.
068: * @throws IllegalArgumentException if not an entity or entity is detached
069: * @throws TransactionRequiredException if there is no transaction and the
070: * persistence context is of type PersistenceContextType.TRANSACTION
071: */
072: public void persist(final Object entity)
073: throws IllegalArgumentException,
074: TransactionRequiredException {
075: getCurrentEntityManager().persist(entity);
076: }
077:
078: /**
079: * Merge the state of the given entity into the current persistence context.
080: * @param entity entity bean
081: * @param <T> entity object's class.
082: * @return the instance that the state was merged to
083: * @throws IllegalArgumentException if instance is not an entity or is a
084: * removed entity
085: * @throws TransactionRequiredException if there is no transaction and the
086: * persistence context is of type PersistenceContextType.TRANSACTION
087: */
088: public <T> T merge(final T entity) throws IllegalArgumentException,
089: TransactionRequiredException {
090: return getCurrentEntityManager().merge(entity);
091: }
092:
093: /**
094: * Remove the entity instance.
095: * @param entity entity bean
096: * @throws IllegalArgumentException if not an entity or if a detached entity
097: * @throws TransactionRequiredException if there is no transaction and the
098: * persistence context is of type PersistenceContextType.TRANSACTION
099: */
100: public void remove(final Object entity)
101: throws IllegalArgumentException,
102: TransactionRequiredException {
103: getCurrentEntityManager().remove(entity);
104: }
105:
106: /**
107: * Find by primary key.
108: * @param <T> entity object's class.
109: * @param entityClass the class of the entity
110: * @param primaryKey the primary key
111: * @return the found entity instance or null if the entity does not exist
112: * @throws IllegalArgumentException if the first argument does not denote an
113: * entity type or the second argument is not a valid type for that
114: * entity?s primary key
115: */
116: public <T> T find(final Class<T> entityClass,
117: final Object primaryKey) throws IllegalArgumentException {
118: return getCurrentEntityManager().find(entityClass, primaryKey);
119: }
120:
121: /**
122: * Get an instance, whose state may be lazily fetched. If the requested
123: * instance does not exist in the database, throws EntityNotFoundException
124: * when the instance state is first accessed. (The persistence provider
125: * runtime is permitted to throw the EntityNotFoundException when
126: * getReference is called.) The application should not expect that the
127: * instance state will be available upon detachment, unless it was accessed
128: * by the application while the entity manager was open.
129: * @param <T> entity object's class.
130: * @param entityClass the class of the entity
131: * @param primaryKey the primary key
132: * @return the found entity instance
133: * @throws IllegalArgumentException if the first argument does not denote an
134: * entity type or the second argument is not a valid type for that
135: * entity?s primary key
136: * @throws EntityNotFoundException if the entity state cannot be accessed
137: */
138: public <T> T getReference(final Class<T> entityClass,
139: final Object primaryKey) throws IllegalArgumentException,
140: EntityNotFoundException {
141: return getCurrentEntityManager().getReference(entityClass,
142: primaryKey);
143: }
144:
145: /**
146: * Synchronize the persistence context to the underlying database.
147: * @throws TransactionRequiredException if there is no transaction
148: * @throws PersistenceException if the flush fails
149: */
150: public void flush() throws TransactionRequiredException,
151: PersistenceException {
152: getCurrentEntityManager().flush();
153: }
154:
155: /**
156: * Set the flush mode that applies to all objects contained in the
157: * persistence context.
158: * @param flushMode the mode of flushing
159: */
160: public void setFlushMode(final FlushModeType flushMode) {
161: getCurrentEntityManager().setFlushMode(flushMode);
162:
163: }
164:
165: /**
166: * Get the flush mode that applies to all objects contained in the
167: * persistence context.
168: * @return flushMode
169: */
170: public FlushModeType getFlushMode() {
171: return getCurrentEntityManager().getFlushMode();
172: }
173:
174: /**
175: * Set the lock mode for an entity object contained in the persistence
176: * context.
177: * @param entity entity bean
178: * @param lockMode mode for locking
179: * @throws PersistenceException if an unsupported lock call is made
180: * @throws IllegalArgumentException if the instance is not an entity or is a
181: * detached entity
182: * @throws TransactionRequiredException if there is no transaction
183: */
184: public void lock(final Object entity, final LockModeType lockMode)
185: throws PersistenceException, IllegalArgumentException,
186: TransactionRequiredException {
187: getCurrentEntityManager().lock(entity, lockMode);
188: }
189:
190: /**
191: * Refresh the state of the instance from the database, overwriting changes
192: * made to the entity, if any.
193: * @param entity entity bean
194: * @throws IllegalArgumentException if not an entity or entity is not
195: * managed
196: * @throws TransactionRequiredException if there is no transaction and the
197: * persistence context is of type PersistenceContextType.TRANSACTION
198: * @throws EntityNotFoundException if the entity no longer exists in the
199: * database
200: */
201: public void refresh(final Object entity)
202: throws IllegalArgumentException,
203: TransactionRequiredException, EntityNotFoundException {
204: getCurrentEntityManager().refresh(entity);
205: }
206:
207: /**
208: * Clear the persistence context, causing all managed entities to become
209: * detached. Changes made to entities that have not been flushed to the
210: * database will not be persisted.
211: */
212: public void clear() {
213: getCurrentEntityManager().clear();
214: }
215:
216: /**
217: * Check if the instance belongs to the current persistence context.
218: * @param entity the entity bean
219: * @return true/false
220: * @throws IllegalArgumentException if not an entity
221: */
222: public boolean contains(final Object entity)
223: throws IllegalArgumentException {
224: return getCurrentEntityManager().contains(entity);
225: }
226:
227: /**
228: * Create an instance of Query for executing an EJB QL statement.
229: * @param ejbqlString an EJB QL query string
230: * @return the new query instance
231: * @throws IllegalArgumentException if query string is not valid
232: */
233: public Query createQuery(final String ejbqlString)
234: throws IllegalArgumentException {
235: return getCurrentEntityManager().createQuery(ejbqlString);
236: }
237:
238: /**
239: * Create an instance of Query for executing a named query (in EJB QL or
240: * native SQL).
241: * @param name the name of a query defined in metadata
242: * @return the new query instance
243: * @throws IllegalArgumentException if a query has not been defined with the
244: * given name
245: */
246: public Query createNamedQuery(final String name)
247: throws IllegalArgumentException {
248: return getCurrentEntityManager().createNamedQuery(name);
249: }
250:
251: /**
252: * Create an instance of Query for executing a native SQL statement, e.g.,
253: * for update or delete.
254: * @param sqlString a native SQL query string
255: * @return the new query instance
256: */
257: public Query createNativeQuery(final String sqlString) {
258: return getCurrentEntityManager().createNativeQuery(sqlString);
259: }
260:
261: /**
262: * Create an instance of Query for executing a native SQL query.
263: * @param sqlString a native SQL query string
264: * @param resultClass the class of the resulting instance(s)
265: * @return the new query instance
266: */
267: public Query createNativeQuery(final String sqlString,
268: final Class resultClass) {
269: return getCurrentEntityManager().createNativeQuery(sqlString,
270: resultClass);
271: }
272:
273: /**
274: * Create an instance of Query for executing a native SQL query.
275: * @param sqlString a native SQL query string
276: * @param resultSetMapping the name of the result set mapping
277: * @return the new query instance
278: */
279: public Query createNativeQuery(final String sqlString,
280: final String resultSetMapping) {
281: return getCurrentEntityManager().createNativeQuery(sqlString,
282: resultSetMapping);
283: }
284:
285: /**
286: * TODO: document this.
287: */
288: public void joinTransaction() {
289: getCurrentEntityManager().joinTransaction();
290: }
291:
292: /**
293: * @return TODO: document this.
294: */
295: public Object getDelegate() {
296: return getCurrentEntityManager().getDelegate();
297: }
298:
299: /**
300: * Close an application-managed EntityManager. After an EntityManager has
301: * been closed, all methods on the EntityManager instance will throw the
302: * IllegalStateException except for isOpen, which will return false. This
303: * method can only be called when the EntityManager is not associated with
304: * an active transaction.
305: * @throws IllegalStateException if the EntityManager is associated with an
306: * active transaction or if the EntityManager is container-managed.
307: */
308: public void close() throws IllegalStateException {
309: getCurrentEntityManager().close();
310: }
311:
312: /**
313: * Determine whether the EntityManager is open.
314: * @return true until the EntityManager has been closed.
315: */
316: public boolean isOpen() {
317: return getCurrentEntityManager().isOpen();
318: }
319:
320: /**
321: * Return the resource-level transaction object. The EntityTransaction
322: * instance may be used serially to begin and commit multiple transactions.
323: * @return EntityTransaction instance
324: * @throws IllegalStateException if invoked on a JTA EntityManager or an
325: * EntityManager that has been closed.
326: */
327: public EntityTransaction getTransaction()
328: throws IllegalStateException {
329: return getCurrentEntityManager().getTransaction();
330: }
331:
332: }
|