Editing Jakarta Transactions

{{Short description|Jakarta EE specification for transactional resource access}}
The '''Jakarta Transactions''' ('''JTA'''; formerly '''Java Transaction API'''), one of the [[Jakarta EE]] [[application programming interface|API]]s, enables [[distributed transaction]]s to be done across multiple [[X/Open XA]] resources in a [[Java (programming language)|Java]] environment. JTA was a specification developed under the [[Java Community Process]] as JSR 907. JTA provides for:

*demarcation{{Clarify|date=May 2012}} of transaction boundaries
*[[X/Open XA]] API allowing resources to participate in transactions.

==X/Open XA architecture==
{{main article|X/Open XA}}
<!-- Unsourced image removed: [[File:jtaxadiagram.gif|frame|center|{{Deletable image-caption|2007-06-24|date=May 2012}}]] -->
In the X/Open XA architecture, a transaction manager or [[transaction processing monitor]] (TP monitor) coordinates the transactions across multiple resources such as databases and message queues. Each resource has its own resource manager. The resource manager typically has its own API for manipulating the resource, for example the [[Java Database Connectivity|JDBC]] API to work with relational databases. In addition, the resource manager allows a TP monitor to coordinate a distributed transaction between its own and other resource managers. Finally, there is the application which communicates with the TP monitor to begin, [[Commit (data management)|commit]] or [[Rollback (data management)|roll back]] the transactions. The application also communicates with the individual resources using their own API to modify the resource.

==JTA implementation of the X/Open XA architecture==
The JTA API consists of classes in two [[Java package]]s:
* {{Javadoc:EE|package=javax.transaction|javax/transaction}}
* {{Javadoc:EE|package=javax.transaction.xa|javax/transaction/xa}}

The JTA is modelled on the X/Open XA architecture, but it defines two different APIs for demarcating transaction boundaries. It distinguishes between an [[application server]] such as an [[Jakarta Enterprise Beans|EJB]] server and an application component. It provides an interface, {{Javadoc:EE|package=javax.transaction|javax/transaction|TransactionManager}}, that is used by the application server itself to begin, commit and roll back the transactions. It provides a different interface, the {{Javadoc:EE|package=javax.transaction|javax/transaction|UserTransaction}}, that is used by general client code such as a servlet or an EJB to manage the transactions.

The JTA architecture requires that each resource manager must implement the {{Javadoc:EE|package=javax.transaction.xa|javax/transaction/xa|XAResource}} interface in order to be managed by the TP monitor. As stated previously, each resource will have its own specific API, for instance:
* relational databases use JDBC
* messaging services use [[Java Message Service|JMS]]
* generalized EIS ([[Enterprise Information System]]) resources {{Clarify|date=May 2012}} use [[Java EE Connector Architecture|Java EE Connector API]].

==API==
The Jakarta Transactions API consists of three elements: a high-level application transaction demarcation interface, a high-level transaction manager interface intended for an application server, and a standard Java mapping of the X/Open XA protocol intended for a transactional resource manager.

===UserTransaction interface===
The {{Javadoc:EE|package=javax.transaction|javax/transaction|UserTransaction}} interface provides the application the
ability to control transaction boundaries programmatically. This interface may be used
by Java client programs or EJB beans.

The {{Javadoc:EE|javax/transaction|UserTransaction|begin()}} method starts a global transaction and associates the
transaction with the calling thread. The transaction-to-thread association is managed
transparently by the Transaction Manager.

Support for nested transactions is not required. The UserTransaction.begin method
throws the NotSupportedException when the calling thread is already associated
with a transaction and the transaction manager implementation does not support nested
transactions.

Transaction context propagation between application programs is provided by the
underlying transaction manager implementations on the client and server machines.
The transaction context format used for propagation is protocol dependent and must be
negotiated between the client and server hosts. For example, if the transaction manager
is an implementation of the [[Java transaction service|JTS]] specification, it will use the transaction context
propagation format as specified in the CORBA OTS 1.1 specification. Transaction
propagation is transparent to application programs.

===@Transactional annotation===
The {{Javadoc:EE|package=javax.transaction|javax/transaction|Transactional}} annotation provides the application the
ability to control transaction boundaries declaratively. This annotation can be applied to any class that the Jakarta EE specification
defines as a managed bean (which includes CDI managed beans).

The code sample below illustrates the usage of {{java|@Transactional}} in a request scoped CDI managed bean:

<syntaxhighlight lang="java">
@RequestScoped
public class ExampleBean {

    @Transactional
    public void foo() { // A transaction is active here
        
        // Do work

    } // After the method returns transaction is committed or rolled back
}
</syntaxhighlight>

