https://github.com/javaee/jpa-spec: Java(TM) Persistence API 
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

/*******************************************************************************
 * 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.

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
EntityManagerFactory has been closed, all its entity managers
are considered to be in the closed state.

Since:Java Persistence 1.0
/**
 * 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 EntityManager.
This method returns a new EntityManager instance each time
it is invoked. 
The isOpen method will return true on the returned instance.

Throws:
Returns:entity manager instance
/**
     * 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 EntityManager with the 
specified Map of properties. 
This method returns a new EntityManager instance each time
it is invoked. 
The isOpen method will return true on the returned instance.

Params:
  • map – properties for entity manager
Throws:
Returns:entity manager instance
/**
     * 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 EntityManager with the 
specified synchronization type.
This method returns a new EntityManager instance each time
it is invoked. 
The isOpen method will return true on the returned instance.

Params:
  • synchronizationType –  how and when the entity manager should be 
synchronized with the current JTA transaction
Throws:
  • IllegalStateException – if the entity manager factory
has been configured for resource-local entity managers or is closed
Returns:entity manager instance
Since:Java Persistence 2.1
/**
     * 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 EntityManager with the 
specified synchronization type and map of properties. 
This method returns a new EntityManager instance each time
it is invoked. 
The isOpen method will return true on the returned instance.

Params:
  • synchronizationType –  how and when the entity manager should be 
synchronized with the current JTA transaction
  • map – properties for entity manager
Throws:
  • IllegalStateException – if the entity manager factory
has been configured for resource-local entity managers or is closed
Returns:entity manager instance
Since:Java Persistence 2.1
/**
     * 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 CriteriaBuilder for the creation of
CriteriaQuery objects.

Throws:
Returns:CriteriaBuilder instance
Since:Java Persistence 2.0
/**
     * 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 Metamodel interface for access to the
metamodel of the persistence unit.

Throws:
Returns:Metamodel instance
Since:Java Persistence 2.0
/**
     * 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.

Returns:boolean indicating whether the factory is open
/**
     * 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 IllegalStateException, except
for isOpen, which will return false. Once an
EntityManagerFactory 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
/**
     * 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.

Throws:
Returns:properties
Since:Java Persistence 2.0
/**
     * 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").

Throws:
Returns:instance of the Cache interface or null if
no cache is in use
Since:Java Persistence 2.0
/**
     * 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.

Throws:
Returns:PersistenceUnitUtil interface
Since:Java Persistence 2.0
/**
     * 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 createNamedQuery or
createNamedStoredProcedureQuery method.

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.

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 createNamedQuery or
createNamedStoredProcedureQuery method.

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.

Params:
  • name – name for the query
  • query – Query, TypedQuery, or StoredProcedureQuery object
Since:Java Persistence 2.1
/**
     * 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.

Params:
  • cls – the class of the object to be returned. This is
normally either the underlying EntityManagerFactory
implementation class or an interface that it implements.
Throws:
Returns:an instance of the specified class
Since:Java Persistence 2.1
/**
     * 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.

Params:
  • graphName –  name for the entity graph
  • entityGraph –  entity graph
Since:Java Persistence 2.1
/**
     * 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);

}