Java tutorial
/******************************************************************************* * Copyright (c) 2008 - 2013 Oracle Corporation. All rights reserved. * * This program and the accompanying materials are made available under the * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 * which accompanies this distribution. * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html * and the Eclipse Distribution License is available at * http://www.eclipse.org/org/documents/edl-v10.php. * * Contributors: * Linda DeMichiel - Java Persistence 2.1 * Linda DeMichiel - Java Persistence 2.0 * ******************************************************************************/ package javax.persistence; import java.util.Map; import javax.persistence.metamodel.Metamodel; import javax.persistence.criteria.CriteriaBuilder; /** * Interface used to interact with the entity manager factory * for the persistence unit. * * <p>When the application has finished using the entity manager * factory, and/or at application shutdown, the application should * close the entity manager factory. Once an * <code>EntityManagerFactory</code> has been closed, all its entity managers * are considered to be in the closed state. * * @since Java Persistence 1.0 */ public interface EntityManagerFactory { /** * Create a new application-managed <code>EntityManager</code>. * This method returns a new <code>EntityManager</code> instance each time * it is invoked. * The <code>isOpen</code> method will return true on the returned instance. * @return entity manager instance * @throws IllegalStateException if the entity manager factory * has been closed */ public EntityManager createEntityManager(); /** * Create a new application-managed <code>EntityManager</code> with the * specified Map of properties. * This method returns a new <code>EntityManager</code> instance each time * it is invoked. * The <code>isOpen</code> method will return true on the returned instance. * @param map properties for entity manager * @return entity manager instance * @throws IllegalStateException if the entity manager factory * has been closed */ public EntityManager createEntityManager(Map map); /** * Create a new JTA application-managed <code>EntityManager</code> with the * specified synchronization type. * This method returns a new <code>EntityManager</code> instance each time * it is invoked. * The <code>isOpen</code> method will return true on the returned instance. * @param synchronizationType how and when the entity manager should be * synchronized with the current JTA transaction * @return entity manager instance * @throws IllegalStateException if the entity manager factory * has been configured for resource-local entity managers or is closed * * @since Java Persistence 2.1 */ public EntityManager createEntityManager(SynchronizationType synchronizationType); /** * Create a new JTA application-managed <code>EntityManager</code> with the * specified synchronization type and map of properties. * This method returns a new <code>EntityManager</code> instance each time * it is invoked. * The <code>isOpen</code> method will return true on the returned instance. * @param synchronizationType how and when the entity manager should be * synchronized with the current JTA transaction * @param map properties for entity manager * @return entity manager instance * @throws IllegalStateException if the entity manager factory * has been configured for resource-local entity managers or is closed * * @since Java Persistence 2.1 */ public EntityManager createEntityManager(SynchronizationType synchronizationType, Map map); /** * Return an instance of <code>CriteriaBuilder</code> for the creation of * <code>CriteriaQuery</code> objects. * @return CriteriaBuilder instance * @throws IllegalStateException if the entity manager factory * has been closed * * @since Java Persistence 2.0 */ public CriteriaBuilder getCriteriaBuilder(); /** * Return an instance of <code>Metamodel</code> interface for access to the * metamodel of the persistence unit. * @return Metamodel instance * @throws IllegalStateException if the entity manager factory * has been closed * * @since Java Persistence 2.0 */ public Metamodel getMetamodel(); /** * Indicates whether the factory is open. Returns true * until the factory has been closed. * @return boolean indicating whether the factory is open */ public boolean isOpen(); /** * Close the factory, releasing any resources that it holds. * After a factory instance has been closed, all methods invoked * on it will throw the <code>IllegalStateException</code>, except * for <code>isOpen</code>, which will return false. Once an * <code>EntityManagerFactory</code> has been closed, all its * entity managers are considered to be in the closed state. * @throws IllegalStateException if the entity manager factory * has been closed */ public void close(); /** * Get the properties and associated values that are in effect * for the entity manager factory. Changing the contents of the * map does not change the configuration in effect. * @return properties * @throws IllegalStateException if the entity manager factory * has been closed * * @since Java Persistence 2.0 */ public Map<String, Object> getProperties(); /** * Access the cache that is associated with the entity manager * factory (the "second level cache"). * @return instance of the <code>Cache</code> interface or null if * no cache is in use * @throws IllegalStateException if the entity manager factory * has been closed * * @since Java Persistence 2.0 */ public Cache getCache(); /** * Return interface providing access to utility methods * for the persistence unit. * @return <code>PersistenceUnitUtil</code> interface * @throws IllegalStateException if the entity manager factory * has been closed * * @since Java Persistence 2.0 */ public PersistenceUnitUtil getPersistenceUnitUtil(); /** * Define the query, typed query, or stored procedure query as * a named query such that future query objects can be created * from it using the <code>createNamedQuery</code> or * <code>createNamedStoredProcedureQuery</code> method. * <p>Any configuration of the query object (except for actual * parameter binding) in effect when the named query is added * is retained as part of the named query definition. * This includes configuration information such as max results, * hints, flush mode, lock mode, result set mapping information, * and information about stored procedure parameters. * <p>When the query is executed, information that can be set * by means of the query APIs can be overridden. Information * that is overridden does not affect the named query as * registered with the entity manager factory, and thus does * not affect subsequent query objects created from it by * means of the <code>createNamedQuery</code> or * <code>createNamedStoredProcedureQuery</code> method. * <p>If a named query of the same name has been previously * defined, either statically via metadata or via this method, * that query definition is replaced. * * @param name name for the query * @param query Query, TypedQuery, or StoredProcedureQuery object * * @since Java Persistence 2.1 */ public void addNamedQuery(String name, Query query); /** * Return an object of the specified type to allow access to the * provider-specific API. If the provider's EntityManagerFactory * implementation does not support the specified class, the * PersistenceException is thrown. * @param cls the class of the object to be returned. This is * normally either the underlying EntityManagerFactory * implementation class or an interface that it implements. * @return an instance of the specified class * @throws PersistenceException if the provider does not * support the call * @since Java Persistence 2.1 */ public <T> T unwrap(Class<T> cls); /** * Add a named copy of the EntityGraph to the * EntityManagerFactory. If an entity graph with the same name * already exists, it is replaced. * @param graphName name for the entity graph * @param entityGraph entity graph * @since Java Persistence 2.1 */ public <T> void addNamedEntityGraph(String graphName, EntityGraph<T> entityGraph); }