Return-Path: X-Original-To: apmail-deltaspike-commits-archive@www.apache.org Delivered-To: apmail-deltaspike-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 2AB95108A6 for ; Mon, 15 Dec 2014 22:31:49 +0000 (UTC) Received: (qmail 67413 invoked by uid 500); 15 Dec 2014 22:31:44 -0000 Delivered-To: apmail-deltaspike-commits-archive@deltaspike.apache.org Received: (qmail 67365 invoked by uid 500); 15 Dec 2014 22:31:44 -0000 Mailing-List: contact commits-help@deltaspike.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@deltaspike.apache.org Delivered-To: mailing list commits@deltaspike.apache.org Received: (qmail 67100 invoked by uid 99); 15 Dec 2014 22:31:43 -0000 Received: from eris.apache.org (HELO hades.apache.org) (140.211.11.105) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 15 Dec 2014 22:31:43 +0000 Received: from hades.apache.org (localhost [127.0.0.1]) by hades.apache.org (ASF Mail Server at hades.apache.org) with ESMTP id B6E61AC0E00 for ; Mon, 15 Dec 2014 22:31:43 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: svn commit: r932889 [4/7] - in /websites/staging/deltaspike/trunk/content: ./ documentation/ Date: Mon, 15 Dec 2014 22:31:43 -0000 To: commits@deltaspike.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20141215223143.B6E61AC0E00@hades.apache.org> Modified: websites/staging/deltaspike/trunk/content/documentation/index.html ============================================================================== --- websites/staging/deltaspike/trunk/content/documentation/index.html (original) +++ websites/staging/deltaspike/trunk/content/documentation/index.html Mon Dec 15 22:31:42 2014 @@ -134,7 +134,7 @@ body { data-target=".nav-collapse"> Apache DeltaSpike + href="http://deltaspike.apache.org/index.html">Apache DeltaSpike []
  • - +
    -
    -

    Introduction

    -
    -
    -

    Apache DeltaSpike project has been created to support the development of -portable CDI extensions that provide useful features for Java -applications not provided out of the box by the CDI spec (Security, JPA, -…​). CDI extensions created by the DeltaSpike community are packaged as -modules.

    -
    -
    -

    Therefore, Apache DeltaSpike is a great toolbox for CDI. More than a set -of powerful extension and tools to ease extension development, -DeltaSpike also proves that CDI allows Java EE to evolve between each -release.

    -
    -
    -

    The goal of the project is also to provide useful classes to :

    -
    +
    +
      +
    • +

      Get Started

      -
      -

      The project is currently tested on different CDI implementations like -Apache OpenWebBeans and JBoss Weld, and also on different Java Web -containers like Apache TomEE or JavaEE, JBoss AS7, Oracle GlassFish -3.1+, Oracle WebLogic Server 12c.

      -
      -
      -

      What is a portable CDI extension ?

      -
      -

      A portable CDI extension means that CDI itself can be extended. Such -extensions can be used with any spec. compliant CDI implementation. From -the user perspective, it means that you can simply drop in CDI extension -jars into your runtime e.g. to integrate third-party APIs with CDI or to -improve existing JavaEE-APIs.

      -
      -
      -

      The CDI Portable extensions SPI (Service Provider Interface) allows to -define additional beans, scopes, stereotypes, interceptors and -decorators. The SPI of CDI is a powerful vehicle for innovation and -DeltaSpike is an example of it.

      -
      -
      -
      -

      DeltaSpike in a nutshell

      -
      -

      Java EE 7 without Java EE 7!

      -
      -

      Transactional support for non-EJB beans: The Transactional Interceptor -in DeltaSpike paved the way for @Transactional in Java EE 7.

      -
      -
      -

      Injectable Servlet objects: Allows the developer to inject CDI beans -on Servlets on Java EE 6/CDI 1.0 environments

      -
      -
      -

      Injectable resources: Configuration, resource bundles,…​ are easy to -inject when using CDI and Apache DeltaSpike.

      -
      -
      -

      @Exclude annotation: it’s possible to annotate beans which should be -ignored by CDI even if they are in a CDI enabled archive on Java EE -6/CDI 1.0 environment where you can’t use @Vetoed or a veto based on -project-stages or expressions is needed.

      -
      -
      -

      Scheduling tasks: Async processes in a non Java EE 7 environment.

      -
      -
      -

      Bean Validation integration: Allows to inject CDI beans and EJB in to -Constraint-Validators.

      -
      -
      -

      BeanProvider: Access the BeanManager and CDI beans even in non managed -classes like JPA-2.0 EntityListeners or Spring Beans.

      -
      -
      -
      -

      JSF Improvements

      -
      -

      Multi-window handling: Allows to manage logical windows for -batches,…​ or in case of JSF it offers proper separation of -browser-tabs.

      -
      -
      -

      Type-safe view-config: It allows to bind meta-data (e.g. for security) -to views with a type-safe, but flexible approach. It provides a more -solid navigation in case of JSF and helps a lot in the maintenance -phase.

      -
      -
      -

      View-Controller: Based on type-safe view-configs view-controller -annotations provide a type-safe alternative to standard-tags.

      -
      -
      -

      Injection on Converters and Validators: Allows to inject CDI beans and -EJB in to JSF Converters and Validators.

      -
      -
      -

      JSF event broadcasting to CDI: Allows CDI to be notified about JSF -events

      -
      -
      -
      -

      Productivity Improvements

      -
      -

      Security based on annotations: The foundation for building a robust, -capable and non invasive security solution.

      -
      -
      -

      New CDI scopes: TransactionScoped, WindowScoped, ViewScoped, -ViewAccess scope, Grouped conversion scope

      -
      -
      -

      Container Control & Test Control: Java SE with CDI, all with a -unifying API. Start, stop, add classes to a running CDI container.

      -
      -
      -

      Data Module: An out of the box entity framework solution complete with -support for container or application managed persistence contexts, as -well as JDBC.

      -
      -
      -

      Decoupled Exception handling: Allows to do exception handling in one -location similar to CDI Observers.

      -
      -
      -

      JMX integration: Any CDI bean can be exposed via JMX easily with one -annotation.

      -
      -
      -

      Type-safe i18n messages: Localized messages are easy to use with an -interface and a resource bundle, no more boilerplate and your messages -now have context within the code.

      -
      -
      -

      Type-safe Project-Stages: Compared to project-stages in JSF, -DeltaSpike provides a type-safe, but still extensible approach which can -be used in CDI based applications.

      -
      -
      -
      -
    -
    -
    -

    Getting Started

    -
    -
    -

    A DeltaSpike project can be designed using or not Apache Maven and -consists in a collection of jar files. Depending on your needs, you will -package DeltaSpike core jar (api and impl) files or extend the list with -DeltaSpike modules. DeltaSpike Api and Impl are mandatory and provide -code required to benefits of portable CDI extensions or useful features -created.

    -
    -
    -

    Remark : For Java SE, an additional step is required as you have to -select the CDI implementation of your choice to boot a CDI container.

    -
    -
    -

    [TODO] Add a section or remark to explain how to package & deploy -DeltaSpike in an OSGI environment (Apache Felix, Apache Karaf, Apache -ServiceMix)

    -
    -
    -

    Project Configuration without Maven

    -
    -

    You can manually download all JARs described above or you get the source-code and build DeltaSpike -manually.

    -
    -
    -
    -

    Project Configuration with Maven

    -
    -

    Hint: In the listings below replace the placeholders for the version with the version of your choice or use:

    -
    -
    -
    -
    <properties>
-    <deltaspike.version>1.2.0</deltaspike.version>
-</properties>
    -
    -
    -
    -

    Or if you want to very bleeding edge, point to our current snapshot.

    -
    -
    -
    -
    <properties>
-    <deltaspike.version>1.2.1-SNAPSHOT</deltaspike.version>
-</properties>
    -
    -
    -
    -

    Configuration of DeltaSpike Core

    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.core</groupId>
-    <artifactId>deltaspike-core-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.core</groupId>
-    <artifactId>deltaspike-core-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -

    Configuration of DeltaSpike Modules

    -
    -
    Security Module
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-security-module-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-security-module-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -
    JPA Module
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-jpa-module-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-jpa-module-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -
    JSF Module
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-jsf-module-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-jsf-module-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -

    Some EE6 servers can’t handle optional classes. If you don’t like the -corresponding log entries during the startup or the deployment fails, -you can use an alternative impl-module (instead of -deltaspike-jsf-module-impl) since v1.0.1:

    -
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-jsf-module-impl-ee6</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -
    Bean Validation Module
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-bean-validation-module-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -
    Servlet Module
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-servlet-module-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-servlet-module-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -
    Data Module
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-data-module-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-data-module-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -
    Test-Control Module
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-test-control-module-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>test</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-test-control-module-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>test</scope>
-</dependency>
    -
    -
    -
    -
    -
    Scheduler Module
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-scheduler-module-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.modules</groupId>
-    <artifactId>deltaspike-scheduler-module-impl</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -
    -

    With Java SE

    -
    -

    To use DeltaSpike with Java SE, we must provide additional jars file -corresponding to the DeltaSpike CDI Controller API and its -implementation. The Controller uses Java Services to resolve the CDI -container -(JBoss -Weld, Apache OpenWebbeans (and -Apache OpenEJB)) and implementation contains -the code to manage the CDI container and contexts.

    -
    -
    -

    Hint: In the listings below replace the placeholders for the version -with the version of your choice or use:

    -
    -
    -
    -
    <properties>
-    <deltaspike.version>1.0.0</deltaspike.version>
-    <owb.version>1.2.0</owb.version>
-    <weld.version>1.1.9.Final</weld.version>
-</properties>
    -
    -
    -
    -
    Add the DeltaSpike Container Ctrl API
    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.cdictrl</groupId>
-    <artifactId>deltaspike-cdictrl-api</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
    -
    -
    -
    -
    -
    Add a CDI container + Container Ctrl Impl
    - -
    -
    -
    -

    …​ for Apache OpenWebBeans

    -
    -
    -
    <dependency>
-    <groupId>org.apache.openwebbeans</groupId>
-    <artifactId>openwebbeans-impl</artifactId>
-    <version>${owb.version}</version>
-    <scope>runtime</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.openwebbeans</groupId>
-    <artifactId>openwebbeans-spi</artifactId>
-    <version>${owb.version}</version>
-    <scope>compile</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.apache.deltaspike.cdictrl</groupId>
-    <artifactId>deltaspike-cdictrl-owb</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -

    …​ for JBoss Weld (RI)

    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.cdictrl</groupId>
-    <artifactId>deltaspike-cdictrl-weld</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>runtime</scope>
-</dependency>
-
-<dependency>
-    <groupId>org.jboss.weld.se</groupId>
-    <artifactId>weld-se-core</artifactId>
-    <version>${weld.version}</version>
-    <scope>runtime</scope>
-</dependency>
    -
    -
    -
    -
    -

    For Embedded Servlet Runtimes, you can add

    -
    -
    -
    <dependency>
-    <groupId>org.apache.deltaspike.cdictrl</groupId>
-    <artifactId>deltaspike-cdictrl-servlet</artifactId>
-    <version>${deltaspike.version}</version>
-    <scope>compile</scope>
-</dependency>
    -
    -
    -
    -
    -

    Testing Snapshots

    -
    -

    If you would like to test the latest Snapshot, you can build DeltaSpike locally or you -get it from the Apache Snapshot-Repository:

    -
    -
    -
    -
    <repositories>
-    <repository>
-        <id>apache-snapshot-repository</id>
-        <url>http://repository.apache.org/snapshots/</url>
-        <releases>
-            <enabled>false</enabled>
-        </releases>
-        <snapshots>
-            <enabled>true</enabled>
-        </snapshots>
-    </repository>
-</repositories>
    -
    -
    -
    -
    -
    -
    -
    -

    Deployment mode

    -
    -
    -

    DeltaSpike can be deployed in different Java environments. Depending -which Java container and release you are using, the procedure which is -different is explained here after.

    -
    -
    -

    With Java EE6+

    -
    -

    If you are using DeltaSpike in a Java EE6 environment, you don’t need to -configure a CDI implementation explicitly because it’s shipped with the -container.

    -
    -
    -
    -

    With Java EE5 or Servlet Containers

    -
    -

    Java EE5 application servers as well as pure servlet containers like -Apache Tomcat / Eclipse Jetty don’t provide a CDI implementation -out-of-the-box. So don’t forget to setup the CDI implementation of your -choice.

    -
    -
    -
    -

    Standard Java SE6+

    -
    -

    If you are only using a JDK and runs Java in a standalone or standard -mode (Java SE), then DeltaSpike will allow you to boot a CDI -implementation where you can use Dependency Injection with a Bean -Manager. Such an example will be presented at the next section.

    -
    -
    -
    -
    -
    -

    Start a CDI container using Java SE

    -
    -
    -

    This code snippet show you how with a Java MainApplication a CDI -container can be started (= boot) by DeltaSpike using Java SE and how -you define a CDI scope and resolve beans injected.

    -
    -
    -

    Hint: To bootstrap a CDI container in your Java application, you -just need to instantiate the CdiContainer and call the #boot method.

    -
    -
    -
    -
    import org.apache.deltaspike.cdise.api.CdiContainer;
-import org.apache.deltaspike.cdise.api.CdiContainerLoader;
-
-public class MainApp {
-    public static void main(String[] args) {
-
-        CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
-        cdiContainer.boot();
-
-        // You can use CDI here
-
-        cdiContainer.shutdown();
-    }
-}
    -
    -
    -
    -

    When #boot is called, the CdiContainer will scan CDI enabled -archives for beans and CDI extensions.

    -
    -
    -

    Note: Booting the container does not automatically start all CDI -Contexts!

    -
    -
    -

    Example for starting the application-context:

    -
    -
    -
    -
    import org.apache.deltaspike.cdise.api.CdiContainer;
-import org.apache.deltaspike.cdise.api.CdiContainerLoader;
-import org.apache.deltaspike.cdise.api.ContextControl;
-import javax.enterprise.context.ApplicationScoped;
-
-public class MainApp {
-    public static void main(String[] args) {
-
-        CdiContainer cdiContainer = CdiContainerLoader.getCdiContainer();
-        cdiContainer.boot();
-
-        // Starting the application-context allows to use @ApplicationScoped beans
-        ContextControl contextControl = cdiContainer.getContextControl();
-        contextControl.startContext(ApplicationScoped.class);
-
-        // You can use CDI here
-
-        cdiContainer.shutdown();
-    }
-}
    -
    -
    -
    -

    To resolve a bean of this project, you can use the BeanProvider -provided by DeltaSpike. The following example shows how to resolve the a -bean without qualifiers. It depends on the application if EchoService -is a concrete implementation or just an interface. In case of an -interface the corresponding implementation will be resolved. The -resolved bean is a normal CDI bean which means you can use all CDI -concepts like @Inject in the class (and you don’t need further usages -of BeanProvider).

    -
    -
    -
    -
    EchoService echoService = BeanProvider.getContextualReference(EchoService.class, false);
    -
    -
    -
    -

    Before the application exits, you have to call #shutdown to destroy -beans,…​ in a well-ordered fashion.

    -
    -
    -
    -
    -

    Module Overview

    -
    -
    -

    The core features of DeltaSpike project are packaged under the following -different modules. Some of them are mandatory while others are optional.

    -
    -
    -

    Core (required)

    -
    -

    Definition : Contain the API and util classes of DeltaSpike project

    -
    -View details » -
    -
    -

    Security (optional)

    -
    -

    Definition : Intercept and check security

    -
    -View details » -
    -
    -

    JPA (optional)

    -
    -

    Definition :

    -
    -View details » -
    -
    -

    JSF (optional)

    -
    -

    Definition :

    -
    -View details » -
    -
    -

    Container Control (optional)

    -
    -

    Definition :

    -
    -View details » -
    -
    -

    Bean Validation (optional)

    -
    -

    Definition : A module for adding CDI support in Bean Validation.

    -
    -
    -

    Features : Allows a developer to create CDI aware `ConstraintValidator`s -that can use business objects (EJBs, ManagedBeans) to support validation -needs.

    -
    -View details » -
    -
    -

    Servlet (optional)

    -
    -

    Definition : The DeltaSpike Servlet module provides integration with the -Java Servlet API.

    -
    -
    -

    Features :

    -
    +
    • +
  • +

    Use Individual Modules

    -
    -View details » -
-
-

Partial-Bean (optional)

-View details » -
-
-

Data (optional)

-
-

Definition : The DeltaSpike Data module provides enhanced JPA experience -with declarative queries, reducing boilerplate to a minimum.

-
-
-

Features :

-
-
-
  • -

    Derive queries by simple method names or by method annotations -defining JPQL, named queries or plain SQL

    +

    Bean Validation

  • -

    Result pagination and sorting

    +

    Container Control

  • -

    Auditing of entities

    +

    Data

  • -

    A simplified alternative to the Criteria API

    +

    JPA

  • -

    Mapping of entities from and to DTOs

    +

    JSF

    +
    • +
  • +

    Partial-Bean

    +
    • +
  • +

    Scheduler

    • -
-
-View details » -
-
-

Test-Control (optional)

-
-

Definition : This module allows to write CDI based tests easily.

-
-View details » -
-
-

Scheduler (optional)

-
-

Definition : This module provides a simple integration with Quartz v2 -(per default) or any other scheduler which supports cron-expressions for -job-classes.

-
-View details » -
- - -
-

DeltaSpike SPI

-
-
-

DeltaSpike Service Provider Interface (SPI)

-
-View details » -
-
-
-

External

-
-
-

Blogs

-
-
-
-
-

Add-ons

+ +
  • +

    Advanced Information

    -
    • -
    -

    Project Templates

    + +
  • +

    Access More DeltaSpike Resources

    -
    • -
    -

    Examples

    -
    -

    See External Examples

    -
    -
    -
    + +
    Modified: websites/staging/deltaspike/trunk/content/documentation/jpa.html ============================================================================== --- websites/staging/deltaspike/trunk/content/documentation/jpa.html (original) +++ websites/staging/deltaspike/trunk/content/documentation/jpa.html Mon Dec 15 22:31:42 2014 @@ -134,7 +134,7 @@ body { data-target=".nav-collapse"> Apache DeltaSpike + href="http://deltaspike.apache.org/index.html">Apache DeltaSpike []
    • -

      @Transactional

      +

      Overview

      -

      This annotation is an alternative to transactional EJBs which allows to -execute a method within a transaction. Before it’s possible to start -using the annotation, it’s required to implement a CDI producer for an -EntityManager and it’s needed to inject the EntityManager in the -bean which uses @Transactional. As shown later on it’s also possible -to use multiple qualifiers for using different `EntityManager`s.

      +

      The JPA module provides a transactional context and scope, enabling execution of methods within transactions.

      +
      +
      +
      +
      +

      Configure Your Projects

      +
      +
      +

      The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in Configure DeltaSpike in Your Projects. For Maven-independent projects, see Configure DeltaSpike in Maven-independent Projects.

      +
      +
      +

      1. Declare JPA Module Dependencies

      +
      +

      Add the JPA module to the list of dependencies in the project pom.xml file using this code snippet:

      +
      +
      +
      +
      <dependency>
+    <groupId>org.apache.deltaspike.modules</groupId>
+    <artifactId>deltaspike-jpa-module-api</artifactId>
+    <version>${deltaspike.version}</version>
+    <scope>compile</scope>
+</dependency>
+
+<dependency>
+    <groupId>org.apache.deltaspike.modules</groupId>
+    <artifactId>deltaspike-jpa-module-impl</artifactId>
+    <version>${deltaspike.version}</version>
+    <scope>runtime</scope>
+</dependency>
      +
      +
      +
      +

      2. Enable the Transaction Interceptor

      -

      Hint: If you are using features described by this page with CDI 1.0 -(or DeltaSpike up to v1.1.0 with CDI 1.1+), you have -to enable the transaction interceptor in your beans.xml file:

      +

      For CDI 1.0 (or DeltaSpike v1.1.0 and earlier together with CDI 1.1+), you must enable the transaction interceptor in the project beans.xml file:

      @@ -202,17 +239,31 @@ to enable the transaction interceptor in </beans>
      +
      +
      +
      +
      +

      Use the Module Features

      +
      +
      +

      @Transactional

      +
      +

      This annotation is an alternative to transactional EJBs which allows to +execute a method within a transaction. Before it is possible to start +using the annotation, it is required to implement a CDI producer for an +EntityManager and it is needed to inject the EntityManager in the +bean which uses @Transactional. As shown later on, it is also possible +to use multiple qualifiers for using different `EntityManager`s.

      +

      The following example shows a simple producer for an EntityManager and the corresponding dispose-method. Producing it as request scoped bean means that the dispose method will be called on finishing the request. -As an alternative it’s possible to use a special scope called +As an alternative it is possible to use a special scope called @TransactionScoped provided by the same DeltaSpike module.

      -
      -

      Producer for the default EntityManager (no EE-Server):

      -
      +
      Producer for the Default EntityManager (no EE-Server)
      //...
 public class EntityManagerProducer
@@ -238,10 +289,8 @@ As an alternative it’s possible to
 }
      -
      -

      Producer for the default EntityManager (EE-Server):

      -
      +
      Producer for the Default EntityManager (EE-Server)
      @ApplicationScoped
 public class EntityManagerProducer
@@ -271,10 +320,8 @@ As an alternative it’s possible to
 
      The following examples show how to use the EntityManager produced by
 the example above.
      -
      -

      Beans with transactional method:

      -
      +
      Beans with Transactional Method
      //...
 public class TransactionalBean
@@ -290,10 +337,8 @@ the example above.
      
 }
      -
      -

      Simple transactional bean (all methods transactional):

      -
      +
      Simple Transactional Bean (All Methods are Transactional)
      //...
 @Transactional
