EzyJPA helps an EzyFox application initialize a JPA database context, create repositories, and work with relational databases through JPA/Hibernate.

It uses:

HikariCP for DataSource and connection pooling.
JPA EntityManagerFactory for persistence.
Hibernate as the preferred JPA provider when available.
EzyData database context for repository scanning and registration.

Configuration List

EzyJPA reads application properties and sends them to two main places:

Properties under datasource.* are used to configure HikariCP.
JPA/Hibernate properties such as hibernate.* are passed to the JPA provider.

#	Property	Default Value	Description
1	datasource.jdbcUrl or datasource.jdbc_url	null	JDBC connection URL.
2	datasource.username	null	Database username.
3	datasource.password	null	Database password.
4	datasource.driverClassName or datasource.driver_class_name	null	JDBC driver class name.
5	datasource.maximumPoolSize or datasource.maximum_pool_size	HikariCP default	Maximum number of connections in the pool.
6	datasource.minimumIdle or datasource.minimum_idle	HikariCP default	Minimum number of idle connections kept in the pool.
7	datasource.connectionTimeout or datasource.connection_timeout	HikariCP default	Maximum time to wait for a connection from the pool.
8	datasource.idleTimeout or datasource.idle_timeout	HikariCP default	Maximum time a connection can stay idle in the pool.
9	datasource.maxLifetime or datasource.max_lifetime	HikariCP default	Maximum lifetime of a pooled connection.
10	datasource.poolName or datasource.pool_name	HikariCP default	Name of the HikariCP connection pool.
11	datasource.autoCommit or datasource.auto_commit	HikariCP default	Whether connections use auto commit by default.
12	hibernate.show_sql	Hibernate default	Whether Hibernate prints SQL statements.
13	hibernate.format_sql	Hibernate default	Whether Hibernate formats printed SQL statements.
14	hibernate.dialect	Hibernate default	Hibernate SQL dialect, for example `org.hibernate.dialect.MySQLDialect`.
15	hibernate.hbm2ddl.auto	Hibernate default	Schema generation strategy, for example `none`, `validate`, `update`, `create`, or `create-drop`.

Because the datasource configuration is backed by HikariCP, you can also use other HikariCP properties. You can encrypt sensitive configuration such as datasource.username and datasource.password if your application enables encrypted properties.

How Properties Are Mapped

When EzyJPA creates a datasource, it reads properties with the datasource prefix, removes that prefix, converts underscore names to camelCase, and maps the result to HikariCP.

For example:

datasource.jdbc_url=jdbc:mysql://localhost:3306/test
datasource.driver_class_name=com.mysql.cj.jdbc.Driver
datasource.maximum_pool_size=16

is mapped to HikariCP as:

jdbcUrl=jdbc:mysql://localhost:3306/test
driverClassName=com.mysql.cj.jdbc.Driver
maximumPoolSize=16

So both camelCase and underscore style can be used for datasource properties:

datasource.jdbcUrl=jdbc:mysql://localhost:3306/test

or:

datasource.jdbc_url=jdbc:mysql://localhost:3306/test

Hibernate properties should keep their standard names, for example:

hibernate.show_sql=true
hibernate.format_sql=true
hibernate.hbm2ddl.auto=update

An Example

You can put the following configuration into application.yaml:

datasource:
  jdbcUrl: jdbc:mysql://localhost:3306/test
  username: root
  password: 12345678
  driverClassName: com.mysql.cj.jdbc.Driver
  maximumPoolSize: 16
  minimumIdle: 2

hibernate:
  show_sql: true
  format_sql: true
  dialect: org.hibernate.dialect.MySQLDialect
  hbm2ddl:
    auto: update

Or into application.properties:

datasource.jdbcUrl=jdbc:mysql://localhost:3306/test
datasource.username=root
datasource.password=12345678
datasource.driverClassName=com.mysql.cj.jdbc.Driver
datasource.maximumPoolSize=16
datasource.minimumIdle=2

hibernate.show_sql=true
hibernate.format_sql=true
hibernate.dialect=org.hibernate.dialect.MySQLDialect
hibernate.hbm2ddl.auto=update

The old datasource.database_name style is not a direct HikariCP setting. Prefer putting the database name in datasource.jdbcUrl.

Auto Configuration

To configure EzyJPA automatically, add ezyfox-boot-autoconfigure to your project:

<dependency>
    <groupId>com.tvd12</groupId>
    <artifactId>ezyfox-boot-autoconfigure</artifactId>
    <version>1.1.2</version>
</dependency>

