This chapter describes the required Jakarta Enterprise Edition (Jakarta EE) transaction management and runtime environment.
Product Providers must transparently support transactions that involve multiple components and transactional resources within a single Jakarta EE product, as described in this chapter. This requirement must be met regardless of whether the Jakarta EE product is implemented as a single process, multiple processes on the same network node, or multiple processes on multiple network nodes.
If the following components are included in a Jakarta EE product, they are considered transactional resources and must behave as specified here:
-
JDBC connections
-
Jakarta Messaging sessions
-
Resource adapter connections for resource adapters specifying the XATransaction transaction level
A Jakarta EE Product that includes both a servlet container and an enterprise bean container must support a transactional application comprised of combinations of web application components accessing multiple enterprise beans within a single transaction. If the Jakarta EE product also includes support for the Connectors specification, each component may also acquire one or more connections to access one or more transactional resource managers.
For example, in Servlets/Server Pages Accessing Enterprise Beans , the call tree starts from a servlet or server pages accessing multiple enterprise beans, which in turn may access other enterprise beans. The components access resource managers via connections.
The Application Component Provider specifies, using a combination of programmatic and declarative transaction demarcation APIs, how the platform must manage transactions on behalf of the application.
For example, the application may require that all the components in Servlets/Server Pages Accessing Enterprise Beans access resources as part of a single transaction. The Platform Provider must provide the transaction capabilities to support such a scenario.
This specification does not define how the components and the resources are partitioned or distributed within a single Jakarta EE product. In order to achieve the transactional semantics required by the application, the Jakarta EE Product Provider is free to execute the application components sharing a transaction in the same Java virtual machine, or distribute them across multiple virtual machines, in accordance with the requirements of the component specifications.
The rest of this chapter describes the transactional requirements for a Jakarta EE product in more detail.
This section defines the transaction support requirements of Jakarta EE Products that must be supported by Product Providers.
Web components may demarcate transactions using the jakarta.transaction.UserTransaction interface or transactional interceptors, which are defined in the Jakarta Transactions specification. They may access multiple resource managers and invoke multiple enterprise beans within a single transaction. The specified transaction context is automatically propagated to the enterprise beans and transactional resource managers. The result of the propagation may be subject to the enterprise bean transaction attributes (for example, a bean may be required to use Container Managed Transactions).
Web application event listeners and upgrade handlers must not demarcate transactions using the jakarta.transaction.UserTransaction interface or transactional interceptors. Servlet filters may use transactional resources within their doFilter methods but should not use any transactional resources in the methods of any objects used to wrap the request or response objects.
The Jakarta EE platform must meet the following requirements:
-
The Jakarta EE platform must provide an object implementing the jakarta.transaction.UserTransaction interface to all web components. The platform must publish the UserTransaction object in the Java™ Naming and Directory Interface (JNDI) name space available to web components under the name java:comp/UserTransaction.
-
The Jakarta EE platform must provide classes that implement the transactional interceptors, as defined by the Jakarta Transactions specification.
-
If a web component invokes an enterprise bean from a thread associated with a transaction defined by the Jakarta Transactions specification, the Jakarta EE platform must propagate the transaction context with the enterprise bean invocation. Whether the target enterprise bean will be invoked in this transaction context or not is determined by the rules defined in the Jakarta Enterprise Beans specification.
Note that this transaction propagation requirement applies only to invocations of enterprise beans in the same Jakarta EE product instance [1] as the invoking component. Invocations of enterprise beans in another Jakarta EE product instance (for example, using the Jakarta Enterprise Beans interoperability protocol) need not propagate the transaction context. See the Jakarta Enterprise Beans specification for details.
-
If a web component accesses a transactional resource manager from a thread associated with a transaction defined by the Jakarta Transactions specification, the Jakarta EE platform must ensure that the resource access is included as part of the transaction defined by the Jakarta Transactions specification.
-
If a web component creates a thread, the Jakarta EE platform must ensure that the newly created thread is not associated with any transaction defined by the Jakarta Transactions specification.
The Product Provider is not required to support the importing of a transaction context from a client to a web component.
The Product Provider is not required to support transaction context propagation via an HTTP request across web components. The HTTP protocol does not support such transaction context propagation. When a web component associated with a transaction makes an HTTP request to another web component, the transaction context is not propagated to the target servlet or page.
However, when a web component is invoked through the RequestDispatcher interface, any active transaction context must be propagated to the called servlet or server pages.
Transactions may not span web requests from a client on the network. If a web component starts a transaction in the service or doFilter method (or transactional interceptor of service or doFilter method), it must be completed before the service or doFilter method returns to the network client.[2] Returning from the service or doFilter method to the network client with an active transaction context is an error. The web container is required to detect this error and abort the transaction.
As specified above in Transaction Non-Requirements, requests made within a web container using the RequestDispatcher must propagate any transaction context to the called class. Unless the called class commits or aborts the transaction, the transaction must remain active when the called class returns.
If a servlet that is called via the RequestDispatcher starts a transaction, the behavior of the container with regard to that transaction is unspecified when the servlet returns from its service method. The web container may throw an exception to the caller, abort the transaction and return to the caller without error, or propagate the transaction context back to the caller. Portable servlets will complete any transaction they start before returning from the service method.
There are many subtle and complex interactions between the use of transactional resources and threads. To ensure correct operation, web components should obey the following guidelines, and the web container must support at least these usages.
-
Transactions defined by the Jakarta Transactions specification should be started and completed in the thread in which the service method is called. Additional threads that are created for any purpose should not attempt to start transactions defined by the Jakarta Transactions specification.
-
Transactional resources may be acquired and released by a thread other than the service method thread, but should not be shared between threads.
-
Transactional resource objects (for example, JDBC Connection objects) should not be stored in static fields. Such objects can only be associated with one transaction at a time. Storing them in static fields would make it easy to erroneously share them between threads in different transactions.
-
Web components implementing SingleThreadModel may store top-level transactional resource objects in class instance fields. A top-level object is one acquired directly from a container managed connection factory object (for example, a JDBC Connection acquired from a JDBC ConnectionFactory ), as opposed to other objects acquired from these top-level objects (for example, a JDBC Statement acquired from a JDBC Connection ). The web container ensures that requests to a SingleThreadModel servlet are serialized and thus only one thread and one transaction will be able to use the object at a time, and that the top-level object will be enlisted in any new transaction started by the component.
-
In web components not implementing SingleThreadModel , transactional resource objects, as well as Jakarta Persistence EntityManager objects, should not be stored in class instance fields, and should be acquired and released within the same invocation of the service method.
-
Web components that are called by other web components (using the forward or include methods) should not store transactional resource objects in class instance fields.
-
Enterprise beans may be invoked from any thread used by a web component. Transaction context propagation requirements are described above and in the Jakarta Enterprise Beans specification.
The Jakarta EE Product Provider must provide support for transactions as defined in the Jakarta Enterprise Beans specification.
The Jakarta EE Product Provider is not required to provide transaction management support for application clients.
A Jakarta EE product must support a JDBC technology database as a transactional resource manager. The platform must enable transactional JDBC API access from web components and enterprise beans.
It must be possible to access the JDBC technology database from multiple application components within a single transaction. For example, a servlet may wish to start a transaction, access a database, invoke an enterprise bean that accesses the same database as part of the same transaction, and, finally, commit the transaction.
A Jakarta EE product must provide a transaction manager that is capable of coordinating two-phase commit operations across multiple XA-capable JDBC databases. If a JDBC driver supports the Java SE API’s XA interfaces (in the javax.transaction.xa package), then the Jakarta EE product must be capable of using the XA interfaces provided by the JDBC driver to accomplish two-phase commit operations. The Jakarta EE product may discover the XA capabilities of JDBC drivers through product-specific means, although normally such JDBC drivers would be delivered as resource adapters using the Connector API.
A Jakarta EE product must support a Jakarta Messaging provider as a transactional resource manager. The platform must enable transactional Jakarta Messaging access from servlets, server pages, and enterprise beans.
It must be possible to access the Jakarta Messaging provider from multiple application components within a single transaction. For example, a servlet may wish to start a transaction, send a Jakarta Messaging message, invoke an enterprise bean that also sends a Jakarta Messaging message as part of the same transaction, and, finally, commit the transaction.
A Jakarta EE product must support resource adapters that use XATransaction mode as transactional resource managers. The platform must enable transactional access to the resource adapter from servlets, server pages, and enterprise beans.
It must be possible to access the resource adapter from multiple application components within a single transaction. For example, a servlet may wish to start a transaction, access the resource adapter, invoke an enterprise bean that also accesses the resource adapter as part of the same transaction, and, finally, commit the transaction.
This specification does not require the Product Provider to implement any particular protocol for transaction interoperability across multiple Jakarta EE products. Jakarta EE compatibility requires neither interoperability among identical Jakarta EE products from the same Product Provider, nor among heterogeneous Jakarta EE products from multiple Product Providers.
We recommend that Jakarta EE Product Providers use the IIOP transaction propagation protocol defined by OMG and described in the OTS specification, transaction interoperability when using the Jakarta Enterprise Beans interoperability protocol based on RMI-IIOP.
This specification requires all Jakarta EE products to support the javax.transaction.xa.XAResource interface, as referenced in the Connectors specification. This specification also requires all Jakarta EE products to support the javax.transaction.xa.XAResource interface for performing two-phase commit operations on JDBC drivers that support the Java SE XA APIs. This specification does not require that JDBC drivers or Jakarta Messaging providers use the javax.transaction.xa.XAResource interface, although they may use this interface and in all cases they must meet the transactional resource manager requirements described in this chapter. In particular, it must be possible to combine operations on one or more JDBC databases, one or more Jakarta Messaging sessions, one or more enterprise beans, and multiple resource adapters supporting the XATransaction mode in a single transaction defined by the Jakarta Transactions specification.
If a transaction uses a single resource manager, performance may be improved by using a resource manager specific local optimization. A local transaction is typically more efficient than a global transaction and provides better performance. Local optimization is not available for transactions that are imported from a different container.
Containers may choose to provide local transaction optimization, but are not required to do so. Local transaction optimization must be transparent to a Jakarta EE application.
The following section describes a possible mechanism for local transaction optimization by containers.
This section illustrates how the previously described requirements might be implemented.
When the first connection to a resource manager is established as part of the transaction, a resource manager specific local transaction is started on the connection. Any subsequent connection acquired as part of the transaction that can share the local transaction on the first connection is allowed to share the local transaction.
A global transaction is started lazily under the following conditions:
-
When a subsequent connection cannot share the resource manager local transaction on the first connection, or if it uses a different resource manager.
-
When a transaction is exported to a different container.
After the lazy start of a global transaction, any subsequent connection acquired may either share the local transaction on the first connection, or be part of the global transaction, depending on the resource manager it accesses.
When a transaction completion (commit or rollback) is attempted, there are two possibilities:
-
If only a single resource manager had been accessed as part of the transaction, the transaction is completed using the resource manager specific local transaction mechanism.
-
If a global transaction had been started, the transaction is completed treating the resource manager local transaction as a last resource in the global 2-phase commit protocol, that is using the last resource 2-phase commit optimization.
When multiple connections acquired by a Jakarta EE application use the same resource manager, containers may choose to provide connection sharing within the same transaction scope. Sharing connections typically results in efficient usage of resources and better performance. Containers are required to provide connection sharing in certain situations; see the Connector specification for details.
Connections to resource managers acquired by Jakarta EE applications are considered potentially shared or shareable. A Jakarta EE application component that intends to use a connection in an unshareable way must provide deployment information to that effect, to prevent the connection from being shared by the container. Examples of when this may be needed include situations with changed security attributes, isolation levels, character settings, and localization configuration. Containers must not attempt to share connections that are marked unshareable. If a connection is not marked unshareable, it must be transparent to the application whether the connection is actually shared or not.
Jakarta EE application components may use the optional shareable element of the Resource annotation or the optional deployment descriptor element res-sharing-scope to indicate whether a connection to a resource manager is shareable or unshareable. Containers must assume connections to be shareable if no deployment hint is provided. Jakarta EE Application Client XML Schema, the Jakarta Enterprise Beans specification, and the Servlet specification provide descriptions of the deployment descriptor element.
Jakarta EE application components may cache connection objects and reuse them across multiple transactions. Containers that provide connection sharing must transparently switch such cached connection objects (at dispatch time) to point to an appropriate shared connection with the correct transaction scope. Refer to the Connector specification for a detailed description of connection sharing.
The JDBC transaction requirements in Transactional JDBC™ Technology Support and the Jakarta Messaging transaction requirements in Transactional Jakarta Messaging Support may impose some restrictions on a Deployer’s configuration of an application’s JDBC and Jakarta Messaging resources. Jakarta EE Product Providers may impose the restrictions described in this section to meet these requirements.
If the deployer configures a non-XA-capable JDBC resource manager in a transaction, then a Jakarta EE Product Provider may restrict all JDBC access within that transaction to that non-XA-capable JDBC resource manager. Otherwise, a Jakarta EE Product Provider must support use of multiple XA-capable JDBC resource managers within a transaction. In addition, a Jakarta EE Product Provider may restrict the security configuration of all JDBC connections within a transaction to a single user identity. A Jakarta EE Product Provider is not required to support transactions where more than one JDBC identity is used. Specifically, this means that transactions that require the use of more than one JDBC security identity (which can be done explicitly via component provided user name and password) may not be portable.
A Jakarta EE Product Provider may make the same restrictions as above, resulting in a transaction being restricted to a single Jakarta Messaging resource manager and user identity.
In addition, when both a JDBC resource manager and a Jakarta Messaging resource manager are used in the same transaction, a Jakarta EE Product Provider may restrict both to a pairing that allows their combination to deliver the full transactional semantics required by the application, and may restrict the security identity of both to a single identity. To fully support such usage, portable applications that wish to include JDBC and Jakarta Messaging access in a single global transaction must not mark the corresponding transactional resources as “unshareable”.
Although these restrictions are allowed, it is recommended that Jakarta EE Product Providers support JDBC and Jakarta Messaging resource managers that provide full two-phase commit functionality and, as a result, do not impose these restrictions.
A Jakarta EE product must support the use of multiple XA-capable resource adapters in a single transaction. To support such a scenario, full two-phase commit support is required. A Jakarta Messaging provider may be provided as an XA-capable resource adapter. In such a case, it must be possible to include Jakarta Messaging operations in the same global transaction as other resource adapters. While JDBC drivers are not required to be XA-capable, a JDBC driver may be delivered as an XA-capable resource adapter. In such a case, it must be possible to include JDBC operations in the same global transaction as other XA-capable resource adapters. See also Transactional JDBC™ Technology Support.
Although there are no compatibility requirements for system administration capabilities, the Jakarta EE Product Provider will typically include tools that allow the System Administrator to perform the following tasks:
-
Integrate transactional resource managers with the platform.
-
Configure the transaction management parts of the platform.
-
Monitor transactions at runtime.
-
Receive notifications of abnormal transaction processing conditions (such as abnormally high number of transaction rollbacks).