docs/transaction-annotations.adoc

= Transaction Annotations
:index-group: Unrevised
:jbake-date: 2018-12-05
:jbake-type: page
:jbake-status: published


_Also see link:testing-transactions-example.html[Testing Transactions]
for an example of how to use and test EJB transaction attributes_

The _javax.ejb.TransactionAttribute_ annotation (`@TransactionAttribute`)
can be applied to a bean class or it's methods.

Usage of the `@TransactionAttribute` requires you to specify one of six
different transaction attribute types defined via the
javax.ejb.TransactionAttributeType enum.

* TransactionAttributeType._MANDATORY_
* TransactionAttributeType._REQUIRED_
* TransactionAttributeType._REQUIRES_NEW_
* TransactionAttributeType._SUPPORTS_
* TransactionAttributeType._NOT_SUPPORTED_
* TransactionAttributeType._NEVER_

Per EJB 3.0 the default transaction attribute for all EJB 3.0
applications is _REQUIRED_. The default transaction attribute for EJB
2.1, 2.0 and 1.1 applications is vendor specific. In OpenEJB EJB 2.1,
2.0 and 1.1 applications also use _REQUIRED_ as the default.

== Attribute Types summary

A simplistic way to visualize the transaction attributes is as follows.

Failing

Correcting

No Change

Transacted

MANDATORY

REQUIRED, REQUIRES_NEW

SUPPORTS

Not Transacted

NEVER

NOT_SUPPORTED

SUPPORTS

The "_Transacted_" and "_Not Transacted_" categories represent the
container guarantee, i.e. if the bean method will or will not be invoked
in a transaction. The "_Failing_", "_Correcting_", and "_No Change_"
categories represent the action take by the container to achieve that
guarantee.

For example, _Never_ and _Mandatory_ are categorized as "_Failing_" and
will cause the container to throw an exception to the caller if there is
(Tx Never) or is not (Tx Mandatory) a transaction in progress when the
method is called. The attributes _Required_, _RequiresNew_, and
_NotSupported_ are categorized as "_Correcting_" as they will cause the
container to adjust the transactional state automatically as needed to
match the desired state, rather than blocking the invocation by throwing
an exception.

=== Detailed description of each Attribute

==== MANDATORY

A _MANDATORY_ method is guaranteed to always be executed in a
transaction. However, it's the caller's job to take care of suppling the
transaction. If the caller attempts to invoke the method _outside_ of a
transaction, then the container will block the call and throw them an
_exception_.

==== REQUIRED

A _REQUIRED_ method is guaranteed to always be executed in a
transaction. If the caller attempts to invoke the method _outside_ of a
transaction, the container will _start_ a transaction, execute the
method, then _commit_ the transaction.

==== REQUIRES_NEW

A _REQUIRES_NEW_ method is guaranteed to always be executed in a
transaction. If the caller attempts to invoke the method _inside or
outside_ of a transaction, the container will still _start_ a
transaction, execute the method, then _commit_ the transaction. Any
transaction the caller may have in progress will be _suspended_ before
the method execution then _resumed_ afterward.

==== NEVER

A _NEVER_ method is guaranteed to never be executed in a transaction.
However, it's the caller's job to ensure there is no transaction. If the
caller attempts to invoke the method _inside_ of a transaction, then the
container will block the call and throw them an _exception_.

==== NOT_SUPPORTED

A _NOT_SUPPORTED_ method is guaranteed to never be executed in a
transaction. If the caller attempts to invoke the method _inside_ of a
transaction, the container will _suspend_ the caller's transaction,
execute the method, then _resume_ the caller's transaction.

==== SUPPORTS

A _SUPPORTS_ method is guaranteed to adopt the exact transactional state
of the caller. These methods can be invoked by caller's _inside or
outside_ of a transaction. The container will do nothing to change that
state.

== On Methods

[source,java]
----
@Stateless
public static class MyBean implements MyBusinessInterface {

    @TransactionAttribute(TransactionAttributeType.MANDATORY)
    public String codeRed(String s) {
    return s;
    }

    public String codeBlue(String s) {
    return s;
    }
}
----

* _codeRed_ will be invoked with the attribute of _MANDATORY_
* _codeBlue_ will be invoked with the default attribute of _REQUIRED_

== On Classes

[source,java]
----
@Stateless
@TransactionAttribute(TransactionAttributeType.MANDATORY)
public static class MyBean implements MyBusinessInterface {

    public String codeRed(String s) {
    return s;
    }

    public String codeBlue(String s) {
    return s;
    }
}
----

* _codeRed_ and _codeBlue_ will be invoked with the attribute of
_MANDATORY_

== Mixed on classes and methods

[source,java]
----
@Stateless
@TransactionAttribute(TransactionAttributeType.SUPPORTS)
public static class MyBean implements MyBusinessInterface {

    @TransactionAttribute(TransactionAttributeType.NEVER)
    public String codeRed(String s) {
    return s;
    }

    public String codeBlue(String s) {
    return s;
    }

    @TransactionAttribute(TransactionAttributeType.REQUIRED)
    public String codeGreen(String s) {
    return s;
    }
}
----

* _codeRed_ will be invoked with the attribute of _NEVER_
* _codeBlue_ will be invoked with the attribute of _SUPPORTS_
* _codeGreen_ will be invoked with the attribute of _REQUIRED_

= Illegal Usage

Generally, transaction annotationss cannot be made on AroundInvoke
methods and most callbacks.

The following usages of `@TransactionAttribute` have no effect.

[source,java]
----
@Stateful
public class MyStatefulBean implements  MyBusinessInterface  {

    @PostConstruct
    @TransactionAttribute(TransactionAttributeType.NEVER)
    public void constructed(){

    }

    @PreDestroy
    @TransactionAttribute(TransactionAttributeType.NEVER)
    public void destroy(){

    }

    @AroundInvoke
    @TransactionAttribute(TransactionAttributeType.NEVER)
    public Object invoke(InvocationContext invocationContext) throws Exception {
    return invocationContext.proceed();
    }

    @PostActivate
    @TransactionAttribute(TransactionAttributeType.NEVER)
    public void activated(){

    }

    @PrePassivate
    @TransactionAttribute(TransactionAttributeType.NEVER)
    public void passivate(){

    }
}
----