diff --git a/.gitignore b/.gitignore index 3716441..90d7b92 100644 --- a/.gitignore +++ b/.gitignore @@ -11,11 +11,8 @@ buildNumber.properties # https://github.com/takari/maven-wrapper#usage-without-binary-jar .mvn/wrapper/maven-wrapper.jar -# Eclipse m2e generated files -# Eclipse Core -#.project -# JDT-specific (Eclipse Java Development Tools) -#.classpath +# Eclipse files +bin/* # Gradle ignores @@ -35,13 +32,6 @@ gradle-app.setting # Cache of project .gradletasknamecache -# Eclipse Gradle plugin generated files -# Eclipse Core -#.project -# JDT-specific (Eclipse Java Development Tools) -#.classpath - - # Java ignores # Compiled class file *.class diff --git a/.project b/.project index 5f86624..1182948 100644 --- a/.project +++ b/.project @@ -10,11 +10,6 @@ - - org.eclipse.jdt.core.javabuilder - - - org.eclipse.wst.common.project.facet.core.builder @@ -33,7 +28,6 @@ org.eclipse.m2e.core.maven2Nature - org.eclipse.jdt.core.javanature org.eclipse.wst.common.project.facet.core.nature org.eclipse.wst.common.modulecore.ModuleCoreNature org.eclipse.jem.workbench.JavaEMFNature diff --git a/README.md b/README.md index 4ddf570..8a8d467 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,7 @@ The following Java source components are supplied in the [`cics-java-liberty-res - [cics-java-liberty-restapp](./cics-java-liberty-restapp) - Top-level project. - [cics-java-liberty-restapp-app](./cics-java-liberty-restapp-app) - Application source code. -- [cics-java-liberty-restapp-bundle](./cics-java-liberty-restapp-bundle) - CICS bundle plug-in based project. Use with Gradle and Maven builds. -- [etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle](./etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle) - CICS Explorer based CICS bundle project, contains Web application bundle-part. Use with CICS Explorer 'Export to zFS' deployment capability. +- [cics-java-liberty-restapp-bundle](./cics-java-liberty-restapp-bundle) - CICS bundle project. Use with Gradle and Maven builds or as a Eclipse CICS Bundle project. ## Prerequisites @@ -36,8 +35,8 @@ The following Java source components are supplied in the [`cics-java-liberty-res - Java SE 1.8 or later on the workstation - One of the following on your workstation: - Eclipse with the IBM CICS SDK for Java EE, Jakarta EE and Liberty - - An IDE of your choice that supports Gradle or Maven (or can run the Wrappers) - - A command line, to run the Wrappers or to invoke a locally installed version of Gradle or Maven + - An IDE of your choice that supports Gradle or Maven + - A command line, to run Gradle or Maven ## Supporting files * [`DFHCSD.txt`](etc/DFHCSD.txt) - DFHCSDUP sample input stream for the CICS BUNDLE resource definition. @@ -48,41 +47,30 @@ The following Java source components are supplied in the [`cics-java-liberty-res ## Downloading -- Clone the repository using your IDEs support, such as the Eclipse Git plugin -- **or**, download the sample as a [ZIP](https://github.com/cicsdev/cics-java-liberty-restapp/archive/main.zip) and unzip onto the workstation +- Download the sample as a [ZIP](archive/refs/heads/main.zip) and unzip onto the workstation or clone the repository using a git client. -> [!TIP] -> Eclipse Git provides an 'Import existing Projects' check-box when cloning a repository. ## Building -You can build the sample in a variety of ways: -- Using the implicit compile/build of the Eclipse based CICS Explorer SDK -- Using the built-in Gradle or Maven support of your IDE (For example: *buildship* or *m2e* in Eclipse which integrate with the "Run As..." menu.) -- Using the supplied Gradle or Maven Wrapper scripts (no requirement for an IDE or Gradle/Maven install) -- or you can build it from the command line if you have Gradle or Maven installed on your workstation - -> [!IMPORTANT] -> The sample comes pre-configured for use with a JDK 1.8 and CICS TS V5.5 Libraries for Java EE & Jakarta EE 8. When you initially import the project to your IDE, if your IDE is not configured for a JDK 1.8, or does not have CICS Explorer SDK installed, you might experience local project compile errors. To resolve issues you should configure the Project's build-path to add/remove your preferred combination of CICS TS, JDK, and Liberty's Enterprise Java libraries (Java EE or Jakarta EE). Resolving errors might also depend on how you wish to build and deploy the sample. If you are building and deploying through CICS Explorer SDK and 'Export to zFS' you should edit the link-app's Project properties. Select 'Java Build Path', on the Libraries tab select 'Classpath', click 'Add Library', select 'CICS with Enterprise Java and Liberty' Library, and choose the appropriate CICS and Enterprise Java versions. -If you are building and deploying with Gradle or Maven then you don't necessarily need to fix the local errors, but to do so, you can do as above, or you can run a tooling refresh on the hello-web project. For example, in Eclipse: right-click on "Project", select "Gradle -> Refresh Gradle Project", **or** right-click on "Project", select "Maven -> Update Project...". +The sample includes an Eclipse project configuration, a Gradle build, a Maven POM, Gradle/Maven Wrappers and Eclipse Gradle and Maven project natures offering a wide range of build options with the tooling and IDE of your choice. -> [!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. +Choose from the following 2 main approaches: +1. Use the command line to drive the supplied Gradle or Apache Maven Wrappers, this means there is no requirement for Gradle, Maven, Eclipse, or CICS Explorer SDK to be installed. +1. Use the CICS Explorer SDK capability to build the application in Eclipse. -### Option 1: Building with Eclipse + -If you are using the Egit client to clone the repo, remember to tick the button to import all projects. Otherwise, you should manually Import the projects into CICS Explorer using File → Import → General → Existing projects into workspace, then follow the error resolution advice above. +> [!IMPORTANT] +> The sample comes pre-configured for use with a JDK 1.8 and CICS TS V5.5 Libraries for Java EE & Jakarta EE 8. When you initially import the project to your IDE, if your IDE is not configured for a JDK 1.8, or does not have CICS Explorer SDK installed, you might experience local project compile errors. +If you are building and deploying with Gradle or Maven then you don't necessarily need to fix the local Eclipse build problems as the build files are used to build the sample. -### Option 2: Building with Gradle -For a complete build you should run the settings.gradle file in the top-level 'cics-java-liberty-restapp' directory which is designed to invoke the individual build.gradle files for each project. -If successful, a WAR file is created inside the `cics-java-liberty-restapp-app/build/libs` directory and a CICS bundle ZIP file inside the `cics-java-liberty-restapp-bundle/build/distribution` directory. +### Option 1a: Building with Gradle -[!NOTE] -In Eclipse, the output 'build' directory is often hidden by default. From the Package Explorer pane, select the three dot menu, choose filters and un-check the Gradle build folder to view its contents. +The sample comes pre-configured with a Gradle wrapper and Gradle build files to facilitate automated builds. The `gradlew` command is used to invoke the wrapper and should be invoked from the top-level 'cics-java-liberty-restapp' directory which will then invoke the individual build.gradle files for each sub-project. The JVM server the CICS bundle is targeted at is controlled through the `cics.jvmserver` property, defined in the [`cics-java-liberty-restapp-bundle/build.gradle`](cics-java-liberty-restapp-bundle/build.gradle) file, or alternatively can be set on the command line: @@ -92,23 +80,23 @@ The JVM server the CICS bundle is targeted at is controlled through the `cics.jv ``` **Gradle Wrapper (Windows):** ```shell -gradle.bat clean build -``` -**Gradle (command-line):** -```shell -gradle clean build +gradlew.bat clean build ``` + **Gradle (command-line & setting jvmserver):** ```shell -gradle clean build -Pcics.jvmserver=MYJVM +gradlew clean build -Pcics.jvmserver=MYJVM ``` -### Option 3: Building with Apache Maven +If successful, a WAR file is created inside the `cics-java-liberty-restapp-app/build/libs` directory and a CICS bundle ZIP file inside the `cics-java-liberty-restapp-bundle/build/distribution` directory. + +### Option 1b: Building with Apache Maven -For a complete build you should run the pom.xml file in the top-level 'cics-java-liberty-hello' directory. A WAR file is created inside the `cics-java-liberty-restapp-app/target` directory and a CICS bundle ZIP file inside the `cics-java-liberty-restapp-bundle/target` directory. +The sample comes pre-configured with a Maven wrapper and Maven build files to facilitate automated builds. The `mvnw` command is used to invoke the wrapper and should be invoked from the top-level 'cics-java-liberty-restapp' directory which will then invoke the individual Maven `pom.xml` files for each sub-project. If building a CICS bundle ZIP the CICS JVM server name for the WAR bundle part should be modified in the - `cics.jvmserver` property, defined in [`cics-java-liberty-restapp-bundle/pom.xml`](cics-java-liberty-restapp-bundle/pom.xml) file under the `defaultjvmserver` configuration property, or alternatively can be set on the command line. + `cics.jvmserver` property, defined in [`cics-java-liberty-restapp-bundle/pom.xml`](cics-java-liberty-restapp-bundle/pom.xml) file under the `defaultjvmserver` configuration property, or alternatively can be set on the command line as shown. + **Maven Wrapper (Linux/Mac):** ```shell @@ -118,15 +106,23 @@ If building a CICS bundle ZIP the CICS JVM server name for the WAR bundle part s ```shell mvnw.cmd clean verify ``` -**Maven (command-line):** -```shell -mvn clean verify -``` -**Maven (command-line & setting jvmserver):** +**Maven wrapper (command-line & setting jvmserver):** ```shell -mvn clean verify -Dcics.jvmserver=MYJVM +mvnw clean verify -Dcics.jvmserver=MYJVM ``` +A WAR file is created inside the `cics-java-liberty-restapp-app/target` directory and a CICS bundle ZIP file inside the `cics-java-liberty-restapp-bundle/target` directory. + +### Option 2: Building with Eclipse + +Install the latest version of the IBM CICS Explorer [see](https://www.ibm.com/support/pages/cics-explorer-downloads) + +Import the projects into Eclipse using **File → Import → General → Existing projects into workspace → Select archive file** and select the downloaded zip as the archive. Ensure you select **Search for nested projects** and include the CICS Bundle project `com.ibm.cicsdev.wlp.restapp.cicsbundle`. + +To resolve build issues in Eclipse you should configure the application project's build-path to add your preferred combination of CICS TS, JDK, and Liberty's Enterprise Java libraries (Java EE or Jakarta EE). On the `cics-java-liberty-restapp-app` project select Select **Build Path → Configure Build Path → Java Build Path** then on the **Libraries** tab, click **Add Library CICS with Enterprise Java and Liberty** and choose the appropriate CICS and Enterprise Java versions. +If the project built correctly the Eclipse Problems view should no longer have any errors displayed. + + ## Deploying ### Configuring the Liberty JVM server @@ -135,30 +131,24 @@ mvn clean verify -Dcics.jvmserver=MYJVM 3. Add the `jaxrs-1.1` (or later version) Liberty feature to `server.xml` depending on your version of Java EE. -### Deploying CICS Bundles with CICS Explorer -1. Optionally, change the name of the JVMSERVER in the .warbundle file of the CICS bundle project from DFHWLP to the name of your JVMSERVER resource defined in CICS. -2. Export the bundle project to zFS by selecting 'Export Bundle project to z/OS Unix File System' from the context menu. -3. In CICS, create a bundle definition, setting the bundle directory attribute to the zFS location you just exported to, and install it. +### Deploying the CICS Bundle with CICS Explorer +1. First check the name of the JVMSERVER in the .warbundle file of the CICS bundle project (com.ibm.cicsdev.wlp.restapp.cicsbundle), and ensure this matches the name of your JVMSERVER resource defined in CICS. The default used is DFHWLP. +2. Export the CICS bundle project to zFS by selecting **Export Bundle project to z/OS Unix File System** from the context menu in Eclipse. The samples uses the directory `/u/cics1/com.ibm.cicsdev.restapp.bundle_1.0.0`. -### Deploying CICS Bundles from Gradle or Maven -1. Manually upload the ZIP file from the _cics-java-liberty-restapp-bundle/target_ or _cics-java-liberty-restapp-bundle/build/distributions_ directory to zFS. -2. Unzip this ZIP file on zFS (e.g. `${JAVA_HOME}/bin/jar xf /path/to/bundle.zip`). -3. Create a CICS BUNDLE resource definition, setting the bundle directory attribute to the zFS location you just extracted to, and install it into the CICS region. -### Deploying directly with Liberty's application configuration -1. Manually upload the WAR file from the _cics-java-liberty-restapp-app/target_ or _cics-java-liberty-restapp-app/build/libs_ directory to zFS. -2. Add an `` element to the Liberty server.xml to define the web application. +### Deploying the CICS Bundle from Gradle or Maven +1. Manually upload the ZIP file from the _cics-java-liberty-restapp-bundle/target_ or _cics-java-liberty-restapp-bundle/build/distributions_ directory to zFS. +2. Unzip this ZIP file on zFS (e.g. `${JAVA_HOME}/bin/jar -xvf /path/to/bundle.zip`). +3. Create a CICS BUNDLE resource definition, and install it into the CICS region. -### To deploy the samples into a CICS region: -1. Using the CICS Explorer export the CICS bundle project to a zFS directory. The samples use the directory `/u/cics1/com.ibm.cicsdev.restapp.cicsbundle_1.0.0`. -1. Create a CICS BUNDLE definition. -1. Install the CICS BUNDLE resource. +### To install the sample into a CICS region: +1. Check the JVM server is in the `Enabled` state. 1. Download and compile the supplied COBOL program `EDUCHAN` and deploy into CICS. +1. Create a CICS BUNDLE definition, an example for usage with the DFHCSDUP utility is provided in [DFHCSD.txt](etc/DFHCSD.txt) file. Ensure you set the bundle directory attribute to the zFS location you previously deployed the bundle proejct to. +1. Install the CICS BUNDLE resource into CICS and ensure it becomes enabled. -**Note:** A sample DFHCSDUP input file for the required CICS BUNDLE resource definition is supplied in the supporting file [DFHCSD.txt](etc/DFHCSD.txt) file. - ## Running the Sample diff --git a/cics-java-liberty-restapp-app/.project b/cics-java-liberty-restapp-app/.project index 4451f29..00195d7 100644 --- a/cics-java-liberty-restapp-app/.project +++ b/cics-java-liberty-restapp-app/.project @@ -20,23 +20,11 @@ - - org.eclipse.buildship.core.gradleprojectbuilder - - - - - org.eclipse.m2e.core.maven2Builder - - - org.eclipse.jdt.core.javanature org.eclipse.wst.common.project.facet.core.nature org.eclipse.wst.common.modulecore.ModuleCoreNature org.eclipse.jem.workbench.JavaEMFNature - org.eclipse.buildship.core.gradleprojectnature - org.eclipse.m2e.core.maven2Nature diff --git a/cics-java-liberty-restapp-bundle/.project b/cics-java-liberty-restapp-bundle/.project index 8580d80..37081a8 100644 --- a/cics-java-liberty-restapp-bundle/.project +++ b/cics-java-liberty-restapp-bundle/.project @@ -6,18 +6,28 @@ - org.eclipse.buildship.core.gradleprojectbuilder - - - - - org.eclipse.m2e.core.maven2Builder + com.ibm.cics.bundle.ui.bundlebuilder + + bundleID + com.ibm.cicsdev.restapp.bundle + + + majorVersion + 1 + + + microVersion + 0 + + + minorVersion + 0 + - org.eclipse.m2e.core.maven2Nature - org.eclipse.buildship.core.gradleprojectnature + com.ibm.cics.bundle.ui.bundlenature diff --git a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs b/cics-java-liberty-restapp-bundle/.settings/org.eclipse.core.resources.prefs similarity index 53% rename from etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs rename to cics-java-liberty-restapp-bundle/.settings/org.eclipse.core.resources.prefs index 8ddaf77..a0137e2 100644 --- a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.settings/org.eclipse.core.resources.prefs +++ b/cics-java-liberty-restapp-bundle/.settings/org.eclipse.core.resources.prefs @@ -1,2 +1,3 @@ eclipse.preferences.version=1 encoding//META-INF/cics.xml=UTF-8 +encoding/cics-java-liberty-restapp-app.warbundle=UTF-8 diff --git a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml b/cics-java-liberty-restapp-bundle/META-INF/cics.xml similarity index 61% rename from etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml rename to cics-java-liberty-restapp-bundle/META-INF/cics.xml index 0983976..716458d 100644 --- a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/META-INF/cics.xml +++ b/cics-java-liberty-restapp-bundle/META-INF/cics.xml @@ -1,7 +1,7 @@ - + - 2025-09-02T15:13:21.573Z + 2026-03-31T16:50:19.618+01:00 diff --git a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/cics-java-liberty-restapp-app.warbundle b/cics-java-liberty-restapp-bundle/cics-java-liberty-restapp-app.warbundle similarity index 100% rename from etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/cics-java-liberty-restapp-app.warbundle rename to cics-java-liberty-restapp-bundle/cics-java-liberty-restapp-app.warbundle diff --git a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project b/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project deleted file mode 100644 index 04b3722..0000000 --- a/etc/eclipse_projects/com.ibm.cicsdev.wlp.restapp.cicsbundle/.project +++ /dev/null @@ -1,33 +0,0 @@ - - - com.ibm.cicsdev.wlp.restapp.cicsbundle - - - - - - com.ibm.cics.bundle.ui.bundlebuilder - - - bundleID - com.ibm.cics.server.examples.wlp.link.bundle - - - majorVersion - - - - microVersion - - - - minorVersion - - - - - - - com.ibm.cics.bundle.ui.bundlenature - - \ No newline at end of file