Holon Platform JPA Datastore Module - Reference manual

The JPA Datastore builder API extends the core Datastore builder API, which provides common Datastore configuration settings as listed below.

Example of base JPA Datastore configuration:

The configuration properties can also be provided through an external configuration property source, using the properties provided by the DatastoreConfigProperties property set.

For example, supposing to have a properties file named datastore.properties like this:

We can use it as configuration property source to enable the Datastore tracing mode:

The JPA Datastore implementation relies on the standard JPA EntityManagerFactory API to obtain and manage the EntityManager instances to be used to perform the Datastore operations.

The EntityManagerFactory reference is the only required JPA Datastore configuration attribute and can be provided using the JPA Datastore builder API.

For some internal operations, the JPA Datastore needs to know the ORM platform which manages the concrete EntityManagerFactory (and accorrdingly the EntityManager) instances (for example Hibernate, Eclipselink and so on). The ORM platform is used, for example, to auto-detect the ORM dialect to use if not directly specified at JPA Datastore configuration time.

The ORM platform can be explicitly specified using the JPA Datastore platform builder method, using the ORMPlatform enumeration.

ORM platform auto detection:

When the ORM platform is not explicitly specified, the JPA Datastore will auto-detect it using the configured EntityManagerFactory.

To ensure operations consistency and efficiency, the JPA Datastore uses the ORMDialect API abstraction in order to resolve each ORM platform specificity and JPQL language difference.

Normally, the ORMDialect implementation to use is auto-detected by the JPA Datastore, relying on the ORM platform to which the EntityManagerFactory instance is bound, as described in the previous section.

The ORMDialect implementation to use can be also explicitly configured using the JPA Datastore builder. This can be done in two ways:

1. ORMDialect configuration using the JPA Datastore builder:

The ORM dialect to use can be directly configured using the JPA Datastore builder, either using the dialect(ORMDialect dialect) or the dialect(String dialectClassName) method.

The ORMDialect API provides a static methods to obtain the ORM dialect for a specific ORM platform or to directly obtain a specific dialect implementation within the available ones.

1. ORMDialect configuration using a configuration property:

The ORM dialect to use can be also configured using the default holon.datastore.dialect Datastore configuration property, available from the DatastoreConfigProperties property set.

The fully qualified dialect class name must be provided as property value.

For example, supposing to have a properties file named datastore.properties like this:

We can use it as configuration property source to configure the JPA Datastore dialect:

The Holon JPA Datastore module provides a set of builtin ORM dialects for the most common ORM platforms. The currently available ORM dialect implementations are:

The JPA Datastore API can be configured to automatically flush the persistence context into the concrete persistence source when a data management operation of the Datastore API (such as save or delete) is performed.

When the auto-flush mode is enabled, the EntityManager.flush() operation is invoked just after the Datastore API operation execution, forcing the persistence context synchronization to the underlying database.

The default JPA Datastore strategy to handle the EntityManager lifecycle is defined as follows:

To customize the EntityManager lifecycle, the EntityManagerInitializer and EntityManagerFinalizer interfaces can be used to control the EntityManager instance creation and/or the EntityManager instance finalization for any JPA Datastore API operation.

The EntityManagerInitializer and EntityManagerFinalizer to use can be configured using the JPA Datastore builder API.

By default, the Datastore API relies on the PropertyBox type to represent and handle a set of data model attribute values. For this reason, the PropertyBox type is the default type used in query projections to obtain a set of property values.

The JpaTarget definition can be also used as query projection, to obtain results as JPA entity class instances, instead of PropertyBox type instances.

A new ExpressionResolver can be registered in the JPA Datastore API in two ways:

1. Using the JPA Datastore API instance:

An ExpressionResolver can be registered either using the Datastore builder API at Datastore configuration time:

Or using the Datastore API itself, which extends the ExpressionResolverSupport API:

2. Automatic registration using Java service extensions:

The JPA Datastore supports ExpressionResolver automatic registration using the JpaDatastoreExpressionResolver base type and the default Java service extensions modality.

To automatically register an ExpressionResolver this way, a class implementing JpaDatastoreExpressionResolver has to be created and its fully qualified name must be specified in a file named com.holonplatform.datastore.jpa.config.JpaDatastoreExpressionResolver, placed in the META-INF/services folder in classpath.

When this registration method is used, the expression resolvers defined this way will be registered for any JPA Datastore API instance.

All the default Datastore API operation representations supports operation specific expression resolvers registration, through the ExpressionResolverSupport API.

An ExpressionResolver registered for a specific Datastore API operation execution will be available only for the execution of that operation, and will be ignored by any other Datastore API operation.

For example, to register an expression resolver only for a single Query execution, the Query builder API can be used:

According to the standard convention, the javax.annotation.Priority annotation can be used on ExpressionResolver classes to indicate in what order the expression resolvers bound to the same type resolution pair (i.e. the expression type handled by a resolver and the target expression type into which it will be resolved) must be applied.

