com.holonplatform.jpa.spring

Annotation Type EnableJpa

@Target(value=TYPE)
 @Retention(value=RUNTIME)
 @Documented
 @Inherited
 @Import(value=com.holonplatform.jpa.spring.internal.JpaRegistrar.class)
public @interface EnableJpa

Annotation to be used on Spring Configuration classes to setup a full JPA enviroment bean stack: DataSource (if not already available in Spring context), EntityManagerFactory and PlatformTransactionManager.

If a DataSource is not available in Spring context, a DataSource instance will be automatically configured using external configuration properties according to DataSourceConfigProperties.

A data context id can be specified using dataContextId(), to discriminate configuration properties using given id as property prefix, and setting data context id as Spring bean qualifier to allow bean injection when multiple JPA beans stack instances are registered in context, for example using Qualifier annotation.

When a data context id is specified, configuration properties must be written using that id as prefix, for example, if data context id is myid:
holon.datasource.myid.url=...

In case of multiple data context ids, primary() or the external property SpringDataSourceConfigProperties.PRIMARY can be used to mark one of the JPA beans stack as primary candidate for dependency injection when a qualifier is not specified.

If enableDatastore() is true (default value), a JpaDatastore bean will be configured and registered in Spring Application Context, using a shared EntityManager obtained using this JPA stack.

Since:

5.0.0

Field Summary

Fields

Modifier and Type	Fields and Description
static String	DEFAULT_ENTITYMANAGERFACTORY_BEAN_NAME Default EntityManagerFactory registration bean name

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	autoFlush Get whether to enable the JPA datastore auto-flush mode.
String	dataContextId Bind JPA beans stack to given data context id.
String	dataSourceReference Configures the name of the DataSource bean definition to be used to create the JPA EntityManagerFactory bean definition registered using this annotation.
int	defaultTimeout Specify the default timeout that this transaction manager should apply if there is no timeout specified at the transaction level, in seconds.
boolean	enableDatastore Whether to create a JpaDatastore bound to the EntityManagerFactory created and registered using this annotation.
Class<?>[]	entityPackageClasses Type-safe alternative to entityPackages() for specifying the packages to scan to map JPA Entity classes into EntityManagerFactory.
String[]	entityPackages Package names to scan to map JPA Entity classes into EntityManagerFactory.
boolean	failEarlyOnGlobalRollbackOnly Set whether to fail early in case of the transaction being globally marked as rollback-only.
com.holonplatform.spring.internal.PrimaryMode	primary Whether to qualify registered JPA beans as primary, i.e. the preferential bean to be injected in a single-valued dependency when multiple candidates are present.
boolean	rollbackOnCommitFailure Set whether doRollback should be performed on failure of the doCommit call.
javax.persistence.SharedCacheMode	sharedCacheMode Specify the JPA 2.0 shared cache mode for this persistence unit.
boolean	transactionalDatastore If enableDatastore() is true, get whether to add Transactional behaviour to transactional Datastore methods, to automatically create or partecipate in a transaction when methods are invoked.
int	transactionSynchronization Set when this transaction manager should activate the thread-bound transaction synchronization support.
boolean	validateExistingTransaction Set whether existing transactions should be validated before participating in them.
javax.persistence.ValidationMode	validationMode Specify the JPA 2.0 validation mode for this persistence unit.

Field Detail

DEFAULT_ENTITYMANAGERFACTORY_BEAN_NAME

public static final String DEFAULT_ENTITYMANAGERFACTORY_BEAN_NAME

Default EntityManagerFactory registration bean name

Element Detail

dataContextId

public abstract String dataContextId

Bind JPA beans stack to given data context id.

The data context id will be used as JPA stack beans qualifier, allowing persistence sources discrimination in case of multiple data sources. You must ensure different data context ids are used when configuring multiple data sources using this annotation.

This id will be setted as JPA persistence unit name too.

Returns:

Data context id

Default:

""

primary

public abstract com.holonplatform.spring.internal.PrimaryMode primary

Whether to qualify registered JPA beans as primary, i.e. the preferential bean to be injected in a single-valued dependency when multiple candidates are present.

When mode is PrimaryMode.AUTO, the registered beans are marked as primary only when the DataSource bean to which JPA stack is bound is registered as primary bean.

Returns:

Primary mode, defaults to PrimaryMode.AUTO

Default:

com.holonplatform.spring.internal.PrimaryMode.AUTO

dataSourceReference

public abstract String dataSourceReference

Configures the name of the DataSource bean definition to be used to create the JPA EntityManagerFactory bean definition registered using this annotation. See dataContextId() for informations about DataSource bean lookup when a specific name is not configured.

If the DataSource reference is not configured and no registered DataSource bean with consistent name is found in context, a new DataSource instance is configured and registered using DataSourceConfigProperties configuration properties.

Returns:

The name of the DataSource bean definition to be used to create the JPA EntityManagerFactory

Default:

""

enableDatastore

public abstract boolean enableDatastore

Whether to create a JpaDatastore bound to the EntityManagerFactory created and registered using this annotation.

Defaults to true.

Returns:

True to create a JPA Datastore bean bound to the EntityManagerFactory created and registered using this annotation

Default:

true

autoFlush

public abstract boolean autoFlush

Get whether to enable the JPA datastore auto-flush mode. When auto-flush mode is enabled, EntityManager.flush() is called after each Datastore data manipulation operation, such as save or delete operations.

