6 Integrating XA Global Transactions Between WebLogic Server and Helidon Using MicroTx
This chapter explains how MicroTx ensures consistency of XA transactions using the following distributed applications as an example. In this example, the applications are deployed in a Kubernetes cluster. However, the integration of XA transactions described in this example does not depend on Kubernetes, and can be implemented on any supported platform.
- Helidon Teller Application (transaction initiator)
- Helidon Application (participant application)
- WebLogic Server (participant application)
- MicroTx Transaction Coordinator
The following graphic shows the flow of XA transactions between the various applications and the role of MicroTx as the coordinator of the transactions. Here, the XA transaction is initiated by the Helidon Teller Application, and then distributed to other Helidon and WebLogic Server Applications (the participant applications in the transaction):
Figure 6-1 WebLogic Server, Helidon, and MicroTx Integration
This chapter includes the following topics:
- Prerequisites
In this example, it is assumed that the applications are running in Kubernetes and you have already deployed WebLogic Server, the WebLogic Kubernetes Operator (Operator), Helidon, and MicroTx in the same Kubernetes cluster. - Setting Up the Integration of WebLogic Server with Helidon and MicroTx Applications and Services
With MicroTx, you can ensure a spectrum of data consistency across microservices and cloud native applications without writing any complex code. With a choice of transaction protocols and use of APIs and annotations included in the client libraries, MicroTx makes it easy to use distributed transactions in applications deployed in Kubernetes. - Troubleshooting Common Issues
Learn about the common issues you may encounter when setting up the integration between WebLogic Server and Helidon with MicroTx.
Prerequisites
Note:
Transaction integration with MicroTx is supported only with WebLogic Server 14c (14.1.1.0) and Helidon 2.x because these releases of the products support JDK 11.To deploy MicroTx in the Kubernetes cluster, obtain the MicroTx image from Oracle Container Registry. To obtain samples, client libraries, and deployment scripts, download the MicroTx binaries from Transaction Manager for Microservices Free.
Downloading MicroTx Binaries from Transaction Manager for Microservices Free
- Go to https://www.oracle.com/database/transaction-manager-for-microservices/, click Download MicroTx Free, and then download the installation bundle (.zip file) for Oracle Transaction Manager for Microservices Free. You will be directed to Oracle Software Delivery Cloud.
- You can download the ZIP file using the Oracle Download Manager or simply by clicking the file to download.
- Extract the contents of the ZIP file, preferably in to a new
directory. The
otmm-22.3.2folder contains the following folders:lib: This folder contains the MicroTx library files. You must use these library files in your application code to use MicroTx to manage transactions amongst your application microservices.otmm: This folder contains the MicroTx image and YAML files which you can use to install and configure MicroTx. The image in this folder is the same image that is available in the Oracle Container Registry. Oracle recommends that you use the MicroTx image from the Oracle Container Registry. For steps to download, see Downloading the MicroTx image from Oracle Container Registry.samples: This folder contains the source code for sample applications for different transaction protocols. The source code of the sample applications also includes the MicroTx libraries.Note:
Oracle recommends that you review the sample documentation to become familiar with the build and integration procedures.
Downloading the MicroTx image from Oracle Container Registry
- Go to Oracle Container Registry.
- In the search box, specify Oracle Transaction Manager and click
otmmin the Search Results page. - In the Tags section of the page, you can view the available
versions of MicroTx. To download the latest version, run the following
command:
docker pull container-registry.oracle.com/database/otmm:latestTo download a specific version, for example version 22.3.2, run the following command:docker pull container-registry.oracle.com/database/otmm:22.3.2
In addition, complete the following tasks as part of the prerequisites:
- Configure a WebLogic Server XA data source or emulate two-phase commit data source and target it to the WebLogic cluster. This data source will be used by the WebLogic JAX-RS based web application (which contains the MicroTx library) to connect to the database.
- Configure the JTA Transaction Log as a JDBC store. See Using a JDBC TLog Store in Administering the WebLogic Persistent Store.
- To enable communication between WebLogic Server and Helidon
applications, ensure that:
- The MicroTx Transaction Coordinator Service (TCS) is up and running.
- The Helidon Teller Application is up and running.
- WebLogic Server is able to communicate with MicroTx TCS and the Teller services.
- By default, all resources configured as part of the same Kubernetes cluster communicate with each other using a short name or a fully qualified domain name (FQDN). In case of any restrictions, you should add network rules to enable working with MicroTx TCS.
- WebLogic Deploy Tooling (WDT) Model: The Model in Image domain home pattern enables you to configure the data source using the WDT model files. See Model in Image.
- WebLogic Scripting Tool (WLST): The Domain in Persistent Volume (PV) domain home pattern enables you to configure the data source using WLST. See Domain Home on a PV.
- WebLogic Server Administration Console: The Domain in Persistent Volume (PV) domain home pattern enables you to configure the data source using the Administration Console. See Domain Home on a PV.
In addition, you should have completed the following:
Preparing WebLogic Server to Work with MicroTx
To enable transaction coordination between WebLogic Server and Helidon applications involving data sources, you should first create and deploy the data sources used by the application to connect to the database. You should also configure the JTA TLog JDBC Store for the WebLogic cluster.
- Creating the JDBC Data Sources Using WebLogic Deploy Tooling
- Configuring the JTA Transaction Log as a JDBC Store
Parent topic: Prerequisites
Creating the JDBC Data Sources Using WebLogic Deploy Tooling
You will use WDT to create the XA and non-XA data sources. For more information about WDT, see WebLogic Deploy Tooling.
- Creating the XA Data Source Using WebLogic Deploy Tooling
- Creating the Non-XA Data Source Using WebLogic Deploy Tooling
Parent topic: Preparing WebLogic Server to Work with MicroTx
Creating the XA Data Source Using WebLogic Deploy Tooling
An example of creating the XA data source, oraxads, using WDT:
resources:
JDBCSystemResource:
oraxads:
Target: cluster-1
JdbcResource:
DatasourceType: GENERIC
JDBCConnectionPoolParams:
TestFrequencySeconds: 600
InitialCapacity: 2
ConnectionReserveTimeoutSeconds: 10
TestConnectionsOnReserve: true
MaxCapacity: 30
TestTableName: SQL SELECT 1 FROM DUAL
MinCapacity: 3
JDBCDataSourceParams:
JNDIName: oraxads
GlobalTransactionsProtocol: TwoPhaseCommit
JDBCDriverParams:
DriverName: oracle.jdbc.xa.client.OracleXADataSource
PasswordEncrypted: '@@PROP:oraxads.password@@'
URL: jdbc:oracle:thin:@//@@PROP:oraxads.url@@
Properties:
user:
Value: '@@PROP:oraxads.user@@'
databaseName: {}Creating the Non-XA Data Source Using WebLogic Deploy Tooling
An example of creating the non-XA data source, jtads, using WDT:
resources:
JDBCSystemResource:
jtads:
Target: cluster-1
JdbcResource:
DatasourceType: GENERIC
JDBCConnectionPoolParams:
TestFrequencySeconds: 600
InitialCapacity: 2
ConnectionReserveTimeoutSeconds: 10
TestConnectionsOnReserve: true
MaxCapacity: 30
TestTableName: SQL SELECT 1 FROM DUAL
MinCapacity: 3
JDBCDataSourceParams:
JNDIName: jtads
GlobalTransactionsProtocol: None
JDBCDriverParams:
DriverName: oracle.jdbc.OracleDriver
PasswordEncrypted: '@@PROP:jtads.password@@'
URL: jdbc:oracle:thin:@//@@PROP:jtads.url@@
Properties:
user:
Value: '@@PROP:jtads.user@@'
databaseName: {}Configuring the JTA Transaction Log as a JDBC Store
Before you configure the JTA Transaction Log as a JDBC store, ensure that you have created the data source used by the transaction log store to log transactions. See Creating the JDBC Data Sources Using WebLogic Deploy Tooling.
You can configure the JTA Transaction Log as a JDBC store using one of the following methods:
- Configuring the JTA Transaction Log as a JDBC Store Using WebLogic Deploy Tooling
- Configuring the JTA Transaction Log as a JDBC Store Using the WebLogic Scripting Tool
- Configuring the JTA Transaction Log as a JDBC Store Using the Administration Console
Parent topic: Preparing WebLogic Server to Work with MicroTx
Configuring the JTA Transaction Log as a JDBC Store Using WebLogic Deploy Tooling
The following example of the WDT script uses the non-XA data source,
jtads, to configure the JTA Transaction Log as a JDBC
store:
topology:
ServerTemplate:
server-template_1:
TransactionLogJDBCStore:
Enabled: true
DataSource: jtads
PrefixName: TLOG_${serverName}_Parent topic: Configuring the JTA Transaction Log as a JDBC Store
Configuring the JTA Transaction Log as a JDBC Store Using the WebLogic Scripting Tool
The following example of the WLST script uses the non-XA data source,
jtads, to configure the JTA Transaction Log
as a JDBC store:
import sys,os,socket, traceback
adminUsername=sys.argv[1]
adminPassword=sys.argv[2]
adminT3URL=sys.argv[3]
connect(adminUsername,adminPassword,adminT3URL)
edit()
startEdit()
##Here SERVER_TEMPLATE_NAME refers to WebLogic dynamic-cluster Server Template Name
cd('/ServerTemplates/SERVER_TEMPLATE_NAME')
cd('/ServerTemplates/SERVER_TEMPLATE_NAME/TransactionLogJDBCStore/SERVER_TEMPLATE_NAME')
##Here jtads refers to datasource name used for Transaction Log JDBC Store
cmo.setDataSource(getMBean('/JDBCSystemResources/jtads'))
cmo.setEnabled(true)
cmo.setPrefixName('TLOG_${serverName}_')
save()
activate()
disconnect()Parent topic: Configuring the JTA Transaction Log as a JDBC Store
Configuring the JTA Transaction Log as a JDBC Store Using the Administration Console
Parent topic: Configuring the JTA Transaction Log as a JDBC Store
Modifying the MicroTx Configurations
When running in Kubernetes, transaction integration between WebLogic Server and Helidon coordinated by MicroTx requires that you deploy WebLogic Server, Helidon, and MicroTx in the same Kubernetes cluster and that you configure all the Kubernetes resources and services. See Preparing the Kubernetes Cluster for WebLogic Server and Helidon Integration.
The Kubernetes resources can be part of different namespaces. To work
with all the namespaces within the Kubernetes cluster, you should enable
MicroTx TCS to communicate with services across all the namespaces by
modifying the MicroTx TCS PeerAuthentication policy.
Parent topic: Prerequisites
Allowing Communication Between Peers Across Namespaces
Peer authentication provides service-to-service authentication in a Kubernetes cluster with Istio service mesh. For more information, see PeerAuthentication.
Change the Oracle Transaction Manager for Microservices (OTMM)
PeerAuthentication policy's spec.mtls.mode value from
STRICT to PERMISSIVE in the
<otmm>/helmcharts/tmm/templates/auth.yaml file. The
PERMISSIVE value facilitates communication across all the namespaces in
the Kubernetes cluster.
The spec.mtls.mode value before the change:
apiVersion: "security.istio.io/v1beta1"
kind: "PeerAuthentication"
metadata:
name: "peer-auth"
namespace: {{ .Values.applicationNameSpace }}
spec:
mtls:
mode: STRICTThe spec.mtls.mode value after the change:
apiVersion: "security.istio.io/v1beta1"
kind: "PeerAuthentication"
metadata:
name: "peer-auth"
namespace: {{ .Values.applicationNameSpace }}
spec:
mtls:
mode: PERMISSIVEFor more information about peer authentication, see PeerAuthentication.
Parent topic: Modifying the MicroTx Configurations
Creating Routing Rules
Routing rules are created to access the WebLogic Servers, the WebLogic Server Administration Console, applications, and Helidon.
Create an Istio VirtualService to define a set of
traffic routing rules that apply to all the applications of the WebLogic cluster,
Helidon, and the teller service. You may use the following example of the script as
reference:
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: wls-domain-virtualservice
namespace: wls-domain-ns
spec:
gateways:
- otmm/otmm-gateway
hosts:
- '*'
http:
- match:
- uri:
prefix: /console
- uri:
prefix: /management
- port: 7001
route:
- destination:
host: wls-domain-admin-server
port:
number: 7001
- match:
- uri:
prefix: /mtxwls
- port: 8001
route:
- destination:
host: wls-domain-cluster-cluster-1
port:
number: 8001
- match:
- uri:
prefix: /mtxhelidon
- port: 8084
route:
- destination:
host: microtx-helidon.helidon-ns.svc.cluster.local
port:
number: 8084
- match:
- uri:
prefix: /mtxteller
- port: 8087
route:
- destination:
host: microtx-teller.helidon-ns.svc.cluster.local
port:
number: 8087For more information about the Istio virtual service specifications, see Istio Gateway.
WebLogic Server and MicroTx have their own Administration Consoles. By
default, the MicroTx Console is not supported. You will experience path collision if
you access the WebLogic Server Administration Console using
http(s)://LoadBalancer/console. In this case, you need to
change the notpaths value in the Oracle Transaction Manager for
Microservices (OTMM) Authorization Policy rules in
<otmm>/helmcharts/tmm/templates/auth.yaml file, as
shown below. However, you can also use different URLs by rewriting the paths.
apiVersion: "security.istio.io/v1beta1"
kind: "AuthorizationPolicy"
metadata:
name: "frontend-ingress"
namespace: {{ .Values.istioSystemNameSpace }}
spec:
selector:
matchLabels:
istio: {{ .Values.istioIngressGateway.name }}
action: {{ .Values.authentication.requestsWithNoJWT }}
rules:
- from:
- source:
notRequestPrincipals: ["*"]
to:
- operation:
###########notPaths Value before change ["/console*"]######################
notPaths: ["/mtxconsole*"]Parent topic: Modifying the MicroTx Configurations
Setting Up the Integration of WebLogic Server with Helidon and MicroTx Applications and Services
As part of the MicroTx and WebLogic Server integration, MicroTx uses WebLogic Server Interposed Transaction Manager (ITM) to coordinate the transactions with WebLogic Server.
To enable the JDBC resources deployed in the WebLogic Server domain
(as javax.transaction.xa.XAResource) to participate in the
transaction, MicroTx must interface with WebLogic Server using ITM. The
WebLogic Server ITM exposes a
javax.transaction.xa.XAResource implementation
using the weblogic.transaction.InterposedTransactionManager
interface. The MicroTx transaction manager accesses the
InterposedTransactionManager interface to
coordinate with the WebLogic Server transaction manager
XAResource during its commit processing. See Participating in
Transactions Managed by a Third-Party Transaction Manager in
Developing JTA Applications for Oracle WebLogic
Server.
Download the MicroTx binaries from the MicroTx Downloads page (see Prerequisites) and complete the following tasks to enable the integration between WebLogic Server, Helidon, and MicroTx applications and services:
- Building and Deploying the Helidon Teller Application
- Building and Deploying the Helidon Participant Application
- Building and Deploying the MicroTx Application WAR File in the WebLogic Server Domain
- Deploying the Web Application in the WebLogic Cluster Using WebLogic Deploy Tooling
- Deploying the MicroTx Coordinator Service
Building and Deploying the Helidon Participant Application
Building and Deploying the MicroTx Application WAR File in the WebLogic Server Domain
To build an application WAR (Web Application Resource or Web Application ARchive) file for WebLogic Server and target the file to the WebLogic cluster or the Managed Server resources:
Note:
If you want to work with your own JAX-RS application, ensure that
you add the following pom dependency and the
javax.ws.rs.core.Application subclass to your JAX-RS
application. However, you need to use the WebLogic data source connection in
your application.
This following dependency is referred from the local Maven repository. Therefore, you should add this artifactory to the local Maven repository before packaging the project.
<dependency>
<groupId>com.oracle.tmm.jta</groupId>
<artifactId>TmmLib</artifactId>
<version>22.3.2</version>
</dependency>Also, add the javax.ws.rs.core.Application subclass
to scan all the resource classes annotated with @Provider and
@Path. This subclass is required to register the MicroTx
filter classes, callback resources, and connection factory classes.
The javax.ws.rs.core.Application subclass method
'getClasses()' or 'getSingletons()' return
the relevant JAX-RS resources and providers. If empty sets are returned in both
the getClasses() and getSingletons() methods,
all the JAX-RS resource and provider classes that are found in the application
are added to the JAX-RS application subclass.
package com.oracle.mtm.sample;
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
@ApplicationPath("/")
public class WebLogicWebApp extends Application {
}Deploying the Web Application in the WebLogic Cluster Using WebLogic Deploy Tooling
The following example script is used to deploy the WebLogic Server JAX-RS web application WAR file in the WebLogic cluster using WDT:
appDeployments:
Application:
mtxwwls :
SourcePath: wlsdeploy/applications/mtxwls.war
Target: cluster-1
ModuleType: warDeploying the MicroTx Coordinator Service
Before you deploy the MicroTx Coordinator Service, ensure that you have deployed the Istio service mesh in the Kubernetes cluster.
To deploy the MicroTx Coordinator Service:
A few samples of the values.yaml file:
-
A sample of the configuration values in the
tmmImagesection of the file (you can refer thetmmImageimage from Oracle Container Registry instead of storing and referring the image from the local container registry):tmmImage: image: <Image_Registry>/tmm:22.3.x imagePullPolicy: Always imagePullSecret: regcred -
A sample of the configuration values for the
tmmExternalURL,xaCoordinator, andstorage.typeproperties in thetmmConfigurationsection of file:tmmConfiguration: tmmId: "TCS01" tmmAppName: otmm-tcs port: 9000 tmmExternalURL: protocol: http host: x.x.x.x port: 80 xaCoordinator: enabled: "true" txMaxTimeout: 600000 lraCoordinator: enabled: "false" tccCoordinator: enabled: "false" storage: type: db db: connectionString: "tcps://<ORACLE_DB_HOST>:<ORACLE_DB_PORT>/<ORACLE_DB_SERVICE>?retry_count=20&retry_delay=3" credentialSecretName: "walletsecret" connectionParams: "" walletConfigMap: configMapName: "db-wallet-cmap" completedTransactionTTL: 60 # Sample configuration values for Retry settings #The maximum number of times the TMM (Transaction Coordinator) will retry an operation in case of certain failures maxRetryCount: 10 #The minimum retry interval in milliseconds minRetryInterval: 1000 #The maximum retry interval in milliseconds maxRetryInterval: 10000 # Coordinator HTTP client timeout value in seconds. A Timeout of zero means no timeout. Max allowed value is 900 seconds httpClientTimeoutInSecs: 180
Note:
By default, the OTMM Coordinator Service'shttpClientTimeoutInSecs value is set to 180 seconds. This
timeout is considered when OTMM coordinator service communicates with the
transaction participants to complete the transaction. This value is used along with
the other retry settings parameters in values.yaml.
Troubleshooting Common Issues
Learn about the common issues you may encounter when setting up the integration between WebLogic Server and Helidon with MicroTx.
Issue 1
In the Helidon applications, the XA connections fail and report an error when the
Application Context Path is defined by extending the
javax.ws.rs.core.Application class provided by the JAX-RS
implementation. Here is a sample of the error message:
2023.03.17 11:39:16 WARNING io.helidon.microprofile.server.JaxRsCdiExtension
!thread!: Internal server error java.lang.NullPointerException
at oracle.tmm.jta.common.TrmConnectionFactory.getXAConn(TrmConnectionFactory.java:47)
at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAcc essorImpl.java:62)
. . . .
The following sample code shows the exception that is reported (after you create the
Helidon Application/Context path by extending
javax.ws.rs.core.Application):
package com.oracle.mtm.sample.resource;
import java.util.Set;
import javax.enterprise.context.ApplicationScoped;
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
//Adding Application Context path by extending javax.ws.rs.core.Application
@ApplicationScoped
@ApplicationPath("/helidonapp")
public class HelidonApplication extends Application {
@Override
public Set<Class<?>> getClasses() {
return Set.of(AccountsResource.class);
}
}Solution:
Create the Application/Context path by extending
org.glassfish.jersey.server.ResourceConfig, as shown below:
package com.oracle.mtm.sample.resource;
import java.util.Set;
import javax.enterprise.context.ApplicationScoped;
import org.glassfish.jersey.server.ResourceConfig;
import javax.ws.rs.ApplicationPath;
//Adding Application Context path by extending org.glassfish.jersey.server.ResourceConfig
@ApplicationPath("/helidonapp")
public class HelidonApplication extends ResourceConfig {
}Issue 2
The Helidon Teller Application reports the transaction limit error. Here is a sample of the error message:
2023.04.10 06:03:05 INFO TMMLibDefaultLogger !thread!: begin response from TCS: transaction limit error. Reached total allowed transactions count of 4800. Please try after one hour
---429
2023.04.10 06:03:05 WARNING io.helidon.microprofile.server.JaxRsCdiExtension !thread!: Internal server error
javax.transaction.SystemException: transaction limit error. Reached total allowed transactions count of 4800. Please try after one hour
at oracle.tmm.jta.TrmUserTransaction.begin(TrmUserTransaction.java:183)
at oracle.tmm.jta.TrmUserTransaction.begin(TrmUserTransaction.java:124)
at oracle.tmm.jta.transactional.TrmTransactionalRequired.intercept(TrmTransactionalRequired.java:51)
. . . .
. . . .
Solution:
The MicroTx Free release 22.3.1 and earlier have restrictions on the number of transactions allowed per hour. Use MicroTx Free 22.3.2 and later to remove this restriction.
Issue 3
When the correct privileges are not granted in the database, Helidon and
WebLogic Server report an error (XAER_RMERR error) when trying to
recover transactions. Here is a sample of the error message:
2023.05.02 11:47:09 SEVERE TMMLibDefaultLogger !thread!: RMID : <RMID> XA Exception: XAErr: -3 XAErrString: XAER_RMERR
javax.transaction.xa.XAException
at oracle.jdbc.xa.OracleXAResource.recover(OracleXAResource.java:754)
at oracle.tmm.jta.common.TrmXAResource.xaop(TrmXAResource.java:225)
. . . .
Solution:
Provide the following database privileges to the Helidon and WebLogic database users:
GRANT SELECT ON sys.dba_pending_transactions TO <DB_USERNAME>;
GRANT SELECT ON sys.dba_2pc_pending TO <DB_USERNAME>;
GRANT EXECUTE ON sys.dbms_xa TO <DB_USERNAME>;
GRANT FORCE ANY TRANSACTION TO <DB_USERNAME>;