The less is the javax.annotation.Priority number assigned to a resolver, the higher will be it’s priority order.

All the default JPA Datastore expression resolvers have the minimum priority order, allowing to override their behavior and resolution strategies with custom expression resolvers with a higher assigned priority order (i.e. a priority number less then Integer.MAX_VALUE).

The internal JPA Datastore JPQL composer engine will perform validation on any Expression instance to resolve and each corresponding resolved Expression instance, using the default expression validate() method.

So the validate() method can be used to implement custom expression validation logic and throw an InvalidExpressionException when validation fails.

Besides the standard Datastore API expressions, such as DataTarget, QueryFilter and QuerySort, which can be used to extend the Datastore API with new expression implementations and new resolution strategies, the JPA Datastore API can be extended using a set of specific JPQL resolution expressions, used by the internal JPQL composer engine to implement the resolution and composition strategy to obtain JPQL statements from the Datastore API meta-language expressions.

These JPQL expression are available from the com.holonplatform.datastore.jpa.jpql.expression package of the holon-datastore-jpa artifact.

The JPQLExpression is the expression which represents an JPQL statement part, used to compose the actual JPQL statement which will be executed using the EntityManager API. So this is the final target expression used by the JPQL composer engine to obtain a JPQL statement part from other, more abstract, expression types.

The JPQLExpression type can be used to directly resolve an abstract Datastore API expression into a JPQL statement part.

For example, supposing to have a KeyIs class which represents a QueryFilter expression type to represent the expression "the key JPA attribute value is equal to a given Long type value":

We want to create an ExpressionResolver class to resolve the KeyIs expression directly into a JPQL WHERE statemet part, using the JPQLExpression type. Using the convenience create method of the ExpressionResolver API, we can do it in the following way:

After the ExpressionResolver is registered in the Datastore API, the new KeyIs expression can be used in the Datastore API operations which support the QueryFilter expression type just like any other filter expression. For example, in a Query expression:

The JPQL composer engine will translate the given KeyIs expression in the JPQL WHERE statement part (alias).key = 1, using the previously defined expression resolver.

Other expression types are used to represent elements of a query or a Datastore operation, to be resolved into a final JPQLExpression type. These expression types often represent an intermediate expression type, between the highest abstract layer (i.e. an expression of the Datastore API meta-language) and the final JPQL statement part representation (i.e. the JPQLExpression type).

Some examples are:

For example, let’s see how the JPQLFunction expression can be used as an intermediate JPQL expression type to define a new JPQL function.

We want to define a Trim function to map the JPQL TRIM(both from x) function.

We will use the QueryFunction expression type to represent the function, since it is the default function expression representation of the Datastore API.

Now we create an expression resolver to resolve the QueryFunction expression into a JPQLFunction intermediate JPQL expression type:

Now the function can be registered in the Datastore API and used the same way as any other QueryFunction expression implementation.

The JPA Datastore API makes available an extension of the standard expression ResolutionContext, to provide a set of configuration attributes and JPQL resolution context specific operations. This resolution context extension is represented by the JPQLResolutionContext API.

When used within the JPA Datastore API, the ResolutionContext provided to the registered expression resolvers is a JPQLResolutionContext for any JPA Datastore API standard operation. To obtain a JPQLResolutionContext, the isJPQLResolutionContext method can be used.

The JPQLStatementResolutionContext API is a further context extension which provides methods related to JPQL statements composition. It can be obtained from a JPQLResolutionContext through the isStatementCompositionContext() method.

The statement resolution context provides methods, for example, to obtain the alias for a property path used in a query.

The EntityManagerFactory bean to be used to configure the JPA Datastore API is obtained as follows:

If a EntityManagerFactory bean definition whith the required name is not present in Spring context, an initialization error is thrown.

When more than one JPA Datastore bean has to be configured using the @EnableJpaDatastore annotation, the dataContextId attribute can be used to assign a different data context id to each JPA Datastore bean definition, in order to:

When a data context id is defined, a Spring qualifier named the same as the data context id will be associated to the generated JPA Datastore bean definitions, and such qualifier can be later used to obtain the right Datastore instance through dependency injection.

Furthermore, the JPA Datastore bean definitions will be named using the data context id as suffix, according to the name pattern: jpaDatastore_{datacontextid}.

The JPA Datastore Auto-flush mode can be configured using the autoFlush attribute of the @EnableJpaDatastore annotation.

The transactional attribute of the @EnableJpaDatastore annotation can be used to control the transactional configuration of a set of the Datastore API operations.

When setted to true, the Spring @Transactional annotation behavior is automatically added to the following Datastore API operation methods:

The default REQUIRED propagation behavior is used, thus allowing the method calls to participate in an existing transaction or to be executed in a new one when the Spring transactions infrastructure is used.