@@ -307,13 +352,11 @@ the example above.
      -

      As illustrated in the following example it’s also possible to use +

      As illustrated in the following example it is also possible to use @Transactional for stereotypes.

      -
      -

      Stereotype for transactional beans (+ usage):

      -
      +
      Stereotype for Transactional Beans (+ Usage)
      @Stereotype
 @Transactional
@@ -334,16 +377,14 @@ the example above.
      -

      Besides such simple usages, it’s also supported to use qualifiers to +

      Besides such simple usages, it is also supported to use qualifiers to access multiple persistence-units in parallel. The default qualifier for @Transactional is @Any. Therefore a transaction for every injected entity manager will be started. The example afterwards shows how to change this default behaviour.

      -
      -

      Producer for multiple entity managers (+ usage):

      -
      +
      Producer for Multiple Entity Managers (+ Usage)
      //...
 public class EntityManagerProducer
@@ -422,10 +463,8 @@ change this default behaviour.
      
 
      The following example shows how to use only the specified
 EntityManager/s
      -
      -

      Activating entity managers manually:

      -
      +
      Activating Entity Managers Manually
      public class MultiTransactionBean
 {
@@ -465,10 +504,8 @@ change this default behaviour.
      
 transaction handling is done on the entry point (after
 FirstLevelTransactionBean#executeInTransaction).
      -
      -

      Joining existing transaction in nested call:

      -
      +
      Joining Existing Transaction in Nested Call
      //...
 public class FirstLevelTransactionBean
@@ -503,15 +540,13 @@ FirstLevelTransactionBean#executeInTrans
 
      
 
      The final transaction handling for all EntityManager s is also done
 after the outermost transactional method if NestedTransactionBean uses
-a different EntityManager. So it’s possible to catch an exception in
-FirstLevelTransactionBean e.g. to try an optional path instead of an
+a different EntityManager. So it is possible to catch an exception in
+FirstLevelTransactionBean, for example, to try an optional path instead of an
 immediate rollback.
      -
      -
      -

      @TransactionScoped

      -
      +
      +

      @TransactionScoped

      @Transactional also starts a context which is available as long as the transaction started by @Transactional. Besides other beans you can use @@ -520,8 +555,8 @@ this scope for the EntityManager@Transactional.

      -

      Producer for the default EntityManager which should be used only for one -transaction:

      +
      Producer for the Default EntityManager which should be Used Only for One
      +

      Transaction

      @@ -550,46 +585,39 @@ transaction:

      -
      -
      -

      Extended Persistence Contexts

      -
      +
      +

      Extended Persistence Contexts

      Frameworks like MyFaces Orchestra provide a feature which allows keeping -an EntityManager across multiple requests. That means it isn’t +an EntityManager across multiple requests. That means it is not required to call EntityManager#merge to add detached entities to the -context. However, several application architectures don’t allow such an +context. However, several application architectures do not allow such an approach (due to different reasons like scalability). In theory that sounds nice and it works pretty well for small to medium sized projects -esp. if an application doesn’t rely on session replication in clusters. +especially if an application does not rely on session replication in clusters. That also means that such an approach restricts your target environment from the very beginning. One of the base problems is that an -EntityManager isn’t serializable. Beans which are scoped in a +EntityManager is not serializable. Beans which are scoped in a normal-scoped CDI context have to be serializable. So by default it -isn’t allowed by CDI to provide a producer-method which exposes e.g. a -conversation scoped EntityManager as it is. We don’t recommend to -use this approach and therefore it isn’t available out-of-the-box. +is not allowed by CDI to provide a producer-method which exposes, for example, a +conversation scoped EntityManager as it is. We do not recommend this approach and therefore it is not available out-of-the-box. However, if you really need this approach to avoid calling #merge for -your detached entities, it’s pretty simple to add this functionality.

      -
      -
      -

      Usage of a simple ExtendedEntityManager

      +your detached entities, it is pretty simple to add this functionality.

      +
      Usage of a Simple ExtendedEntityManager
      @Inject
 private EntityManager entityManager;
      -

      As you see the usage is the same. You don’t have to use -ExtendedEntityManager at the injection point. It’s just needed in the +

      As you see the usage is the same. You do not have to use +ExtendedEntityManager at the injection point. It is just needed in the producer-method:

      -
      -

      Producer for the default Extended-EntityManager (no EE-Server):

      -
      +
      Producer for the Default Extended-EntityManager (no EE-Server)
      //...
 public class ExtendedEntityManagerProducer
@@ -615,10 +643,8 @@ producer-method:
      
 }
      -
      -

      Producer for the default Extended-EntityManager (EE-Server):

      -
      +
      Producer for the Default Extended-EntityManager (EE-Server)
      @ApplicationScoped
 public class ExtendedEntityManagerProducer
@@ -644,10 +670,8 @@ producer-method:
      
 }
      -
      -

      Implementation of a simple ExtendedEntityManager:

      -
      +
      Implementation of a Simple ExtendedEntityManager
      @Typed()
 public class ExtendedEntityManager implements EntityManager, Serializable
