com.holonplatform.jpa.spring

## Annotation Type EnableJpa

-     @Target(value=TYPE)
       @Retention(value=RUNTIME)
       @Documented
       @Inherited
       @Import(value=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.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.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.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.DatastoreOperations.WriteOption...)`
      - `Datastore.update(com.holonplatform.core.datastore.DataTarget, com.holonplatform.core.property.PropertyBox, com.holonplatform.core.datastore.DatastoreOperations.WriteOption...)`
      - `Datastore.save(com.holonplatform.core.datastore.DataTarget, com.holonplatform.core.property.PropertyBox, com.holonplatform.core.datastore.DatastoreOperations.WriteOption...)`
      - `Datastore.delete(com.holonplatform.core.datastore.DataTarget, com.holonplatform.core.property.PropertyBox, com.holonplatform.core.datastore.DatastoreOperations.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

Copyright © 2019 The Holon Platform. All rights reserved.