Skip to content

Commit 3192da6

Browse files
AaronJhajAaronJhaj
committed
initial commit
1 parent 646ab26 commit 3192da6

Some content is hidden

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

46 files changed

+1562
-8
lines changed

‎.gitignore

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Maven ignores
2+
target/
3+
pom.xml.tag
4+
pom.xml.releaseBackup
5+
pom.xml.versionsBackup
6+
pom.xml.next
7+
release.properties
8+
dependency-reduced-pom.xml
9+
buildNumber.properties
10+
.mvn/timing.properties
11+
# https://github.com/takari/maven-wrapper#usage-without-binary-jar
12+
.mvn/wrapper/maven-wrapper.jar
13+
14+
# Eclipse m2e generated files
15+
# Eclipse Core
16+
#.project
17+
# JDT-specific (Eclipse Java Development Tools)
18+
#.classpath
19+
20+
21+
# Gradle ignores
22+
.gradle
23+
**/build/
24+
!src/**/build/
25+
26+
# Ignore Gradle GUI config
27+
gradle-app.setting
28+
29+
# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
30+
!gradle-wrapper.jar
31+
32+
# Avoid ignore Gradle wrappper properties
33+
!gradle-wrapper.properties
34+
35+
# Cache of project
36+
.gradletasknamecache
37+
38+
# Eclipse Gradle plugin generated files
39+
# Eclipse Core
40+
#.project
41+
# JDT-specific (Eclipse Java Development Tools)
42+
#.classpath
43+
44+
45+
# Java ignores
46+
# Compiled class file
47+
*.class
48+
49+
# Log file
50+
*.log
51+
52+
# BlueJ files
53+
*.ctxt
54+
55+
# Mobile Tools for Java (J2ME)
56+
.mtj.tmp/
57+
58+
# Package Files #
59+
*.jar
60+
*.war
61+
*.nar
62+
*.ear
63+
*.zip
64+
*.tar.gz
65+
*.rar
66+
67+
# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
68+
hs_err_pid*
69+
replay_pid*
70+
71+
72+
# VSCode ignores
73+
.vscode/*
74+
!.vscode/settings.json
75+
!.vscode/tasks.json
76+
!.vscode/launch.json
77+
!.vscode/extensions.json
78+
!.vscode/*.code-snippets
79+
80+
# Local History for Visual Studio Code
81+
.history/
82+
83+
# Built Visual Studio Code Extensions
84+
*.vsix

‎.project

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<projectDescription>
3+
<name>cics-java-osgi-hello</name>
4+
<comment></comment>
5+
<projects>
6+
</projects>
7+
<buildSpec>
8+
<buildCommand>
9+
<name>org.eclipse.buildship.core.gradleprojectbuilder</name>
10+
<arguments>
11+
</arguments>
12+
</buildCommand>
13+
<buildCommand>
14+
<name>org.eclipse.m2e.core.maven2Builder</name>
15+
<arguments>
16+
</arguments>
17+
</buildCommand>
18+
</buildSpec>
19+
<natures>
20+
<nature>org.eclipse.m2e.core.maven2Nature</nature>
21+
<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
22+
</natures>
23+
</projectDescription>

‎.settings/org.eclipse.buildship.core.prefs

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
arguments=
2+
auto.sync=false
3+
build.scans.enabled=false
4+
connection.gradle.distribution=GRADLE_DISTRIBUTION(WRAPPER)
5+
connection.project.dir=
6+
eclipse.preferences.version=1
7+
gradle.user.home=
8+
java.home=
9+
jvm.arguments=
10+
offline.mode=false
11+
override.workspace.settings=false
12+
show.console.view=true
13+
show.executions.view=true

‎.settings/org.eclipse.core.resources.prefs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
eclipse.preferences.version=1
2+
encoding/<project>=UTF-8

‎MAINTAINERS.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Maintainers
2+
3+
- Aaron Jhaj [@AaronJhaj](https://github.com/AaronJhaj)
4+
5+
*Last reviewed:* June 2025

‎README.md

Lines changed: 169 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,178 @@
1-
# CICS OSGi Java Hello application
1+
# CICS OSGi Hello sample application
22

3-
This sample demonstrates a simple Hello World Java application running in a CICS OSGi JVM Server.
3+
A simple Hello World CICS Java application running in a CICS OSGi JVM server.
44

5-
## Versions
6-
| CICS TS for z/OS Version | Branch | Minimum Java Version | Build Status |
7-
|--------------------------|----------------------------------------|----------------------|--------------|
8-
| 5.5, 5.6 | [cicsts/v5.5](/../../tree/cicsts/v5.5) | 8 | [![Build](https://github.com/cicsdev/cics-java-osgi-hello/actions/workflows/java.yaml/badge.svg?branch=cicsts%2Fv5.5)](https://github.com/cicsdev/cics-java-osgi-hello/actions/workflows/java.yaml) |
9-
| 6.1 | [cicsts/v6.1](/../../tree/cicsts/v6.1) | 17 | [![Build](https://github.com/cicsdev/cics-java-osgi-hello/actions/workflows/java.yaml/badge.svg?branch=cicsts%2Fv6.1)](https://github.com/cicsdev/cics-java-osgi-hello/actions/workflows/java.yaml) |
5+
6+
## Downloading
7+
8+
- Clone the repository using your IDEs support, such as the Eclipse Git plugin
9+
- **or**, download the sample as a [ZIP](https://github.com/cicsdev/cics-java-osgi-hello/archive/cicsts/v5.5.zip) and unzip onto the workstation
10+
11+
> [!TIP]
12+
> Eclipse Git provides an 'Import existing Projects' check-box when cloning a repository.
13+
14+
---
15+
16+
## Repository structure
17+
* [`cics-java-osgi-hello/`](/) - Top-level project
18+
* [`cics-java-osgi-hello-app/`](cics-java-osgi-hello-app) - Java application source
19+
* [`cics-java-osgi-hello-bundle/`](cics-java-osgi-hello-bundle/) - Build files for CICS bundle project
20+
* [`etc/eclipse_projects/com.ibm.cics.server.examples.osgi.hello.bundle`](etc/eclipse_projects/com.ibm.cics.server.examples.osgi.hello.bundle) - Static CICS Bundle Project
21+
22+
23+
## Building
24+
The sample includes an Eclipse project configuration, a Gradle build, a Maven POM, and Gradle/Maven Wrappers offering a wide range of build options with the tooling and IDE of your choice.
25+
26+
Choose from the following approach:
27+
* Use the built-in Eclipse and CICS Explorer SDK capability
28+
* Use Eclipse with Buildship (Gradle), or m2e (Maven) to drive Gradle, or Maven.
29+
* Use the command line, or IDE terminal, to drive Gradle or Apache Maven (if installed on your workstation)
30+
* Use the command line, or IDE terminal, or IDE support for Wrappers, to drive the supplied Gradle or Apache Maven Wrappers (with no requirement for Gradle, Maven, Eclipse, or CICS Explorer SDK to be installed)
31+
32+
33+
** Note: ** If you import the project to your IDE, you might experience local project compile errors. To resolve these errors follow the relevant build section below.
34+
35+
36+
### Option 1 - Building with Eclipse
37+
38+
The sample comes pre-configured for use with a standard JDK 1.8 and the CICS TS V5.5 Java EE 7 Target Platform. 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 with the correct 'target platform' set, you might experience local project compile errors.
39+
40+
To resolve issues:
41+
* ensure you have the CICS Explorer SDK plug-in installed
42+
* configure the Project's build-path, and Application Project settings to use your preferred JDK and Java compiler settings
43+
* set the CICS TS Target Platform to your intended CICS target (Hint: Window | Preferences | Plug-in Development | Target Platform | Add | Template | Other...)
44+
45+
46+
### Option 2 - Building with Gradle
47+
48+
You don't necessarily need to fix the local errors, but to do so, you can run a tooling refresh on the cics-java-osgi-hello-app project. For example, in Eclipse: right-click on "Project", select "Gradle | Refresh Gradle Project".
49+
50+
The CICS JVM server name should be modified in the `cics.jvmserver` property in the gradle build [cics-java-osgi-hello-bundle/build.gradle](cics-java-osgi-hello-bundle/build.gradle) to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line (see below).
51+
52+
If you have the Gradle buildship plug-in available, use the right-click **Run As...** menu on the cics-java-osgi-hello project to configure and run the `clean` and `build` tasks. Otherwise choose from the command-line approaches.
53+
54+
**Gradle Wrapper (Linux/Mac):**
55+
```shell
56+
./gradlew clean build
57+
```
58+
59+
**Gradle Wrapper (Windows):**
60+
```shell
61+
gradle.bat clean build
62+
```
63+
64+
**Gradle (command-line):**
65+
```shell
66+
gradle clean build
67+
```
68+
69+
**Gradle (command-line & setting jvmserver):**
70+
```shell
71+
gradle clean build -Pcics.jvmserver=MYJVM
72+
```
73+
74+
A JAR file is created inside the `cics-java-osgi-hello-app/build/libs/` directory and a CICS bundle ZIP file inside the `cics-java-osgi-hello-bundle/build/distributions` directory.
75+
76+
77+
### Option 3 - Building with Apache Maven
78+
79+
You don't necessarily need to fix the local errors, but to do so, you can run a tooling refresh on the cics-java-osgi-hello-app project. For example, in Eclipse: right-click on "Project", select "Maven -> Update Project...".
80+
81+
> [!TIP]
82+
> 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 or with the CICS Explorer SDK Java Libraries, 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.
83+
84+
The CICS JVM server name should be modified in the `<cics.jvmserver>` property in the [`pom.xml`](pom.xml) to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line (see below).
85+
86+
If you have the Maven m2e plug-in available, use the right-click **Run As...** menu on the cics-java-osgi-hello project to configure and run the `clean` and `verify` tasks. Otherwise choose from the command-line approaches.
87+
88+
**Maven Wrapper (Linux/Mac):**
89+
```shell
90+
./mvnw clean verify
91+
```
92+
93+
**Maven Wrapper (Windows):**
94+
```shell
95+
mvnw.cmd clean verify
96+
```
97+
98+
**Maven (command-line):**
99+
```shell
100+
mvn clean verify
101+
```
102+
103+
**Maven (command-line & setting jvmserver):**
104+
```shell
105+
mvn clean verify -Dcics.jvmserver=MYJVM
106+
```
107+
108+
A JAR file is created inside the `cics-java-osgi-hello-app/target` directory and a CICS bundle ZIP file inside the `cics-java-osgi-hello-bundle/target` directory.
109+
110+
---
111+
112+
## Deploying to CICS
113+
1. Configure an OSGi JVMSERVER.
114+
115+
2. CICS resource definitions for the bundle, programs, transactions and a JVM server are supplied in a group CDEVCJOH as a DFHCSDUP sample input stream supplied in [`DFHCSD.txt`](etc/DFHCSD.txt). Alternatively they can be installed using the bundle parts supplied with the cics-java-osgi-hello-bundle project.
116+
117+
118+
### Option 1 - Deploying using CICS Explorer SDK and the provided CICS bundle project
119+
1. Deploy the CICS bundle project 'com.ibm.cics.server.examples.osgi.hello.bundle' from CICS Explorer using the **Export Bundle Project to z/OS UNIX File System** wizard. This CICS bundle includes the OSGi bundlepart, the CJOH transaction and the CDEVCJOH program to run the sample.
120+
121+
122+
### Option 2 - Deploying using CICS Explorer SDK with own CICS bundle project
123+
1. Copy and paste the built JAR from your *projects/cics-java-osgi-hello-app/target* or *projects/cics-java-osgi-hello-app/build/libs* directory into a new Eclipse CICS bundle project.
124+
2. Create a new OSGi bundlepart that references the JAR (OSGi bundle) file.
125+
3. Optionally customise the CICS bundle contents, perhaps adding a TRANDEF of your choice
126+
4. Right click using the ** Export Bundle Project to z/OS UNIX File System ** wizard.
127+
128+
129+
### Option 3 - Deploying using CICS Explorer (Remote System Explorer) and CICS Bundle ZIP
130+
1. Connect to USS on the host system
131+
2. Create the bundle directory for the project.
132+
3. Copy & paste the built CICS bundle ZIP file from your *projects/cics-java-osgi-hello-bundle/target* or *projects/cics-java-osgi-hello-bundle/build/distributions* directory to z/FS on the host system into the bundle directory.
133+
4. Extract the ZIP by right-clicking on the ZIP file > User Action > unjar...
134+
5. Refresh the bundle directory
135+
136+
137+
### Option 4 - Deploying using command line tools
138+
1. Upload the built CICS bundle ZIP file from your *projects/cics-java-osgi-hello-bundle/target* or *projects/cics-java-osgi-hello-bundle/build/distributions* directory to z/FS on the host system (e.g. FTP).
139+
2. Connect to USS on the host system (e.g. SSH).
140+
3. Create the bundle directory for the project.
141+
4. Move the CICS bundle ZIP file into the bundle directory.
142+
5. Change directory into the bundle directoy.
143+
6. Extract the CICS bundle ZIP file. This can be done using the `jar` command. For example:
144+
```shell
145+
jar xf file.zip
146+
```
147+
148+
---
149+
150+
## Installing the CICS bundle
151+
### Installing the CICS bundle from a CICS terminal
152+
1. Create a new bundle definition, setting the bundle directory to the deployed bundle directory:
153+
```
154+
BUNDLE(CDEVCJOH) GROUP(CDEVCJOH) BUNDLEDIR(/path/to/bundle/directory)
155+
```
156+
2. Install the bundle
157+
158+
159+
### Installing the CICS bundle with CICS Explorer
160+
1. Definitions > Bundle Definitions
161+
2. Right-click > New...
162+
3. Fill in the Bundle and Group names as `CDEVCJOH`
163+
4. Fill in the Bundle Directory to point to the directory you expanded the ZIP
164+
5. Install the bundle
165+
166+
---
167+
168+
169+
## Running
170+
Run the `CJOH` transaction. This runs the `CDEVCJOH` program.
10171

11172
## License
12173
This project is licensed under [Eclipse Public License - v 2.0](LICENSE).
13174

14175
## Usage terms
15176
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:
16177

17-
• IBM CICS development components terms: https://www.ibm.com/support/customer/csol/terms/?id=L-ACRR-BBZLGX
178+
• IBM CICS development components terms: https://www.ibm.com/support/customer/csol/terms/?id=L-ACRR-BBZLGX

‎build.gradle

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
2+
allprojects {
3+
group = 'com.ibm.cicsdev'
4+
version = '1.0.0'
5+
6+
repositories {
7+
mavenCentral()
8+
}
9+
}
10+
11+
description = 'CICS OSGi hello application'

‎cics-java-osgi-hello-app/.classpath

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<classpath>
3+
<classpathentry kind="src" path="src/main/java"/>
4+
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-17/">
5+
<attributes>
6+
<attribute name="module" value="true"/>
7+
</attributes>
8+
</classpathentry>
9+
<classpathentry kind="src" path=".apt_generated">
10+
<attributes>
11+
<attribute name="optional" value="true"/>
12+
</attributes>
13+
</classpathentry>
14+
<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
15+
<classpathentry kind="output" path="bin/"/>
16+
</classpath>

‎cics-java-osgi-hello-app/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/bin/
2+
/.apt_generated/

‎cics-java-osgi-hello-app/.project

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<projectDescription>
3+
<name>cics-java-osgi-hello-app</name>
4+
<comment></comment>
5+
<projects>
6+
</projects>
7+
<buildSpec>
8+
<buildCommand>
9+
<name>org.eclipse.jdt.core.javabuilder</name>
10+
<arguments>
11+
</arguments>
12+
</buildCommand>
13+
<buildCommand>
14+
<name>org.eclipse.buildship.core.gradleprojectbuilder</name>
15+
<arguments>
16+
</arguments>
17+
</buildCommand>
18+
<buildCommand>
19+
<name>org.eclipse.m2e.core.maven2Builder</name>
20+
<arguments>
21+
</arguments>
22+
</buildCommand>
23+
<buildCommand>
24+
<name>org.eclipse.pde.ManifestBuilder</name>
25+
<arguments>
26+
</arguments>
27+
</buildCommand>
28+
<buildCommand>
29+
<name>org.eclipse.pde.SchemaBuilder</name>
30+
<arguments>
31+
</arguments>
32+
</buildCommand>
33+
</buildSpec>
34+
<natures>
35+
<nature>org.eclipse.jdt.core.javanature</nature>
36+
<nature>org.eclipse.m2e.core.maven2Nature</nature>
37+
<nature>org.eclipse.pde.PluginNature</nature>
38+
<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
39+
</natures>
40+
</projectDescription>

0 commit comments

Comments
 (0)