Default is false.

This attribute is ignored is enableDatastore() is false.

Returns:

true to enable the auto-flush mode, false to disable

Default:

false

transactionalDatastore

public abstract boolean transactionalDatastore

If enableDatastore() is true, get whether to add Transactional behaviour to transactional Datastore methods, to automatically create or partecipate in a transaction when methods are invoked. Affected methods are:

• Datastore.refresh(com.holonplatform.core.datastore.DataTarget, com.holonplatform.core.property.PropertyBox)
• Datastore.insert(com.holonplatform.core.datastore.DataTarget, com.holonplatform.core.property.PropertyBox, com.holonplatform.core.datastore.Datastore.WriteOption...)
• Datastore.update(com.holonplatform.core.datastore.DataTarget, com.holonplatform.core.property.PropertyBox, com.holonplatform.core.datastore.Datastore.WriteOption...)
• Datastore.save(com.holonplatform.core.datastore.DataTarget, com.holonplatform.core.property.PropertyBox, com.holonplatform.core.datastore.Datastore.WriteOption...)
• Datastore.delete(com.holonplatform.core.datastore.DataTarget, com.holonplatform.core.property.PropertyBox, com.holonplatform.core.datastore.Datastore.WriteOption...)

Returns:

Whether to add Transactional behaviour to transactional datastore methods. Defaults to true.

Default:

true

entityPackages

public abstract String[] entityPackages

Package names to scan to map JPA Entity classes into EntityManagerFactory. If none specified, standard persistence.xml file will be used as mappings source.

Returns:

package names to scan to map JPA Entity classes

Default:

{}

entityPackageClasses

public abstract Class<?>[] entityPackageClasses

Type-safe alternative to entityPackages() for specifying the packages to scan to map JPA Entity classes into EntityManagerFactory. The package of each class specified will be scanned.

Consider creating a special no-op marker class or interface in each package that serves no purpose other than being referenced by this attribute.

Returns:

classes from which to obtain package names to scan

Default:

{}

validationMode

public abstract javax.persistence.ValidationMode validationMode

Specify the JPA 2.0 validation mode for this persistence unit.

Returns:

Validation mode

Default:

javax.persistence.ValidationMode.AUTO

sharedCacheMode

public abstract javax.persistence.SharedCacheMode sharedCacheMode

Specify the JPA 2.0 shared cache mode for this persistence unit.

Returns:

Shared cache mode

Default:

javax.persistence.SharedCacheMode.UNSPECIFIED

transactionSynchronization

public abstract int transactionSynchronization

Set when this transaction manager should activate the thread-bound transaction synchronization support. Default is "always".

Note that transaction synchronization isn't supported for multiple concurrent transactions by different transaction managers. Only one transaction manager is allowed to activate it at any time.

Returns:

Transaction synchronization mode, or -1 for default

See Also:

AbstractPlatformTransactionManager.SYNCHRONIZATION_ALWAYS, AbstractPlatformTransactionManager.SYNCHRONIZATION_ON_ACTUAL_TRANSACTION, AbstractPlatformTransactionManager.SYNCHRONIZATION_NEVER

Default:

-1

defaultTimeout

public abstract int defaultTimeout

Specify the default timeout that this transaction manager should apply if there is no timeout specified at the transaction level, in seconds.

Default is the underlying transaction infrastructure's default timeout, e.g. typically 30 seconds in case of a JTA provider, indicated by the TransactionDefinition.TIMEOUT_DEFAULT value.

Returns:

Default timeout in seconds or -1 for default

Default:

-1

validateExistingTransaction

public abstract boolean validateExistingTransaction

Set whether existing transactions should be validated before participating in them.

When participating in an existing transaction (e.g. with PROPAGATION_REQUIRES or PROPAGATION_SUPPORTS encountering an existing transaction), this outer transaction's characteristics will apply even to the inner transaction scope. Validation will detect incompatible isolation level and read-only settings on the inner transaction definition and reject participation accordingly through throwing a corresponding exception.

Default is "false", leniently ignoring inner transaction settings, simply overriding them with the outer transaction's characteristics. Switch this flag to "true" in order to enforce strict validation.

Returns:

True to enable existing transactions validation

Default:

false

failEarlyOnGlobalRollbackOnly

public abstract boolean failEarlyOnGlobalRollbackOnly

Set whether to fail early in case of the transaction being globally marked as rollback-only.

Default is "false", only causing an UnexpectedRollbackException at the outermost transaction boundary. Switch this flag on to cause an UnexpectedRollbackException as early as the global rollback-only marker has been first detected, even from within an inner transaction boundary.

Note that, as of Spring 2.0, the fail-early behavior for global rollback-only markers has been unified: All transaction managers will by default only cause UnexpectedRollbackException at the outermost transaction boundary. This allows, for example, to continue unit tests even after an operation failed and the transaction will never be completed. All transaction managers will only fail earlier if this flag has explicitly been set to "true".

Returns:

True to set early fail

Default:

false

rollbackOnCommitFailure

public abstract boolean rollbackOnCommitFailure

Set whether doRollback should be performed on failure of the doCommit call. Typically not necessary and thus to be avoided, as it can potentially override the commit exception with a subsequent rollback exception.

Default is "false".

Returns:

True to activate

Default:

false