@@ -673,26 +697,24 @@ producer-method:
      -

      This approach just works if it doesn’t come to serialization of this -wrapper e.g. in case of session-replication. If those beans get +

      This approach just works if it does not come to serialization of this +wrapper, for example in case of session-replication. If those beans get serialized, you have to overcome this restriction by storing the persistence-unit-name and recreate the EntityManager via Persistence.createEntityManagerFactory(this.persistenceUnitName).createEntityManager(); and sync it with the database before closing it on serialization. Furthermore, you have to intercept some methods of the EntityManager to merge detached entities automatically if those entities get -serialized as well. However, as mentioned before we don’t recommend +serialized as well. However, as mentioned before we do not recommend such an approach.

      -
      -
      -

      JTA Support

      -
      +
      +

      JTA Support

      -

      Per default the transaction-type used by @Transactional`is -'RESOURCE_LOCAL'. If you configure `transaction-type="JTA"`in the -persistence.xml, you have to enable an alternative `TransactionStrategy +

      By default the transaction-type used by @Transactional is +RESOURCE_LOCAL. If you configure transaction-type="JTA" in the +persistence.xml file, you have to enable an alternative TransactionStrategy in the beans.xml which is called org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy.

      @@ -712,15 +734,23 @@ than the production settings, you can us org.apache.deltaspike.jpa.impl.transaction.EnvironmentAwareTransactionStrategy instead.

      -
      -

      Hint:

      -
      -
      -

      In case of some versions of Weld (or OpenWebBeans in BDA mode), you have +

      + + + + + +
      +
      Note
      +      		 +In case of some versions of Weld (or OpenWebBeans in BDA mode), you have to configure it as global-alternative instead of an <alternatives> in -beans.xml. That means you have to add e.g.: -globalAlternatives.org.apache.deltaspike.jpa.spi.transaction.TransactionStrategy=org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy -to /META-INF/apache-deltaspike.properties

      +beans.xml. That means you have to add, for example, +globalAlternatives.org.apache.deltaspike.jpa.spi.transaction.TransactionStrategy +=org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy +to /META-INF/apache-deltaspike.properties +
      +