///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2019, 2020 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

= Helidon MP JTA Guide
:description: Helidon MP JTA Guide
:keywords: helidon, guide, transaction, jta, microprofile

This guide shows how to configure and use
https://www.jcp.org/en/jsr/detail?id=907[Java Transaction API
(JTA)]-compliant transactions in your Helidon MP application.

== What You Need

|===
|About 10 minutes
|<<about/03_prerequisites.adoc,Helidon Prerequisites>>
|===

== Add The Helidon JTA Integration to Your Helidon MP Application's Runtime Classpath

To bring JTA transactions to your Helidon MP application, you'll need
to add the relevant extension.  Specifically, you'll need to add an
appropriate `<dependency>` element as a child element of the
`<dependencies>` element in your `pom.xml`, referencing the Helidon
JTA extension:

[source,xml]
----
<dependency>
    <groupId>io.helidon.integrations.cdi</groupId>
    <artifactId>helidon-integrations-cdi-jta-weld</artifactId>
    <version>{helidon-version}</version>
    <scope>runtime</scope> <!--1-->
</dependency>
----

<1> Note the scope is `runtime`.

== Add JTA to Your Helidon MP Application's Compilation Classpath

To actually use the Java Transaction API in your code, you'll need to
ensure a library defining the classes and interfaces mandated by the
specification is present on your compilation classpath.  (Note that
this library is separate from any given vendor's actual implementation
of the specification by way of these classes and interfaces.)

[source,xml]
----
<dependency>
    <groupId>javax.transaction</groupId>
    <artifactId>javax.transaction-api</artifactId>
    <version>1.2</version>
    <scope>provided</scope> <!--1-->
</dependency>
----

<1> The scope is `provided` to allow the JTA implementation runtime to
provide its own implementation of the API jar if necessary.

== Annotate a Method With https://javaee.github.io/javaee-spec/javadocs/javax/transaction/Transactional.html[`@Transactional`]

Choose a method that you wish to have a certain kind of transactional
behavior, and annotate it with the
https://javaee.github.io/javaee-spec/javadocs/javax/transaction/Transactional.html[`@Transactional`]
annotation.

The method in question will need to be a business method of some kind:
a method that is invoked by the Helidon MP server machinery, not
directly by the user.  This is because normally the behavior that
`@Transactional` requests is provided by interceptor functionality.
More concretely, in Helidon MP you can annotate a
https://javaee.github.io/tutorial/jaxrs002.html#GILQB[JAX-RS resource
method], or a method on a CDI bean that itself is injected in your
application somewhere.

For example, a method on a hypothetical `PersonDAO` class that saves a
hypothetical `Person` object to a database, starting a new JTA
transaction if necessary, might look like this:

[source,java]
.`PersonDAO.java`
----
import javax.transaction.Transactional;
import javax.transaction.Transactional.TxType;

@Transactional(TxType.REQUIRED) <1>
public void savePerson(Person person) {
    // Use JPA or another JTA-aware framework to save the Person object <2>
}
----

<1> The `Transactional` annotation indicates the kind of transactional
behavior you would like this method to have.  In this example, we
explicitly set the kind of behavior to be
https://javaee.github.io/javaee-spec/javadocs/javax/transaction/Transactional.TxType.html#REQUIRED[`REQUIRED`]
(which also happens to be the default if you do not specify an
explicit
https://javaee.github.io/javaee-spec/javadocs/javax/transaction/Transactional.TxType.html[`TxType`]).

<2> Annotating a method with `@Transactional` demarcates a JTA
transaction, but it is up to individual JTA-aware frameworks and
libraries to actually do something when the transaction is implicitly
started.  JPA is an example of a framework that is JTA aware.

