Interface PersistenceProvider

public interface PersistenceProvider
Interface implemented by the persistence provider.

In Java SE, the Persistence class calls:

In a Jakarta EE environment, the container calls:

Since:
1.0
API note:
This is an SPI interface forming part of the Jakarta EE container / persistence provider contract. It is not intended for direct use by application programs.

  • Method Details

    • createEntityManagerFactory

      @Nonnull EntityManagerFactory createEntityManagerFactory(@Nonnull String unitName, @Nullable Map<?,?> properties)
      Called by Persistence class to create a new EntityManagerFactory for the persistence unit with the given name, optionally specifying configuration properties which override the settings specified in the persistence.xml file for the given persistence unit.
      Parameters:
      unitName - the name of the persistence unit
      properties - property settings for use by the persistence provider. These properties may be used to specify values for properties not specified in the persistence.xml file for the given persistence unit or to override the values specified by the corresponding elements of the persistence.xml file. The map may be null when no properties are specified.
      Returns:
      a newly created EntityManagerFactory for the named persistence unit, or null if the persistence unit configuration specified a different persistence provider
      See Also:

    • createEntityManagerFactory

      @Nonnull EntityManagerFactory createEntityManagerFactory(@Nonnull PersistenceConfiguration configuration)
      Called by Persistence class to create a new EntityManagerFactory for a persistence unit with the given programmatic configuration.
      Parameters:
      configuration - the configuration of the persistence unit
      Returns:
      a newly created EntityManagerFactory for the persistence unit with the given configuration, or null if the persistence unit configuration specified a different persistence provider
      Throws:
      IllegalStateException - if any required configuration is missing
      Since:
      3.2
      See Also:

    • createContainerEntityManagerFactory

      @Nonnull EntityManagerFactory createContainerEntityManagerFactory(@Nonnull PersistenceUnitInfo info, @Nullable Map<?,?> properties)
      Called by the Jakarta EE container to create a new EntityManagerFactory for the persistence unit with the given metadata, optionally specifying configuration properties which override the settings specified in the given PersistenceUnitInfo.
      Parameters:
      info - metadata describing the persistence unit
      properties - integration-level property settings for use by the persistence provider. The given properties may include properties to control schema generation. The map may be null when no properties are specified.
      Returns:
      a newly created EntityManagerFactory for the persistence unit described by the given metadata

    • generateSchema

      void generateSchema(@Nonnull PersistenceUnitInfo info, @Nullable Map<?,?> properties)
      Create database schemas and/or tables and/or create DDL scripts, as determined by the supplied properties.

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

      Parameters:
      info - metadata describing the persistence unit
      properties - property settings for schema generation; these may include provider-specific properties
      Throws:
      PersistenceException - if insufficient or inconsistent configuration information is provided or if schema generation otherwise fails
      Since:
      2.1

    • generateSchema

      boolean generateSchema(@Nonnull String persistenceUnitName, @Nullable Map<?,?> properties)
      Create database schemas and/or tables and/or create DDL scripts, as determined by the supplied properties.

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

      Parameters:
      persistenceUnitName - the name of the persistence unit
      properties - property settings for schema generation; these may include provider-specific properties. The values of these properties override any values configured elsewhere.
      Returns:
      true if the schema was generated, otherwise false
      Throws:
      PersistenceException - if insufficient or inconsistent configuration information is provided or if schema generation otherwise fails
      Since:
      2.1

    • generateSchema

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

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

      Parameters:
      configuration - the configuration of the persistence unit
      Returns:
      true if the schema was generated, otherwise false
      Throws:
      PersistenceException - if insufficient or inconsistent configuration information is provided or if schema generation otherwise fails
      Since:
      4.0

    • getProviderUtil

      @Nonnull ProviderUtil getProviderUtil()
      Return the utility interface implemented by the persistence provider.
      Returns:
      an instance of ProviderUtil
      Since:
      2.0

    • getClassTransformer

      @Nonnull ClassTransformer getClassTransformer(@Nonnull PersistenceUnitInfo info, @Nullable Map<?,?> properties)
      Obtain a provider-supplied class transformer that is called for every new class definition or class redefinition performed by the class loader returned by PersistenceUnitInfo.getClassLoader(). The transformer has no effect on the class loader returned by PersistenceUnitInfo.getNewTempClassLoader().

      A class is transformed exactly once within a given classloading scope, regardless of how many persistence units it belongs to.

      The given instance of PersistenceUnitInfo may return null when any of the accessor methods PersistenceUnitInfo.getClassLoader(), PersistenceUnitInfo.getJtaDataSource(), or PersistenceUnitInfo.getNonJtaDataSource() is called by an implementation of this method.

      If the container calls this method before invoking createContainerEntityManagerFactory(PersistenceUnitInfo, Map) to create the EntityManagerFactory, then the transformer returned by this method is used instead of any transformer registered via PersistenceUnitInfo.addTransformer(ClassTransformer). The container is not required to call this method.

      Parameters:
      info - metadata describing the persistence unit
      properties - integration-level property settings for use by the persistence provider, which will not usually contain a ValidatorFactory or BeanManager.
      Returns:
      a provider-supplied transformer that is later invoked by the container when a managed class belonging to the persistence unit is defined or redefined
      Since:
      4.0