WebSVN - WebE - Blame - Rev 33 - /trunk/src/javax/persistence/EntityManager.java

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	}

Subversion Repositories WebE

(root)/trunk/src/javax/persistence/EntityManager.java - Rev 33