001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common Development
008: * and Distribution License("CDDL") (collectively, the "License"). You
009: * may not use this file except in compliance with the License. You can obtain
010: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
011: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
012: * language governing permissions and limitations under the License.
013: *
014: * When distributing the software, include this License Header Notice in each
015: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
016: * Sun designates this particular file as subject to the "Classpath" exception
017: * as provided by Sun in the GPL Version 2 section of the License file that
018: * accompanied this code. If applicable, add the following below the License
019: * Header, with the fields enclosed by brackets [] replaced by your own
020: * identifying information: "Portions Copyrighted [year]
021: * [name of copyright owner]"
022: *
023: * Contributor(s):
024: *
025: * If you wish your version of this file to be governed by only the CDDL or
026: * only the GPL Version 2, indicate your decision by adding "[Contributor]
027: * elects to include this software in this distribution under the [CDDL or GPL
028: * Version 2] license." If you don't indicate a single choice of license, a
029: * recipient has the option to distribute your version of this file under
030: * either the CDDL, the GPL Version 2 or to extend the choice of license to
031: * its licensees as provided above. However, if you add GPL Version 2 code
032: * and therefore, elected the GPL Version 2 license, then the option applies
033: * only if the new code is made subject to such option by the copyright
034: * holder.
035: */
036: package javax.persistence;
037:
038: /**
039: * Interface used to interact with the persistence context.
040: *
041: * <p> An <code>EntityManager</code> instance is associated with
042: * a persistence context. A persistence context is a set of entity
043: * instances in which for any persistent entity identity there is
044: * a unique entity instance. Within the persistence context, the
045: * entity instances and their lifecycle are managed. This interface
046: * defines the methods that are used to interact with the
047: * persistence context. The <code>EntityManager</code> API is used
048: * to create and remove persistent entity instances, to find entities
049: * by their primary key, and to query over entities.
050: *
051: * <p> The set of entities that can be managed by a given
052: * <code>EntityManager</code> instance is defined by a persistence
053: * unit. A persistence unit defines the set of all classes that are
054: * related or grouped by the application, and which must be
055: * colocated in their mapping to a single database.
056: *
057: * @since Java Persistence 1.0
058: */
059: public interface EntityManager {
060:
061: /**
062: * Make an entity instance managed and persistent.
063: * @param entity
064: * @throws EntityExistsException if the entity already exists.
065: * (The EntityExistsException may be thrown when the persist
066: * operation is invoked, or the EntityExistsException or
067: * another PersistenceException may be thrown at flush or commit
068: * time.)
069: * @throws IllegalStateException if this EntityManager has been closed.
070: * @throws IllegalArgumentException if not an entity
071: * @throws TransactionRequiredException if invoked on a
072: * container-managed entity manager of type
073: * PersistenceContextType.TRANSACTION and there is
074: * no transaction.
075: */
076: public void persist(Object entity);
077:
078: /**
079: * Merge the state of the given entity into the
080: * current persistence context.
081: * @param entity
082: * @return the instance that the state was merged to
083: * @throws IllegalStateException if this EntityManager has been closed.
084: * @throws IllegalArgumentException if instance is not an
085: * entity or is a removed entity
086: * @throws TransactionRequiredException if invoked on a
087: * container-managed entity manager of type
088: * PersistenceContextType.TRANSACTION and there is
089: * no transaction.
090: */
091: public <T> T merge(T entity);
092:
093: /**
094: * Remove the entity instance.
095: * @param entity
096: * @throws IllegalStateException if this EntityManager has been closed.
097: * @throws IllegalArgumentException if not an entity
098: * or if a detached entity
099: * @throws TransactionRequiredException if invoked on a
100: * container-managed entity manager of type
101: * PersistenceContextType.TRANSACTION and there is
102: * no transaction.
103: */
104: public void remove(Object entity);
105:
106: /**
107: * Find by primary key.
108: * @param entityClass
109: * @param primaryKey
110: * @return the found entity instance or null
111: * if the entity does not exist
112: * @throws IllegalStateException if this EntityManager has been closed.
113: * @throws IllegalArgumentException if the first argument does
114: * not denote an entity type or the second
115: * argument is not a valid type for that
116: * entity's primary key
117: */
118: public <T> T find(Class<T> entityClass, Object primaryKey);
119:
120: /**
121: * Get an instance, whose state may be lazily fetched.
122: * If the requested instance does not exist in the database,
123: * throws {@link EntityNotFoundException} when the instance state is
124: * first accessed. (The persistence provider runtime is permitted to throw
125: * {@link EntityNotFoundException} when {@link #getReference} is called.)
126: *
127: * The application should not expect that the instance state will
128: * be available upon detachment, unless it was accessed by the
129: * application while the entity manager was open.
130: * @param entityClass
131: * @param primaryKey
132: * @return the found entity instance
133: * @throws IllegalStateException if this EntityManager has been closed.
134: * @throws IllegalArgumentException if the first argument does
135: * not denote an entity type or the second
136: * argument is not a valid type for that
137: * entity's primary key
138: * @throws EntityNotFoundException if the entity state
139: * cannot be accessed
140: */
141: public <T> T getReference(Class<T> entityClass, Object primaryKey);
142:
143: /**
144: * Synchronize the persistence context to the
145: * underlying database.
146: * @throws IllegalStateException if this EntityManager has been closed.
147: * @throws TransactionRequiredException if there is
148: * no transaction
149: * @throws PersistenceException if the flush fails
150: */
151: public void flush();
152:
153: /**
154: * Set the flush mode that applies to all objects contained
155: * in the persistence context.
156: * @param flushMode
157: * @throws IllegalStateException if this EntityManager has been closed.
158: */
159: public void setFlushMode(FlushModeType flushMode);
160:
161: /**
162: * Get the flush mode that applies to all objects contained
163: * in the persistence context.
164: * @return flush mode
165: * @throws IllegalStateException if this EntityManager has been closed.
166: */
167: public FlushModeType getFlushMode();
168:
169: /**
170: * Set the lock mode for an entity object contained
171: * in the persistence context.
172: * @param entity
173: * @param lockMode
174: * @throws IllegalStateException if this EntityManager has been closed.
175: * @throws PersistenceException if an unsupported lock call
176: * is made
177: * @throws IllegalArgumentException if the instance is not
178: * an entity or is a detached entity
179: * @throws TransactionRequiredException if there is no
180: * transaction
181: */
182: public void lock(Object entity, LockModeType lockMode);
183:
184: /**
185: * Refresh the state of the instance from the database,
186: * overwriting changes made to the entity, if any.
187: * @param entity
188: * @throws IllegalStateException if this EntityManager has been closed.
189: * @throws IllegalArgumentException if not an entity
190: * or entity is not managed
191: * @throws TransactionRequiredException if invoked on a
192: * container-managed entity manager of type
193: * PersistenceContextType.TRANSACTION and there is
194: * no transaction.
195: * @throws EntityNotFoundException if the entity no longer
196: * exists in the database.
197: */
198: public void refresh(Object entity);
199:
200: /**
201: * Clear the persistence context, causing all managed
202: * entities to become detached. Changes made to entities that
203: * have not been flushed to the database will not be
204: * persisted.
205: * @throws IllegalStateException if this EntityManager has been closed.
206: */
207: public void clear();
208:
209: /**
210: * Check if the instance belongs to the current persistence
211: * context.
212: * @param entity
213: * @return <code>true</code> if the instance belongs to
214: * the current persistence context.
215: * @throws IllegalStateException if this EntityManager has been closed.
216: * @throws IllegalArgumentException if not an entity
217: */
218: public boolean contains(Object entity);
219:
220: /**
221: * Create an instance of Query for executing a
222: * Java Persistence query language statement.
223: * @param qlString a Java Persistence query language query string
224: * @return the new query instance
225: * @throws IllegalStateException if this EntityManager has been closed.
226: * @throws IllegalArgumentException if query string is not valid
227: */
228: public Query createQuery(String qlString);
229:
230: /**
231: * Create an instance of Query for executing a
232: * named query (in the Java Persistence query language or in native SQL).
233: * @param name the name of a query defined in metadata
234: * @return the new query instance
235: * @throws IllegalStateException if this EntityManager has been closed.
236: * @throws IllegalArgumentException if a query has not been
237: * defined with the given name
238: */
239: public Query createNamedQuery(String name);
240:
241: /**
242: * Create an instance of Query for executing
243: * a native SQL statement, e.g., for update or delete.
244: * @param sqlString a native SQL query string
245: * @return the new query instance
246: * @throws IllegalStateException if this EntityManager has been closed.
247: */
248: public Query createNativeQuery(String sqlString);
249:
250: /**
251: * Create an instance of Query for executing
252: * a native SQL query.
253: * @param sqlString a native SQL query string
254: * @param resultClass the class of the resulting instance(s)
255: * @return the new query instance
256: * @throws IllegalStateException if this EntityManager has been closed.
257: */
258: public Query createNativeQuery(String sqlString, Class resultClass);
259:
260: /**
261: * Create an instance of Query for executing
262: * a native SQL query.
263: * @param sqlString a native SQL query string
264: * @param resultSetMapping the name of the result set mapping
265: * @return the new query instance
266: * @throws IllegalStateException if this EntityManager has been closed.
267: */
268: public Query createNativeQuery(String sqlString,
269: String resultSetMapping);
270:
271: /**
272: * Indicate to the EntityManager that a JTA transaction is
273: * active. This method should be called on a JTA application
274: * managed EntityManager that was created outside the scope
275: * of the active transaction to associate it with the current
276: * JTA transaction.
277: * @throws IllegalStateException if this EntityManager has been closed.
278: * @throws TransactionRequiredException if there is
279: * no transaction.
280: */
281: public void joinTransaction();
282:
283: /**
284: * Return the underlying provider object for the EntityManager,
285: * if available. The result of this method is implementation
286: * specific.
287: * @throws IllegalStateException if this EntityManager has been closed.
288: */
289: public Object getDelegate();
290:
291: /**
292: * Close an application-managed EntityManager.
293: * After the close method has been invoked, all methods
294: * on the EntityManager instance and any Query objects obtained
295: * from it will throw the IllegalStateException except
296: * for getTransaction and isOpen (which will return false).
297: * If this method is called when the EntityManager is
298: * associated with an active transaction, the persistence
299: * context remains managed until the transaction completes.
300: * @throws IllegalStateException if the EntityManager
301: * is container-managed or has been already closed..
302: */
303: public void close();
304:
305: /**
306: * Determine whether the EntityManager is open.
307: * @return true until the EntityManager has been closed.
308: */
309: public boolean isOpen();
310:
311: /**
312: * Returns the resource-level transaction object.
313: * The EntityTransaction instance may be used serially to
314: * begin and commit multiple transactions.
315: * @return EntityTransaction instance
316: * @throws IllegalStateException if invoked on a JTA
317: * EntityManager.
318: */
319: public EntityTransaction getTransaction();
320:
321: }
|