Skip to content

Commit d82112b

Browse files
pandhariwalpandhariwal
authored
Oracle Sagas based CloudBank-DEMO webapp (oracle-samples#325)
* Add CloudBank-Demo code * Modify sagas directory structure * Update Copyright and License * update License details * Create LICENSE * LICENSE
1 parent 4e25586 commit d82112b

File tree

185 files changed

+15010
-105
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

185 files changed

+15010
-105
lines changed

‎sagas/CloudBank-DEMO/Readme.md

+179
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# CloudBank
2+
### (Oracle Sagas based demo web application)
3+
4+
# About
5+
6+
## Overview
7+
8+
This project showcases a demo web application that demonstrates the power and flexibility of Oracle Sagas in distributed transaction management. Oracle Sagas provide a robust mechanism for maintaining data consistency across microservices in a distributed system, allowing for complex business transactions to be executed atomically. This Java application utilizes [Oracle Saga and Microprofile LRA](https://docs.oracle.com/en/database/oracle/oracle-database/23/adfns/developing-applications-saga.html#GUID-D6E883B8-96F2-4364-B564-843465DFF5CF) based annotations to bind Java methods to Oracle Saga entities (Initiators and Participants), facilitating the management of distributed transactions with ease and reliability.
9+
10+
## Key Features
11+
12+
- **Oracle Saga Integration**: Leverages Oracle Sagas for managing distributed transactions, using annotations under the [Oracle Saga Maven dependency](https://mvnrepository.com/artifact/com.oracle.database.saga) to link Java methods to saga participants and initiators.
13+
- **Distributed Transaction Scenarios**: Implements three primary saga workflows for creating bank accounts, issuing credit cards, and transferring money, showcasing various aspects of distributed transactions, including compensations and rollbacks.
14+
- **CloudBank Coordinator**: Acts as a saga initiator, orchestrating transactions across multiple participants with logic to commit or rollback based on the outcome of participant actions.
15+
- **Participants**: Includes BankA, BankB, and CreditScore as participants in the saga transactions, demonstrating intra and interbank operations.
16+
- **Lock-Free Reservations**: Utilizes Oracle Reservable columns for lock-free reservations, enhancing performance and eliminating the need for manual compensation in interbank transfers. [Learn more about Oracle Reservable columns](https://docs.oracle.com/en/database/oracle/oracle-database/23/adfns/using-lock-free-reservation.html#GUID-60D87F8F-AD9B-40A6-BB3C-193FFF0E60BB).
17+
- **Frontend Application**: Features a python flask based frontend for creating new customers, logging in, and facilitating the process of account creation, credit card issuance, and money transfers, complete with a real-time status update dashboard.
18+
19+
## Saga Processes
20+
21+
1. **Bank Account Creation Saga**: This saga showcases the application's capability to execute straightforward yet essential transactions involving fewer participants. The process initiates with the CloudBank Coordinator, which acts as the saga initiator, launching a request to create a new bank account, which could be either a Checking or Savings account. This request is directed to one of the participant services, such as BankA or BankB, based on predefined logic or customer preference.
22+
23+
- The designated account service attempts to create the new account. Success or failure of this operation determines the saga's next step.
24+
- On successful account creation, the saga commits the transaction, officially registering the new account in the system.
25+
- If the operation fails, the saga triggers a rollback, ensuring no partial or incomplete transaction data remains in the system.
26+
27+
This process exemplifies the use of sagas for single-participant transactions beyond the initiator, emphasizing atomicity and consistency in the system's state.
28+
29+
30+
2. **Credit Card Issuance Saga**: This process is a comprehensive demonstration of the application's ability to handle multistep, multi-participant transactions. It begins with the CloudBank Coordinator initiating a saga to issue a new credit card. The saga unfolds in several stages:
31+
- First, the initiator requests one of the banks (either BankA or BankB) to set up a new credit_card account for the customer.
32+
- Concurrently, a request is sent to the CreditScore service to assess the customer's creditworthiness.
33+
- Upon receiving the credit score, the CloudBank Coordinator evaluates it to decide whether to proceed. If the criteria are met, it instructs the relevant account service to update the customer's account balance, effectively setting the stage for the new credit card's issuance.
34+
35+
This entire operation is encapsulated within a single saga, ensuring that either all steps succeed together, thereby committing the transaction, or fail as a unit, in which case the saga orchestrates a rollback to maintain data integrity and consistency across the system.
36+
37+
38+
3. **Money Transfer Saga**: This complex saga illustrates the application's adeptness in handling transactions that span multiple banks and involve intricate coordination between participants. The CloudBank Coordinator again takes the lead, initiating a saga to transfer money between two accounts, which may reside within the same bank (intra-bank) or across different banks (inter-bank).
39+
40+
- In case of interbank transfer,
41+
- The saga begins with simultaneous requests for withdrawal from one account and deposit into another. These operations are managed by the respective banks, BankA or BankB, depending on the accounts' locations.
42+
- Oracle's Reservable columns play a crucial role here, facilitating lock-free reservations that enhance the efficiency of interbank transfers. This eliminates the need for manual compensations, even in the complex scenario of interbank transactions.
43+
- The saga monitors the success of both withdrawal and deposit operations. Only when both operations succeed does the saga commit the transaction, ensuring the transfer is reflected accurately across accounts.
44+
- In case of a failure in either operation, the saga orchestrates a comprehensive rollback. This includes automatically undoing any partial transactions to maintain the integrity and consistency of account balances across bank.
45+
46+
The Money Transfer Saga exemplifies the application's capability to manage high-complexity transactions, showcasing sophisticated coordination and rollback mechanisms to guarantee data consistency and integrity, even in scenarios of network or system failures.
47+
48+
## Getting Started
49+
50+
This section guides you through all the prerequisites and steps needed to get this project up and running, including initial database setup, SAGA_WALLET creation, backend and frontend configuration.
51+
52+
### Prerequisites
53+
54+
Before starting the installation process, ensure the following prerequisites are met:
55+
1. **Java Development Kit (JDK)** is installed for running the Java application.
56+
2. **Python** is installed for the Flask frontend.
57+
3. **Maven** is installed for Java project dependency management.
58+
4. **Tomcat 10** is installed for the WAR deployment.
59+
5. Environment variable `CATALINA_HOME` set to the Tomcat top-level directory.
60+
6. **Oracle DB 23C** is installed and operational, accessible via a running DB listener with an exposed port. This database version supports the advanced features used by the application, including Oracle Sagas.
61+
7. The `requirements.txt` file is present for Python dependencies, which can be installed using pip.
62+
63+
### Initial Database Setup
64+
65+
1. **Create SAGA_WALLET**:
66+
- If the Java application and Oracle DB are on the same server, create a SAGA_WALLET using scripts similar to `saga_wallet_example/setup_wallet.sh`. Make sure to have a wallet.txt file which holds the passwords for the wallet similar to `saga_wallet_example/wallet.txt`.
67+
- Specify the wallet path and `tnsnames.ora` path in `application.properties` under `src/main/resources`. The script can be executed in the following way from the respective directories:
68+
```
69+
./setup_wallet.sh
70+
```
71+
- If deploying the Java application on a different server than the Oracle DB, create the wallet on the Oracle DB server, then export it to the server running Java application. Provide the wallet's and tnsnames.ora path in `application.properties`. The `tnsnames.ora` looks something like the file found on `saga_wallet_example/tnsnames.ora`.
72+
73+
2. **Execute SQL Scripts**:
74+
- The database needs to be prepared before the maven application can be deployed. The application assumes:
75+
```
76+
- CloudBank Coordinator (Initiator, Saga coordinator and Broker) deployed over cdb1_pdb1.
77+
- BankA (Participant) deployed over cdb1_pdb2.
78+
- BankB (Participant) deployed over cdb1_pdb3.
79+
- CreditScore (Participant) deployed over cdb1_pdb4.
80+
```
81+
- Modify `setupPDBS.sql` to match your CDB details, specifically, change `<seed_database>` on the `create pluggable database` lines to the value of your seed database.
82+
- Copy `initdb.sh.example` to `initdb.sh` and mark it as executable, i.e. `chmod a+x ./initdb.sh`
83+
- Modify `initdb.sh` with the correct credentials and connection strings for the environment. To (re)initialize the database, run
84+
- NOTE: The 'setupPDBS.sql' script initially drops PDB's (cdb1_pdb1,cdb1_pdb2,cdb1_pdb3 and cdb1_pdb4) before recreating them.
85+
```
86+
./initdb.sh
87+
```
88+
- The initdb.sh further automatically executes PDB specific scripts to set up respective Saga entities and their supporting tables.
89+
- **Note**:
90+
- `sqlplus` is required and must be in your path.
91+
- The tnsnames.ora should include the newly created PDB's CDB1_PDB1, CDB1_PDB2, CDB1_PDB3 and CDB1_PDB4.
92+
93+
94+
95+
### Backend and Frontend Setup
96+
97+
#### Backend Setup
98+
99+
The backend service utilizes Java and Maven for dependency management. Follow the setups below for backend setup, including environment preparation and running the application.
100+
101+
1. The application is split into 4 components:
102+
- The CloudBank Coordinator is a WAR that needs to be deployed into a Tomcat 10 container.
103+
- The BankA is also a WAR that needs to be deployed into a Tomcat 10 container.
104+
- The BankB is also a WAR that needs to be deployed into a Tomcat 10 container.
105+
- The CreditService is also a WAR that needs to be deployed into a Tomcat 10 container.
106+
107+
2. Deployment Guide:
108+
- Ensure that your Apache Tomcat server is running. You can start Tomcat by executing the `startup.sh` script (on Unix/Linux) or `startup.bat` script (on Windows) located in `$CATALINA_HOME/bin` directory.
109+
- Follow these instructions to deploy BankA, BankB, CreditScore, and finally, the CloudBank applications.
110+
- Build WAR files:
111+
1. Run `mvn clean install` from the `bankA` directory, it will copy the properties file as well as build and package this application in WAR format.
112+
2. Run `mvn clean install` from the `bankB` directory, it will copy the properties file as well as build and package this application in WAR format.
113+
3. Run `mvn clean install` from the `creditscore` directory, it will copy the properties file as well as build and package this application in WAR format.
114+
- Deploy `bankA.war`, `bankB.war`, `creditscore.war` over Tomcat.
115+
1. Locate the WAR files for BankA, BankB and CreditScore in their respective `target` directories.
116+
2. Copy each WAR file into the `$CATALINA_HOME/webapps` directory to initiate the deployment.
117+
3. Once deployed, Tomcat will automatically extract the WAR files into corresponding directories under `webapps`.
118+
- Configuring Participant URLs in CloudBank Application.
119+
1. Open the `Stubs.java` file at `src/main/java/com/oracle/saga/cloudbank/stubs/Stubs.java`.
120+
2. Update the participant URLs (<BANKA_URL:PORT>, <BANKB_URL:PORT> and <CREDITSCORE_URL:PORT>) to match the endpoints exposed by Tomcat after deployment.
121+
- Compiling and Deploying CloudBank Application.
122+
1. Run `mvn clean install` from the `cloudbank` directory, it will copy the properties file as well as build and package this application in WAR format.
123+
2. Copy the generated `cloudbank.war` file into the `$CATALINA_HOME/webapps` directory.
124+
3. Tomcat will automatically deploy the application and make it available.
125+
126+
3. Deployment Verification:
127+
- After deploying all components, verify that each application is accessible via its context path on the Tomcat server.
128+
1. To verify cloudbank deployment visit, `<TOMCAT_URL:PORT>/cloudbank/version`, it should reflect `1.0`.
129+
2. To verify bankA deployment visit, `<TOMCAT_URL:PORT>/bankA/version`, it should reflect `1.0`.
130+
3. To verify bankB deployment visit, `<TOMCAT_URL:PORT>/bankB/version`, it should reflect `1.0`.
131+
4. To verify creditscore deployment visit, `<TOMCAT_URL:PORT>/creditscore/version`, it should reflect `1.0`.
132+
- You can access the Tomcat Web Application Manager to see the list of deployed applications and their statuses.
133+
- For detailed information on managing and monitoring your Tomcat server, refer to the [Tomcat documentation](https://tomcat.apache.org/tomcat-10.0-doc/manager-howto.html).
134+
135+
4. Deployment Troubleshooting:
136+
- If you encounter issues during the deployment process, consult the Tomcat logs located in `$CATALINA_HOME/logs` for error messages and debugging information. Common issues include port conflicts, missing dependencies, and configuration errors in the deployment descriptors.
137+
- If you encounter issues related to `$CATALINA_HOME` not being defined, it means the environment variable pointing to your Tomcat installation directory has not been set. This variable is crucial for running Tomcat commands and scripts.
138+
- If tomcat is running as tomcat user make sure it has access to file in saga_wallet.
139+
140+
141+
#### Frontend Setup
142+
143+
The frontend is built with Python Flask. Ensure Python and pip are installed, then install the necessary dependencies from `requirements.txt`.
144+
The dependencies can be installed using the command:
145+
```
146+
pip install -r requirements.txt
147+
```
148+
149+
1. Modify the app.py file to update the app.secret_key and the CLOUDBANK application URL's. (deployed above)
150+
2. Run the application using the following command:
151+
> python app.py
152+
3. The default port of deployment will be 5000.
153+
154+
155+
#### DEMO LOGIN
156+
There are two pre-defined Accounts in Bank A and Bank B each:
157+
There credentials are:
158+
159+
| USERNAME | PASSWORD | BANK | OSSN | NAME |
160+
|-----------|----------|--------|---------|------------|
161+
| ORACLE001 | cb1 | Bank A | OSSN001 | CUSTOMER 1 |
162+
| ORACLE002 | cb2 | Bank B | OSSN002 | CUSTOMER 2 |
163+
| ORACLE003 | cb3 | Bank B | OSSN003 | CUSTOMER 3 |
164+
| ORACLE004 | cb4 | Bank A | OSSN004 | CUSTOMER 4 |
165+
166+
For creating new users, make sure to add their unique OSSN, Name and Credit Score to the `credit_score_db` table in `CDB1_PDB4` (similar to `sql-script/creditscore.sql`).
167+
168+
169+
## CLEANUP
170+
1. Exit the python flask application.
171+
2. Stop the tomcat server.
172+
3. To clean up the database, modify and execute the script cleanup.sh
173+
174+
## License
175+
176+
Copyright &copy; 2022,2024 Oracle and/or its associates.
177+
178+
All content in this repository is distributed under the [Universal Permissive
179+
License 1.0](https://oss.oracle.com/licenses/upl/).

0 commit comments

Comments
 (0)