Transactional behavior can be configured via an attribute on the annotation. The available options closely mirror those of the [[EJB#Transactions|EJB]] specification.

===@TransactionScoped annotation===
The {{Javadoc:EE|package=javax.transaction|javax/transaction|TransactionScoped}} annotation provides the application the
ability to declare that the scope during which a bean lives is tied to the time a given transaction is active.

The code sample below illustrates the usage of {{java|@TransactionScoped}} in a request scoped CDI managed bean:

<syntaxhighlight lang="java">

@TransactionScoped
public class TxScopedBean {
    public int number;

    public int getNumber() {return number;}
    public void setNumber(int number) {this.number = number;}
}

@RequestScoped
public class ExampleBean {

    @Inject
    private TxScopedBean txScopedBean;

    @Transactional
    public void foo() {
        txScopedBean.setNumber(1);
    }

    @Transactional
    public void bar() {
        System.out.print(tXscopedBean.getNumber());
    }
}
</syntaxhighlight>

If method ''foo()'' is first called on a managed instance of ExampleBean and then subsequently method ''bar()'' is called, the number printed will be 0 and not 1. This is because each method had its own transaction and therefore its own instance of TxScopedBean. The number 1 that was set during the call to ''foo()'' will therefore not be seen during the call to ''bar()''.

==UserTransaction support in EJB server==
[[EJB]] servers are required to support the {{java|UserTransaction}} interface for use by EJB
beans with the BEAN value in the {{Javadoc:EE|package=javax.ejb|javax/ejb|TransactionManagement}} annotation (this is called bean-managed transactions or BMT). The {{java|UserTransaction}}
interface is exposed to EJB components through either the {{java|EJBContext}} interface using the
{{java|getUserTransaction}} method, or directly via injection using the general <code>@Resource</code> annotation. Thus, an EJB application does not interface with the
Transaction Manager directly for transaction demarcation; instead, the EJB bean relies
on the EJB server to provide support for all of its transaction work as defined in the
Jakarta Enterprise Beans Specification. (The underlying interaction between the EJB
Server and the TM is transparent to the application; the burden of implementing transaction management is on the EJB container and server provider.<ref>[http://cds-esd.sun.com/ESD24/JSCDL/ejb/3.0-fr/ejb-3_0-fr-spec-ejbcore.pdf?AuthParam=1269290256_bf79870723e592b88232b28f0bc403bc&TicketId=B%2Fw2nRyGS1lMTR1LO1BbkAHl&GroupName=CDS&FilePath=/ESD24/JSCDL/ejb/3.0-fr/ejb-3_0-fr-spec-ejbcore.pdf&File=ejb-3_0-fr-spec-ejbcore.pdf JSR 220: Enterprise JavaBeans,Version 3.0, EJB 3.0 Expert Group, Sun Microsystems, 2006]{{dead link|date=July 2017 |bot=InternetArchiveBot |fix-attempted=yes }}</ref>)

The code sample below illustrates the usage of {{java|UserTransaction}} via bean-managed transactions in an EJB session bean:

<syntaxhighlight lang="java">
@Stateless
@TransactionManagement(BEAN)
public class ExampleBean {

    @Resource
    private UserTransaction utx;

    public void foo() {
        // start a transaction
        utx.begin();

        // Do work

        // Commit it
        utx.commit();
    }
}
</syntaxhighlight>

Alternatively, the {{java|UserTransaction}} can be obtained from the {{java|SessionContext}}:

<syntaxhighlight lang="java">
@Stateless
@TransactionManagement(BEAN)
public class ExampleBean {

    @Resource
    private SessionContext ctx;

    public void foo() {
        UserTransaction utx = ctx.getUserTransaction();

        // start a transaction
        utx.begin();

        // Do work

        // Commit it
        utx.commit();
    }
}
</syntaxhighlight>

Note though that in the example above if the <code>@TransactionManagement(BEAN)</code> annotation is omitted, a JTA transaction is automatically started whenever <code>foo()</code> is called and is automatically committed or rolled back when <code>foo()</code> is exited. Making use of a {{java|UserTransaction}} is thus not necessary in EJB programming, but might be needed for very specialized code.

==UserTransaction support in JNDI==
The UserTransaction should be available under <code>java:comp/UserTransaction</code> (if a JTA implementation is installed in the environment).

==See also==
{{Portal|Computer programming}}
* [[Java transaction service]]

==References==
{{Reflist}}

==External links==
* {{Official website}}
* [https://web.archive.org/web/20060212144010/http://jcp.org/en/jsr/detail?id=907 JSR 907]
* [https://web.archive.org/web/20200413132226/https://www.atomikos.com/ Atomikos transaction manager website]
* [https://narayana.io/ Narayana transaction manager website]
* [https://github.com/bitronix/btm Bitronix transaction manager website]

{{Jakarta EE}}

{{DEFAULTSORT:Java Transaction Api}}
[[Category:Transaction processing]]
[[Category:Java enterprise platform|Transaction API]]
[[Category:Java specification requests|Transaction API]]
[[Category:Java APIs]]
[[Category:Articles with example Java code]]