diff --git a/.github/workflows/java.yaml b/.github/workflows/java.yaml index 53b5d7f..b684bab 100644 --- a/.github/workflows/java.yaml +++ b/.github/workflows/java.yaml @@ -25,9 +25,9 @@ jobs: - jdk: 25 experimental: true steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up JDK ${{ matrix.jdk }} - uses: actions/setup-java@v3 + uses: actions/setup-java@v4 with: java-version: ${{ matrix.jdk }} distribution: "semeru" @@ -53,9 +53,9 @@ jobs: - jdk: 25 experimental: true steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up JDK ${{ matrix.jdk }} - uses: actions/setup-java@v3 + uses: actions/setup-java@v4 with: java-version: ${{ matrix.jdk }} distribution: "semeru" @@ -76,16 +76,16 @@ jobs: - jdk: 25 experimental: true steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up JDK ${{ matrix.jdk }} uses: actions/setup-java@v4 with: java-version: ${{ matrix.jdk }} distribution: 'semeru' + - name: Setup Gradle + uses: gradle/actions/setup-gradle@v4 - name: Build with Gradle - uses: gradle/gradle-build-action@bd5760595778326ba7f1441bcf7e88b49de61a25 - with: - arguments: bootWar -Pjava_version=${{ matrix.jdk }} + run: ./gradlew bootWar -Pjava_version=${{ matrix.jdk }} build-gradlew: name: Build Gradle wrapper @@ -100,13 +100,13 @@ jobs: - jdk: 25 experimental: true steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Set up JDK ${{ matrix.jdk }} uses: actions/setup-java@v4 with: java-version: ${{ matrix.jdk }} distribution: 'semeru' - name: Setup Gradle - uses: gradle/actions/setup-gradle@v3 + uses: gradle/actions/setup-gradle@v4 - name: Build with Gradle run: ./gradlew build bootWar -Pjava_version=${{ matrix.jdk }} diff --git a/.settings/org.eclipse.wst.common.component b/.settings/org.eclipse.wst.common.component index 454e07e..05bab8a 100644 --- a/.settings/org.eclipse.wst.common.component +++ b/.settings/org.eclipse.wst.common.component @@ -1,15 +1,22 @@ - - - + + + + + - + + - + + - + + - - + + + + diff --git a/README.md b/README.md index fbd5e48..57f2b4f 100644 --- a/README.md +++ b/README.md @@ -1,116 +1,166 @@ # cics-java-liberty-springboot-jdbc -[![Build](https://github.com/cicsdev/cics-java-liberty-springboot-jdbc/actions/workflows/java.yaml/badge.svg)](https://github.com/cicsdev/cics-java-liberty-springboot-jdbc/actions/workflows/java.yaml) - -This project demonstrates a Spring Boot JDBC application integrated with IBM CICS that can be deployed to a CICS Liberty JVM server. The application makes use of the employee sample table supplied with Db2 for z/OS. The application allows you to add, update, delete or display employee information from the table EMP. The sample also provides a set of Gradle and Maven build files for use either in Eclipse or standalone build environments. - -## Requirements -* CICS TS V5.3 or later -* A configured Liberty JVM server -* Java SE 17 or later on the workstation (required for Spring Boot 3.x) -* IBM Db2 V11 or later on z/OS -* An Eclipse development environment on the workstation (optional) -* Either Gradle or Apache Maven on the workstation (optional if using Wrappers) - -## Reference - -More information about the development of this sample can be found in the IBM tutorial [Spring Boot Java applications for CICS, Part 4: JDBC](https://developer.ibm.com/tutorials/spring-boot-java-applications-for-cics-part-4-jdbc/) +[![Build](https://github.com/cicsdev/cics-java-liberty-springboot-jdbc/actions/workflows/java.yaml/badge.svg)](https://github.com/cicsdev/cics-java-liberty-springboot-jdbc/actions/workflows/java.yaml) +[![License](https://img.shields.io/badge/License-EPL%202.0-green.svg)](https://opensource.org/licenses/EPL-2.0) -## Downloading -* Clone the repository using your IDE's support, such as the Eclipse Git plugin -* **or**, download the sample as a ZIP and unzip onto the workstation +## Overview ->*Tip: Eclipse Git provides an 'Import existing Projects' check-box when cloning a repository.* +This sample demonstrates how to integrate **Spring Boot** with **IBM CICS** using **JDBC** on **CICS Liberty JVM server**. The application makes use of the employee sample table supplied with Db2 for z/OS. The application allows you to add, update, delete or display employee information from the table EMP. -## Building +The sample is intended both as a runnable example and as an educational reference for developers building enterprise-grade Spring Boot applications with JDBC on CICS Liberty. -You can build the sample using an IDE of your choice, or you can build it from the command line. For both approaches, using the supplied Gradle or Maven wrapper is the recommended way to get a consistent version of build tooling. +**What This Sample Does:** +- Provides REST endpoints for employee data management (add, update, delete, display) +- Demonstrates Spring Boot JDBC integration with Db2 for z/OS +- Shows both transactional and non-transactional database operations +- Supports both JDBC Type 2 (local) and Type 4 (remote) connectivity +- Integrates with CICS security for authentication and authorization -On the command line, you simply swap the Gradle or Maven command for the wrapper equivalent, `gradlew` or `mvnw` respectively. +--- -For an IDE, taking Eclipse as an example, the plug-ins for Gradle *buildship* and Maven *m2e* will integrate with the "Run As..." capability, allowing you to specify whether you want to build the project with a Wrapper, or a specific version of your chosen build tool. +## Table of Contents -The required build-tasks are typically `clean bootWar` for Gradle and `clean package` for Maven. Once run, Gradle will generate a WAR file in the `build/libs` directory, while Maven will generate it in the `target` directory. +1. [Design and Architecture](#design-and-architecture) +2. [Transaction Management](#transaction-management) +3. [Before You Start: Files to Modify](#before-you-start-files-to-modify) +4. [Requirements](#requirements) +5. [Building the Sample](#building-the-sample) +6. [Deploying to CICS](#deploying-to-cics) + - [Method 1: CICS Bundle Deployment (Gradle/Maven)](#method-1-cics-bundle-deployment-gradlemaven) + - [Method 2: CICS Explorer Deployment](#method-2-cics-explorer-deployment) + - [Method 3: Direct Liberty Application Deployment](#method-3-direct-liberty-application-deployment) + - [Common Bundle Installation Steps](#common-bundle-installation-steps) +7. [Running the Sample](#running-the-sample) +8. [Troubleshooting](#troubleshooting) +9. [License](#license) +10. [Additional Resources](#additional-resources) +11. [Contributing](#contributing) -**Note:** When building a WAR file for deployment to Liberty it is good practice to exclude Tomcat from the final runtime artifact. We demonstrate this in the pom.xml with the *provided* scope, and in build.gradle with the *providedRuntime()* dependency. +--- -**Note:** If you import the project to your IDE, you might experience local project compile errors. To resolve these errors you should run a tooling refresh on that project. -For example, in Eclipse: -* for Gradle, right-click on "Project", select "Gradle -> Refresh Gradle Project", -* for Maven, right-click on "Project", select "Maven -> Update Project...". +## Design and Architecture -> Tip: *In Eclipse, Gradle (buildship) is able to fully refresh and resolve the local classpath even if the project was previously updated by Maven. However, Maven (m2e) does not currently reciprocate that capability. If you previously refreshed the project with Gradle, you'll need to manually remove the 'Project Dependencies' entry on the Java build-path of your Project Properties to avoid duplication errors when performing a Maven Project Update.* +This sample demonstrates how a Spring Boot application can run in a CICS Liberty JVM server and access Db2 for z/OS through a Liberty-managed datasource. -#### Gradle Wrapper (command line) +Key components: -Run the following in a local command prompt: +1. **Spring Boot Framework** - Provides dependency injection, REST support, and JDBC abstraction +2. **Spring Data JDBC** - Simplifies database access with JdbcTemplate +3. **Liberty JNDI Datasource** - Connects to Db2 via JNDI lookup +4. **CICS Transaction Context** - Ensures operations run within CICS transactions -On Linux or Mac: +### Architecture Diagram -```shell -./gradlew clean bootWar ``` -On Windows: - -```shell -gradlew.bat clean bootWar +┌─────────────────────────────────────────────────────────────────┐ +│ HTTP Client │ +│ (Browser, curl, etc.) │ +└────────────────────────────┬────────────────────────────────────┘ + │ + │ REST Requests + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ CICS Liberty JVM Server │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ Spring Boot Application (WAR) │ │ +│ │ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ EmployeeRestController │ │ │ +│ │ │ • @GetMapping endpoints │ │ │ +│ │ │ • /allEmployees │ │ │ +│ │ │ • /listEmployee/{empno} │ │ │ +│ │ │ • /addEmployee/{firstName}/{lastName} │ │ │ +│ │ │ • /updateEmployee/{empNo}/{newSalary} │ │ │ +│ │ │ • /deleteEmployee/{empNo} │ │ │ +│ │ │ • Transactional variants (*Tx endpoints) │ │ │ +│ │ └────────────┬─────────────────────────────────────┘ │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ EmployeeService │ │ │ +│ │ │ • Business logic layer │ │ │ +│ │ │ • Uses Spring JdbcTemplate │ │ │ +│ │ │ • selectAll(), addEmployee() │ │ │ +│ │ │ • updateEmployee(), deleteEmployee() │ │ │ +│ │ └────────────┬─────────────────────────────────────┘ │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ Spring JdbcTemplate │ │ │ +│ │ │ • Autowired from Spring context │ │ │ +│ │ │ • Configured via application.properties │ │ │ +│ │ └────────────┬─────────────────────────────────────┘ │ │ +│ │ │ │ │ +│ │ ▼ │ │ +│ │ ┌──────────────────────────────────────────────────┐ │ │ +│ │ │ Liberty JNDI Datasource │ │ │ +│ │ │ • jndiName: jdbc/jdbcDataSource │ │ │ +│ │ │ • Configured in server.xml │ │ │ +│ │ └────────────┬─────────────────────────────────────┘ │ │ +│ │ │ │ │ +│ └───────────────┼───────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ IBM Db2 JDBC Driver (Type 2 or Type 4) │ │ +│ └────────────┬─────────────────────────────────────┘ │ +└───────────────┼──────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ IBM Db2 for z/OS │ +│ (EMP Sample Table) │ +└─────────────────────────────────────────────────────────────────┘ ``` -This creates a WAR file in the `build/libs` directory. - -#### Maven Wrapper (command line) +### Component Responsibilities +| Component | Purpose | Key Features | +|-----------|---------|--------------| +| **Application** | Spring Boot entry point | `@SpringBootApplication`, main method | +| **EmployeeRestController** | REST API endpoints | `@RestController`, `@GetMapping`, routes requests | +| **EmployeeService** | Business logic layer | `@Service`, `@Autowired JdbcTemplate`, CRUD operations | +| **Employee** | Data model | POJO representing EMP table structure | +| **ServletInitializer** | WAR deployment support | Extends `SpringBootServletInitializer` | +| **application.properties** | Configuration | JNDI datasource name | +| **server.xml** | Liberty configuration | Datasource, features, security | -Run the following in a local command prompt: +--- -On Linux or Mac: +## Transaction Management -```shell -./mvnw clean package -``` +The sample includes both simple JDBC operations and transactional variants. Transactional endpoints require an XA or otherwise transactional datasource configuration in Liberty. -On Windows: +--- -```shell -mvnw.cmd clean package -``` +## Before You Start: Files to Modify -This creates a WAR file in the `target` directory. +Before building and deploying this sample, you **must** customize the following files with your environment-specific values: -## Deploying to a CICS Liberty JVM Server +### 1. Db2 Connection Configuration -- Ensure you have the following features defined in your Liberty `server.xml`: - - `` or `` depending on the version of Java EE in use. - - `` if CICS security is enabled. - - `` - - `` or '' +**File:** Liberty `server.xml` ->**Note:** `servlet-4.0` will only work for CICS TS V5.5 or later +**What to change:** -- add a dataSource definition to 'server.xml'. - -E.g. as follows for JDBC type 2 connectivity (substitute your values as necessary): - -If you are using jdbc-4.3 then type needs to be there - type="javax.sql.DataSource" else default will be taken for older previous. - -``` XML +For **JDBC Type 2** (local connectivity): +```xml - - - - - - - - - - - -``` - -...or for JDBC type 4 connectivity (substitute your values as necessary): - -``` XML + + + + + + + + + + + +``` + +For **JDBC Type 4** (substitute your values as necessary): +```xml @@ -126,48 +176,536 @@ If you are using jdbc-4.3 then type needs to be there - type="javax.sql.DataSour user="USER" password="PASSWORD" /> - + +``` + +--- + +### 2. CICS Region Configuration + +**Prerequisites:** + +Before deploying, ensure your CICS region has: + +1. **DB2CONN Setup:** + - DB2CONN resource defined and installed in CICS + +2. **CICS SIT Parameters (Type 2 connections only):** + ``` + DB2CONN=YES + ``` + **Note:** The `DB2CONN=YES` parameter is **only required for JDBC Type 2 connections**. . + +3. **JCL Configuration:** + Add these lines to your CICS region JCL: + ``` + // DD DSN=SYS2.DB2.V12.SDSNLOAD,DISP=SHR + // DD DSN=SYS2.DB2.V12.SDSNLOD2,DISP=SHR + ``` + These DD statements provide the necessary DB2 load libraries for the CICS region to access DB2. + +--- + +### 3. Liberty Server Configuration + +**File:** Liberty `server.xml` + +**Required Features:** +```xml + + servlet-6.0 + pages-3.1 + jdbc-4.3 + cicsts:security-1.0 + ``` -- set spring.datasource.jndi-name in application.properties +**Notes:** +- `servlet-6.0` requires CICS TS V6.1 or later +- `cicsts:security-1.0` is automatically added if SEC=YES in SIT +- For `jdbc-4.3`, add `type="javax.sql.DataSource"` to datasource definition + +--- + +### 4. Application Configuration -The file application.properties in `/src/main/resources/` contains the property -``` shell +**File:** `cics-java-liberty-springboot-jdbc-app/src/main/resources/application.properties` + +**Verify JNDI name matches:** +```properties spring.datasource.jndi-name=jdbc/jdbcDataSource ``` -This will direct the application to the dataSource definition in the server.xml which must have parameter `jndiName` set to the same value as specified in the application properties file -- Deployment option 1: - - Copy and paste the built WAR from your *target* or *build/libs* directory into a Eclipse CICS bundle project and create a new WAR bundlepart that references the WAR file. Then deploy the CICS bundle project from CICS Explorer using the **Export Bundle Project to z/OS UNIX File System** wizard. - +This must match the `jndiName` attribute in your server.xml datasource definition. + +--- + +### 5. Build Configuration (Optional) + +**Files:** +- `cics-java-liberty-springboot-jdbc-cicsbundle/build.gradle` +- `cics-java-liberty-springboot-jdbc-cicsbundle/pom.xml` + +**When is this needed?** +Only if using **CICS Bundle Deployment** with Gradle or Maven. This tells the CICS bundle plugins which Liberty JVM server will run your application. + +**What to change:** + +Gradle (`build.gradle`): +```gradle +cics.jvmserver = 'YOUR_JVMSERVER_NAME' // e.g., 'DFHWLP' +``` + +Maven (`pom.xml`): +```xml +YOUR_JVMSERVER_NAME +``` + +--- + +## Requirements + +### Workstation Requirements +* **Java:** Java SE 17 or later (required for Spring Boot 3.x) +* **Build Tools:** + - **Gradle:** Version 7.3+ (Java 17 support) - Recommended: 8.0+ - included via wrapper + - **Maven:** Version 3.8.1+ (Java 17 support) - Recommended: 3.9.0+ - included via wrapper +* **IDE (Optional):** + - Eclipse with IBM CICS SDK for Java EE, Jakarta EE and Liberty + - IntelliJ IDEA, VS Code, or any IDE with Gradle/Maven support + - Command line (no IDE required if using wrappers) + +### z/OS Requirements +* **CICS TS:** V5.3 or later +* **WebSphere Liberty:** Included with CICS +* **IBM Db2:** V11 or later on z/OS +* **Java:** IBM Semeru Runtime 17 or later on z/OS + +### Database Requirements +* Access to Db2 for z/OS with the EMP sample table +* The EMP table is typically provided in the Db2 sample database +* Appropriate permissions to SELECT, INSERT, UPDATE, DELETE on the EMP table + +--- + +## Building the Sample + +You can build using Gradle, Maven, or Eclipse. The wrappers are pre-configured with compatible versions. + +### Option 1: Building with Gradle + +**From the root directory:** + +Linux/Mac: +```bash +./gradlew clean build +``` + +Windows: +```cmd +gradlew.bat clean build +``` + +**Output:** +- WAR file: `cics-java-liberty-springboot-jdbc-app/build/libs/cics-java-liberty-springboot-jdbc.war` +- CICS bundle ZIP: `cics-java-liberty-springboot-jdbc-cicsbundle/build/distributions/cics-java-liberty-springboot-jdbc-cicsbundle-1.0.0.zip` + +**Note:** +- In Eclipse, the `build` directory may be hidden. To view it: Package Explorer → ⋮ menu → Filters → Uncheck "Gradle build folder" + +--- + +### Option 2: Building with Maven + +**From the root directory:** + +Linux/Mac: +```bash +./mvnw clean package +``` + +Windows: +```cmd +mvnw.cmd clean package +``` + +**Output:** +- WAR file: `cics-java-liberty-springboot-jdbc-app/target/cics-java-liberty-springboot-jdbc.war` +- CICS bundle ZIP: `cics-java-liberty-springboot-jdbc-cicsbundle/target/cics-java-liberty-springboot-jdbc-cicsbundle-1.0.0.zip` + +--- + +### Option 3: Building with Eclipse + +1. **Clone and Import Repository:** + - File → Import → Git → Projects from Git → Clone URI + - Enter the repository URL + - Ensure "Import existing Eclipse projects" box is checked + - Complete the wizard to clone and import the projects + +2. **Resolve Build Path (if needed):** + - Right-click project → Properties → Java Build Path → Libraries + - Add Library → CICS with Enterprise Java and Liberty + - Select appropriate CICS and Java EE versions + +3. **Build:** + - Right-click `cics-java-liberty-springboot-jdbc` → Run As → Gradle Build (or Maven Build) + - Goals: `clean build` (Gradle) or `clean package` (Maven) + +**Tip:** If switching between Gradle and Maven in Eclipse, you may need to remove duplicate "Project Dependencies" entries from the build path. + +--- + +## Deploying to CICS + +### Method 1: CICS Bundle Deployment (Gradle/Maven) + +1. **Build the bundle** (see [Building the Sample](#building-the-sample)) + +2. **Upload the bundle ZIP to z/OS:** + ```bash + # Upload the ZIP file to zFS + scp cics-java-liberty-springboot-jdbc-cicsbundle/build/distributions/cics-java-liberty-springboot-jdbc-cicsbundle-1.0.0.zip user@zos:/path/to/bundles/ + ``` + + **Note:** `scp` is a standard Unix/Linux command for secure file transfer. Replace `user@zos` with your z/OS credentials and `/path/to/bundles/` with your target directory. + +3. **Extract on z/OS:** + ```bash + cd /path/to/bundles + jar xf cics-java-liberty-springboot-jdbc-cicsbundle-1.0.0.zip + ``` + +4. **Define and install the bundle in CICS:** + + See [Common Bundle Installation Steps](#common-bundle-installation-steps) below. + +--- + +### Method 2: CICS Explorer Deployment + +This method uses IBM CICS Explorer (an Eclipse-based IDE) to create a CICS bundle and deploy it directly to z/OS. This approach is ideal for developers who prefer a GUI-based deployment workflow and want integrated tooling for CICS development. + +**Prerequisites:** +- IBM CICS Explorer installed and connected to your z/OS system +- SSH/SFTP access to z/OS UNIX System Services (USS) +- CICS region configured and running + +#### Step 1: Review CICS Bundle Project in Eclipse + +A CICS bundle is a deployment package that can contain multiple resources (WARs, JARs, OSGi bundles, etc.) and their metadata. +The bundle project is already provided in the repository (imported when you cloned the repo). + +1. **Locate the Bundle Project:** + In Project Explorer, locate the imported bundle project + (e.g., cics-java-liberty-springboot-jdbc-cicsbundle). + + Look into the project to verify its structure and contents. + +2. **Verify WAR Bundle Part Configuration:** + - Locate the .warbundle file + - Confirm the following: + JVM server is correctly specified (e.g., DFHWLP) + WAR file path points to the correct application artifact + +#### Step 2: Export Bundle to z/OS UNIX File System (zFS) + +This step deploys your bundle to z/OS and makes it available to CICS. + +1. **Initiate Export:** + - In **Project Explorer**, right-click on your bundle project + - Select **Export Bundle Project to z/OS UNIX File System** + - Click **Next** + +2. **Specify Bundle Deployment Location:** -- Deployment option 2: - - Manually upload the WAR file to zFS and add an `` element to the Liberty server.xml to define the web application with access to all authenticated users. For example the following application element can be used to install a WAR, and grant access to all authenticated users if security is enabled. - -``` XML - - - - - - + Choose where on z/OS to deploy the bundle: + - **Target directory**: `/u/cicsts/bundles/cics-java-liberty-springboot-jdbc-cicsbundle_1.0.0` + + **Important Path Considerations:** + - The directory will be created if it doesn't exist + + Click **Finish** to start the export. + + Ensure that the CICS region user has read and write access to the bundle directory structure. + +#### Step 3: Define and Install the Bundle in CICS + + After export, define and install the bundle in your CICS region. See [Common Bundle Installation Steps](#common-bundle-installation-steps) below. + +#### Step 4: Verify Deployment + +1. **Check Liberty Messages:** + - View Liberty server logs + - Look for: + ``` + [AUDIT ] CWWKT0016I: Web application available (default_host): + http://hostname:port/cics-java-liberty-springboot-jdbc/ + ``` + +2. **Verify in CICS Explorer:** + - Status should show: **Enabled** and **Installed** + +--- + +### Method 3: Direct Liberty Application Deployment + +1. **Upload the WAR file to zFS:** + + ```bash + # From your workstation (using secure copy) + scp cics-java-liberty-springboot-jdbc-app/build/libs/cics-java-liberty-springboot-jdbc.war user@zos:/path/to/apps/ + ``` + + **Note:** Replace `user@zos` with your z/OS credentials and `/path/to/liberty/apps/` with your Liberty apps directory. + +2. **Add to Liberty server.xml:** + ```xml + + + + + + + ``` + +3. **Restart or refresh the Liberty server** + +--- + +### Common Bundle Installation Steps + +These steps apply to both Method 1 and Method 2 after the bundle is on z/OS. + +**Option A: Using CEDA Commands** + +1. **Define the Bundle:** + ``` + CEDA DEFINE BUNDLE(JDBCBNDL) + GROUP(MYGROUP) + BUNDLEDIR(/u/cicsts/bundles/cics-java-liberty-springboot-jdbc-cicsbundle-1.0.0) + STATUS(ENABLED) + ``` + +2. **Install the Bundle:** + ``` + CEDA INSTALL BUNDLE(JDBCBNDL) GROUP(MYGROUP) + ``` + +3. **Enable (if needed):** + ``` + CEDA SET BUNDLE(JDBCBNDL) ENABLED + ``` + +**Option B: Using CICS Explorer UI** + +1. Navigate to **CICS SM** (Systems Management) view +2. Expand your CICS region → **Bundle Definitions** +3. Right-click → **New** → **Bundle Definition** +4. Fill in: + - Name: `JDBCBNDL` + - Group: `MYGROUP` + - Bundle Directory: `/u/cicsts/bundles/cics-java-liberty-springboot-jdbc-cicsbundle-1.0.0` + - Status: `Enabled` +5. Save and right-click → **Install** + +**Verify Installation:** +- Check Liberty messages.log for application startup +- In CICS Explorer: Bundle Definitions → `JDBCBNDL` should show **Enabled** and **Installed** + +--- + +## Running the Sample + +### Step 1: Verify Deployment + +Check that the application started successfully in Liberty: + +```bash +# Check Liberty messages.log +tail -f /path/to/liberty/logs/messages.log ``` -## Trying out the sample -1. Ensure the web application started successfully in Liberty by checking for msg `CWWKT0016I` in the Liberty messages.log: - - `A CWWKT0016I: Web application available (default_host): http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jdbc-0.1.0` - - `I SRVE0292I: Servlet Message - [cics-java-liberty-springboot-jdbc-0.1.0]:.Initializing Spring embedded WebApplicationContext` +Look for: +``` +CWWKT0016I: Web application available (default_host): http://host:port/cics-java-liberty-springboot-jdbc +``` -2. Copy the context root from message CWWKT0016I along with the REST service suffix into you web browser. For example display all the Employees from the EMP table: - - `http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jdbc-0.1.0/allEmployees` +--- + +### Step 2: Access the Application + +Open a web browser or use curl to access the application: + +**Root endpoint (usage information):** +``` +http://host:port/cics-java-liberty-springboot-jdbc/ +``` + +The browser will prompt for basic authentication. Enter a valid userid and password according to your Liberty security configuration. + +--- + +### Step 3: Try the REST Endpoints + +**Display all employees:** +```bash +curl -u userid:password "http://host:port/cics-java-liberty-springboot-jdbc/allEmployees" +``` + +**Display specific employee:** +```bash +curl -u userid:password "http://host:port/cics-java-liberty-springboot-jdbc/listEmployee/000100" +``` + +--- + +**Note:** For XA transactions to work properly, ensure your datasource is configured with `type="javax.sql.XADataSource"` in server.xml. + +--- + +## Troubleshooting + +### Issue: Application fails to start + +**Symptom:** +``` +CWWKZ0002E: An exception occurred while starting the application cics-java-liberty-springboot-jdbc +``` + +**Possible Causes & Solutions:** + +1. **Missing Liberty features:** + - Verify `servlet-6.0` (or `servlet-4.0`), `pages-3.1`, and `jdbc-4.3` are in server.xml + - Check Liberty messages.log for feature-related errors + +2. **Java version mismatch:** + - Spring Boot 3.x requires Java 17 or later + - Update JAVA_HOME if necessary + +3. **Datasource not found:** + - Verify JNDI name in application.properties matches server.xml + - Check that datasource is defined in server.xml + +--- + +### Issue: Database connection fails + +**Symptom:** +``` +SQLException: Connection refused +``` +or +``` +DB2 SQL Error: SQLCODE=-204, SQLSTATE=42704 +``` + +**Solutions:** + +1. **For Type 2 connectivity:** + - Verify DB2CONN is installed in CICS: `CEMT INQ DB2CONN` + - Check DB2CONN=YES in CICS SIT + - Verify Db2 load libraries in CICS region JCL + - Ensure CICS region has RACF authority to access Db2 + +2. **For Type 4 connectivity:** + - Verify network connectivity to Db2 server + - Verify user credentials + +3. **Schema/table not found (SQLCODE=-204):** + - Verify `currentSchema` in server.xml matches your Db2 schema + - Check that EMP table exists: `SELECT * FROM YOUR_SCHEMA.EMP` + - Verify user has SELECT/INSERT/UPDATE/DELETE privileges + +--- + +### Issue: Authentication fails + +**Symptom:** +``` +HTTP 401 Unauthorized +``` + +**Solutions:** + +1. **CICS security not configured:** + - Verify SEC=YES in CICS SIT + - Check that `cicsts:security-1.0` feature is in server.xml + - Ensure user is defined in RACF/security manager + +2. **Liberty security configuration:** + - Verify `` section in server.xml + - Check that user has appropriate CICS transaction authority + - Review Liberty security logs + +--- + +### Issue: Transactional operations fail + +**Symptom:** +``` +Transaction rolled back +``` +or +``` +XA transaction error +``` + +**Solutions:** + +1. **Datasource not configured for XA:** + - Change datasource type to `javax.sql.XADataSource` in server.xml + - For Type 2: Use `transactional="true"` + +--- + +### Logging and Diagnostics + +**Enable detailed logging in server.xml:** +```xml + +``` + +**Check logs:** +```bash +# Liberty messages.log +tail -f /path/to/liberty/logs/messages.log + +# CICS MSGUSR +# Check for CICS-related messages +``` +--- - The browser will prompt for basic authentication. Enter a valid userid and password - according to the configured registry for your target Liberty JVM server. - -3. For more information on how to use this sample, request the context root: - - `http://myzos.mycompany.com:httpPort/cics-java-liberty-springboot-jdbc-0.1.0/` - ## License -This project is licensed under [Eclipse Public License - v 2.0](LICENSE). + +This project is licensed under the [Eclipse Public License - v 2.0](LICENSE). + +### Usage Terms + +By downloading, installing, and/or using this sample, you acknowledge that separate license terms may apply to any dependencies that might be required as part of the installation and/or execution and/or automated build of the sample, including the following IBM license terms for relevant IBM components: + +• IBM CICS development components terms: https://www.ibm.com/support/customer/csol/terms/?id=L-ACRR-BBZLGX + +--- + +## Additional Resources + +- [CICS TS Documentation](https://www.ibm.com/docs/en/cics-ts) +- [WebSphere Liberty Documentation](https://www.ibm.com/docs/en/was-liberty) +- [Spring Boot Documentation](https://spring.io/projects/spring-boot) +- [Spring Data JDBC Documentation](https://spring.io/projects/spring-data-jdbc) +- [IBM Db2 for z/OS Documentation](https://www.ibm.com/docs/en/db2-for-zos) +- [IBM Tutorial: Spring Boot Java applications for CICS, Part 4: JDBC](https://developer.ibm.com/tutorials/spring-boot-java-applications-for-cics-part-4-jdbc/) + +--- + +## Contributing + +This is a sample project maintained by IBM CICS development. For issues or questions: +- Open an issue on GitHub +- Contact IBM Support for CICS-related questions + +--- diff --git a/cics-java-liberty-springboot-jdbc-app/.settings/org.eclipse.wst.common.component b/cics-java-liberty-springboot-jdbc-app/.settings/org.eclipse.wst.common.component index 53bd5e8..a41f672 100644 --- a/cics-java-liberty-springboot-jdbc-app/.settings/org.eclipse.wst.common.component +++ b/cics-java-liberty-springboot-jdbc-app/.settings/org.eclipse.wst.common.component @@ -1,23 +1,9 @@ - - - - - - - - - - - - - - - - - - - - - - + + + + + + + +