The transactional attribute can be used to disable this default behavior:

The @EnableJpaDatastore annotation provides a primary() attribute which can be used to control the primary mode of the JPA Datastore bean registration.

If the primary mode is set to PrimaryMode.TRUE, the Datastore bean created with the corresponding annotation will be marked as primary in the Spring application context, meaning that will be the one provided by Spring in case of multiple available candidates, when no specific bean name or qualifier is specified in the dependency injection declaration.

By default, the primary mode is set to PrimaryMode.AUTO, meaning that the registred JPA Datastore bean will be marked as primary only when the EntityManagerFactory bean to which is bound is registered as primary candidate bean.

When a JPA Datastore bean is configured using the @EnableJpaDatastore annotation, the Spring environment is automatically used as configuration properties source.

This way, many Datastore configuration settings can be provided using a configuration property with the proper name and value.

The supported configuration properties are:

1. The standard Datastore configuration properties, avaible from the DatastoreConfigProperties property set (See Datastore configuration).

The configuration property prefix is holon.datastore and the following properties are available:

2. An additional set of properties, provided by the JpaDatastoreConfigProperties property set, which can be used as an alternative for the @EnableJpaDatastore annotation attributes described in the previous sections.

Example of Datastore configuration properties:

The JPA Datastore implementation supports the standard Holon Platform Datastore Spring integration features for Datastore beans configuration and extension, which includes:

A DataSource type bean is automatically configured if:

In order to auto-configure the DataSource bean, a suitable set of configuration properties must be available in the Spring Environment.

See the Holon Platform DataSource configuration properties section of the Holon Platform JDBC Module documentation for details.

A Spring LocalContainerEntityManagerFactoryBean instance is used as javax.persistence.EntityManagerFactory implementation to ensure a full integration with Spring JPA architecture and provide functionalities such as automatic JPA persistence unit configuration without the need of a persistence.xml configuration file.

If a persistence.xml configuration file is not available, automatic persistence unit entity classes configuration can be performed using one of the following @EnableJpa annotation attributes:

Two more annotation attributes are available for persistence unit configuration:

By default, the JPA Persistence provider (ORM) to use is auto-detected from classpath and a suitable Spring JpaVendorAdapter instance is configured and bound to the EntityManagerFactory bean.

If more than one persistence provider implementation is present in classpath (or to explicitly specify a persistence provider implementation to use, anyway) the orm configuration property can be used. See JPA configuration properties for details.

A Spring JPA PlatformTransactionManager is auto-configured and bound to the EntityManagerFactory bean to enable the Spring’s transactions support.

A set of attributes are made available by the @EnableJpa annotation to fine tune the transaction manager configuration:

By default, a JPA Datastore implementation is automatically configured using the EntityManagerFactory bean and made available as Spring bean. The JPA Datastore implementation is configured for a seamless integration with the Spring JPA infrastructure, as described in Integration with the Spring JPA infrastructure.

To disable automatic JPA Datastore configuration, the enableDatastore attribute of the @EnableJpa annotation can be used.

The @EnableJpa annotation makes available two additional configuration attributes related to the JPA Datastore implementation setup:

The JpaConfigProperties interface provides a set of configuration properties to be used with JPA stack beans auto-configuration. It extends a default ConfigPropertySet bound to the property name prefix holon.jpa.

The available configuration properties are listed below:

The JpaConfigProperties can be loaded from a number a sources using the default ConfigPropertySet builder interface.

Using the Spring integration, all Environment registered PropertySources will be enabled as a JpaConfigProperties source.

When more than one JPA stack has to be configured using the @EnableJpa annotation, the dataContextId attribute can be used to assign a different data context id to each JPA bean definitions stack, in order to:

When a data context id is defined, a Spring qualifier named the same as the data context id will be associated to each JPA bean definition, and such qualifier can be later used to obtain the right bean instance through dependency injection.

For example, given the following jdbc.properties configuration property source file:

To configure two JPA bean stacks, one bound to the one data context id and the other to the two data context id, the @EnableJpa annotation can be used as follows:

When a JPA Datastore is not istantiated and configured in a Spring context using the @EnableJpaDatastore annotation, but rather providing the bean implementation programmatically (for example using the JpaDatastore builder API), the Spring integration features described in the previous sections must be explicitly enabled:

When more than one JPA beans stack is auto-configured, the JpaEntityScan repeatable annotation can be used to provide the JPA entity set to map to each auto-configured EntityManagerFactory, using the data context id value to identify each EntityManagerFactory bean.

So, for example, given an application.yml configuration file as follows:

Two DataSource beans and two JPA beans stacks will be auto-configured using the one and two data context ids.

The @JpaEntityScan annotation can be used to specify the packages to scan for JPA entity classes mapping, one for the one data context id and another for the two data context id: