EntityManager


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