By default, EzyFox Boot loads application.properties and application.yaml. You can put datasource properties directly into one of these files:

datasource.jdbcUrl=jdbc:mysql://localhost:3306/test
datasource.driverClassName=com.mysql.cj.jdbc.Driver
datasource.username=root
datasource.password=12345678

If you want to use another configuration file, add @EzyPropertiesSources to your startup class:

@EzyPropertiesSources({"database.properties"})
public class ServerStartup {
    public static void main(String[] args) throws Exception {
        // start application
    }
}

The JPA auto configuration receives the loaded Properties from EzyFox Boot and initializes the JPA database context automatically. It does the following:

Creates a DataSource from properties under the datasource prefix.
Creates an EntityManagerFactory with persistence unit name Default.
Uses the application packages-to-scan as JPA entity packages.
Builds an EzyJPA database context.
Adds discovered repositories to the EzyFox singleton factory.

In the common case, you only need to add the dependency and provide datasource properties. You do not need to manually create DataSource, EntityManagerFactory, or EzyDatabaseContext.

Configure Manually

If you cannot use ezyfox-boot-autoconfigure, you can configure EzyJPA manually:

import com.tvd12.ezydata.database.EzyDatabaseContext;
import com.tvd12.ezydata.jpa.EzyJpaDatabaseContextBuilder;
import com.tvd12.ezydata.jpa.loader.EzyJpaDataSourceLoader;
import com.tvd12.ezydata.jpa.loader.EzyJpaEntityManagerFactoryLoader;
import com.tvd12.ezyfox.bean.EzyBeanConfig;
import com.tvd12.ezyfox.bean.EzyPackagesToScanAware;
import com.tvd12.ezyfox.bean.EzySingletonFactory;
import com.tvd12.ezyfox.bean.EzySingletonFactoryAware;
import com.tvd12.ezyfox.bean.annotation.EzyAutoBind;
import com.tvd12.ezyfox.bean.annotation.EzyConfigurationBefore;
import com.tvd12.ezyfox.util.EzyPropertiesAware;
import lombok.Setter;

import javax.persistence.EntityManagerFactory;
import javax.sql.DataSource;
import java.util.Properties;
import java.util.Set;

import static com.tvd12.ezyfox.boot.util.EzyDatabaseContexts
    .addRepositoriesFromDatabaseContextToSingletonFactory;

@Setter
@EzyConfigurationBefore
public class EzyJpaConfiguration implements
    EzyBeanConfig,
    EzyPropertiesAware,
    EzyPackagesToScanAware,
    EzySingletonFactoryAware {

    private Properties properties;
    private Set<String> packagesToScan;

    @EzyAutoBind
    private EzySingletonFactory singletonFactory;

    @Override
    public void config() {
        addRepositoriesFromDatabaseContextToSingletonFactory(
            databaseContext(),
            singletonFactory
        );
    }

    private EzyDatabaseContext databaseContext() {
        return new EzyJpaDatabaseContextBuilder()
            .properties(properties)
            .entityManagerFactory(entityManagerFactory())
            .scan(packagesToScan)
            .build();
    }

    private EntityManagerFactory entityManagerFactory() {
        return new EzyJpaEntityManagerFactoryLoader()
            .entityPackages(packagesToScan)
            .dataSource(dataSource())
            .properties(properties)
            .load("Default");
    }

    private DataSource dataSource() {
        return new EzyJpaDataSourceLoader()
            .properties(properties, "datasource")
            .load();
    }
}

This manual configuration is almost the same flow as auto configuration: load datasource properties, create EntityManagerFactory, build database context, and register repositories.

Configure EntityManagerFactory Directly

If you already have a standard JPA setup with META-INF/persistence.xml, you can create the EntityManagerFactory yourself and pass it to EzyJPA:

EntityManagerFactory entityManagerFactory =
    Persistence.createEntityManagerFactory("UsersDB");

EzyDatabaseContext databaseContext = new EzyJpaDatabaseContextBuilder()
    .entityManagerFactory(entityManagerFactory)
    .scan("com.example")
    .build();

This approach is useful when you want to keep your existing JPA configuration and only use EzyData for repository scanning, query conversion, and repository registration.

Notes

datasource.* properties are mapped to HikariCP.
Underscore datasource property names are converted to camelCase.
Hibernate properties should keep their original names.
Auto configuration uses persistence unit name Default.
Manual configuration should scan packages that contain entities, repositories, named queries, and query result classes.
The database name should usually be placed in the JDBC URL.

You can take a look at a list of default functions.

EzyJPA: Configuration