Class Persistence

java.lang.Object
jakarta.persistence.Persistence
public final class Persistence extends Object
Bootstrap class used to obtain an EntityManagerFactory in Java SE environments. 
EntityManagerFactory factory =
        Persistence.createEntityManagerFactory("Library", // name of the persistence unit
                // property overrides
                Map.of(Persistence.ConnectionProperties.JDBC_USER, userName,
                       Persistence.ConnectionProperties.JDBC_PASSWORD, password));
Since createEntityManagerFactory(String) is an expensive operation, and since the EntityManagerFactory is a heavyweight object, the application program should create no more than one factory for each persistence unit.

This class also allows schema management to be decoupled from creation of the entity manager factory. 

Persistence.generateSchema("Library", // name of the persistence unit
        // property overrides
        Map.of(Persistence.SchemaManagementProperties.SCHEMAGEN_DATABASE_ACTION, "create",
               Persistence.ConnectionProperties.JDBC_USER, userName,
               Persistence.ConnectionProperties.JDBC_PASSWORD, password));

The Persistence class may be used to obtain a PersistenceUtil instance in both Jakarta EE and Java SE environments. 

boolean loaded = Persistence.getPersistenceUtil().isLoaded(entity);

The nested interfaces of this class list the standard configuration properties defined by the Jakarta Persistence specification.

Since:
1.0
See Also:
API note:
The Persistence class is available in a Jakarta EE container environment. However, support for the Java SE bootstrapping APIs is not required in container environments.

  • Method Details

    • createEntityManagerFactory

      @Nonnull public static EntityManagerFactory createEntityManagerFactory(@Nonnull String unitName)
      Create and return an EntityManagerFactory for the named persistence unit.
      Parameters:
      unitName - the name of the persistence unit; usually the name specified by the name attribute of the <persistence-unit> element in the persistence.xml file
      Returns:
      an EntityManagerFactory for the named persistence unit
      API note:
      This operation is very expensive. It should usually be called just once for each persistence unit.

    • createEntityManagerFactory

      @Nonnull public static EntityManagerFactory createEntityManagerFactory(@Nonnull String unitName, @Nullable Map<?,?> properties)
      Create and return an EntityManagerFactory for the named persistence unit, using the given properties. Standard properties are enumerated by Persistence.UnitProperties, Persistence.CacheProperties, Persistence.ConnectionProperties, Persistence.JdbcProperties, Persistence.DatabaseProperties, Persistence.SchemaManagementProperties, Persistence.ValidationProperties, and Persistence.BeanManagementProperties. A provider might recognize additional vendor-specific properties. Property values specified via the second argument of this method override property values specified in the persistence.xml file.
      Parameters:
      unitName - the name of the persistence unit; usually the name specified by the name attribute of the <persistence-unit> element in the persistence.xml file
      properties - additional properties to use when creating the factory. These properties may include properties to control schema generation. The values of these properties override any values that may have been configured elsewhere.
      Returns:
      an EntityManagerFactory for the named persistence unit
      API note:
      This operation is very expensive. It should usually be called just once for each persistence unit.

    • createEntityManagerFactory

      @Nonnull public static EntityManagerFactory createEntityManagerFactory(@Nonnull PersistenceConfiguration configuration)
      Create and return an EntityManagerFactory for the named persistence unit, using the given properties.
      Parameters:
      configuration - configuration of the persistence unit
      Returns:
      the factory that creates EntityManagers configured according to the specified persistence unit
      Since:
      3.2
      API note:
      This operation is very expensive. It should usually be called just once for each persistence unit.

    • generateSchema

      public static void generateSchema(@Nonnull String unitName, @Nullable Map<?,?> map)
      Create database schemas and/or tables and/or create DDL scripts as determined by the supplied properties. Standard properties are enumerated by Persistence.SchemaManagementProperties, Persistence.DatabaseProperties, Persistence.ConnectionProperties, and Persistence.UnitProperties. A provider might recognize additional vendor-specific properties. Property values specified via the second argument of this method override property values specified in the persistence.xml file.

      Called when schema generation is to occur as a separate phase from creation of the entity manager factory.

      Parameters:
      unitName - the name of the persistence unit; usually the name specified by the name attribute of the <persistence-unit> element in the persistence.xml file
      map - properties for schema generation; these may also contain provider-specific properties. The values of these properties override any values that may have been configured elsewhere.
      Throws:
      PersistenceException - if insufficient or inconsistent configuration information is provided or if schema generation otherwise fails.
      Since:
      2.1

    • generateSchema

      public static void generateSchema(@Nonnull PersistenceConfiguration configuration)
      Create database schemas and/or tables and/or create DDL scripts as determined by the supplied properties.

      Called when schema generation is to occur as a separate phase from creation of the entity manager factory.

      Parameters:
      configuration - configuration of the persistence unit
      Throws:
      PersistenceException - if insufficient or inconsistent configuration information is provided or if schema generation otherwise fails.
      Since:
      4.0

    • getPersistenceUtil

      @Nonnull public static PersistenceUtil getPersistenceUtil()
      Return the PersistenceUtil instance
      Returns:
      PersistenceUtil instance
      Since:
      2.0