revert unwanted changes

Author: AaronJhaj

.gitignore

@@ -13,9 +13,9 @@ buildNumber.properties
 
 # Eclipse m2e generated files
 # Eclipse Core
-.project
+#.project
 # JDT-specific (Eclipse Java Development Tools)
-.classpath
+#.classpath
 
 
 # Gradle ignores
@@ -37,9 +37,9 @@ gradle-app.setting
 
 # Eclipse Gradle plugin generated files
 # Eclipse Core
-.project
+#.project
 # JDT-specific (Eclipse Java Development Tools)
-.classpath
+#.classpath
 
 
 # Java ignores

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

@@ -0,0 +1,13 @@
+arguments=
+auto.sync=false
+build.scans.enabled=false
+connection.gradle.distribution=GRADLE_DISTRIBUTION(WRAPPER)
+connection.project.dir=cics-java-osgi-link-app
+eclipse.preferences.version=1
+gradle.user.home=
+java.home=
+jvm.arguments=
+offline.mode=false
+override.workspace.settings=false
+show.console.view=false
+show.executions.view=false

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

@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+encoding/<project>=UTF-8

.settings/org.eclipse.jdt.core.prefs

@@ -0,0 +1,15 @@
+eclipse.preferences.version=1
+org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
+org.eclipse.jdt.core.compiler.codegen.methodParameters=do not generate
+org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.8
+org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
+org.eclipse.jdt.core.compiler.compliance=1.8
+org.eclipse.jdt.core.compiler.debug.lineNumber=generate
+org.eclipse.jdt.core.compiler.debug.localVariable=generate
+org.eclipse.jdt.core.compiler.debug.sourceFile=generate
+org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
+org.eclipse.jdt.core.compiler.problem.enablePreviewFeatures=disabled
+org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
+org.eclipse.jdt.core.compiler.problem.reportPreviewFeatures=warning
+org.eclipse.jdt.core.compiler.release=disabled
+org.eclipse.jdt.core.compiler.source=1.8

README.md

@@ -14,73 +14,167 @@ Demonstrates how OSGi CICS Java programs link to other CICS programs sending a C
 * [`ChannelLinkCICSProgram.java`](cics-java-osgi-link-app/src/main/java/com/ibm/cicsdev/java/osgi/link/cicsprogram/ChannelLinkCICSProgram.java) - OSGi `@CICSProgram` defined program linked to with a channel
 
 
+## 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-osgi-link/archive/cicsts/v5.5.zip) and unzip onto the workstation
+
+> [!TIP]
+> Eclipse Git provides an 'Import existing Projects' check-box when cloning a repository.
+
+---
+
 ## Repository structure
 * [`cics-java-osgi-link-app/`](cics-java-osgi-link-app) - Java application source
 * [`cics-java-osgi-link-bundle/`](cics-java-osgi-link-bundle/) - Build files for CICS bundle project
-* [`etc/`](etc) - Supporting materials 
+* [`etc/eclipse_projects/`](etc/eclipse_projects) - Static CICS Bundle Project 
 
 
 ## Building
-The sample can be built using Gradle or Maven to produce an OSGi bundle JAR file and optionally a CICS Bundle archive.
+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.
+
+Choose from the following approach:
+* Use the built-in Eclipse and CICS Explorer SDK capability
+* Use Eclipse with Buildship (Gradle), or m2e (Maven) to drive Gradle, or Maven.
+* Use the command line, or IDE terminal, to drive Gradle or Apache Maven (if installed on your workstation)
+* 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)
+
+
+** 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.
+
+
+### Option 1 - Building with Eclipse
 
-### Building with Gradle
+The sample comes pre-configured for use with a standard JDK 1.8 and the CICS TS V5.5 Java EE 6/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. 
 
-A JAR file will be created in `cics-java-osgi-link-app/build/libs/cics-java-osgi-link-app-1.0.0.jar` and a CICS bundle ZIP file in `cics-java-osgi-link-app/build/distributions/cics-java-osgi-link-bundle-1.0.0.zip`.
+To resolve issues:
+* ensure you have the CICS Explorer SDK plug-in installed
+* configure the Project's build-path, and Application Project settings to use your preferred JDK and Java compiler settings
+* set the CICS TS Target Platform to your intended CICS target (Hint: Window | Preferences | Plug-in Development | Target Platform | Add | Template | Other...) 
 
-If using the CICS bundle ZIP, the CICS JVM server name for the OSGi bundle part should be modified in the `cics.jvmserver` property in the gradle build properties file to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line.
+
+### Option 2 - Building with Gradle
+
+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-link-app project. For example, in Eclipse: right-click on "Project", select "Gradle | Refresh Gradle Project".
+
+The CICS JVM server name should be modified in the  `cics.jvmserver` property in the gradle build [cics-java-osgi-link-bundle/build.gradle](cics-java-osgi-link-bundle/build.gradle) to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line (see below).
+
+If you have the Gradle buildship plug-in available, use the right-click **Run As...** menu on the cics-java-osgi-link project to configure and run the `clean` and `build` tasks. Otherwise choose from the command-line approaches.
 
 **Gradle Wrapper (Linux/Mac):**
 ```shell
 ./gradlew clean build
 ```
+
 **Gradle Wrapper (Windows):**
 ```shell
 gradle.bat clean build
 ```
+
 **Gradle (command-line):**
 ```shell
 gradle clean build
 ```
+
 **Gradle (command-line & setting jvmserver):**
 ```shell
 gradle clean build -Pcics.jvmserver=MYJVM
 ```
 
-### Building with Apache Maven
-A JAR file will be created in `cics-java-osgi-link-app/target/cics-java-osgi-link-app-1.0.0.jar`. The CICS bundle ZIP file will be stored in `cics-java-osgi-link-bundle/target/cics-java-osgi-link-bundle-1.0.0.zip`.
+A JAR file is created inside the `cics-java-osgi-link-app/build/libs/` directory and a CICS bundle ZIP file inside the `cics-java-osgi-link-bundle/build/distributions` directory.
+
+
+### Option 3 - Building with Apache Maven
 
-If building a CICS bundle ZIP the CICS bundle plugin is driven using the maven verify phase. The CICS JVM server name for the OSGi bundle part should be modified in the `cics.jvmserver` property in the pom.xml to match the required CICS JVMSERVER resource name, or alternatively can be set on the command line.
+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-link-app project. For example, in Eclipse: right-click on "Project", select "Maven -> Update Project...".
+
+> [!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 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.
+
+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).
+
+If you have the Maven m2e plug-in available, use the right-click **Run As...** menu on the cics-java-osgi-link project to configure and run the `clean` and `verify` tasks. Otherwise choose from the command-line approaches.
 
 **Maven Wrapper (Linux/Mac):**
 ```shell
 ./mvnw clean verify
 ```
+
 **Maven Wrapper (Windows):**
 ```shell
 mvnw.cmd clean verify
 ```
+
 **Maven (command-line):**
 ```shell
 mvn clean verify
 ```
+
 **Maven (command-line & setting jvmserver):**
 ```shell
 mvn clean verify -Dcics.jvmserver=MYJVM
 ```
 
+A JAR file is created inside the `cics-java-osgi-link-app/target` directory and a CICS bundle ZIP file inside the `cics-java-osgi-link-bundle/target` directory.
+
+---
+
 ## Deploying to CICS
+1. Configure an OSGi JVMSERVER. 
+
+2. CICS resource definitions for the bundle, programs, transactions and a JVM server are supplied in a group CDEVSAMP 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-link-bundle project.
+Note that the resource definitions for the CICS programs `CDEVMCLC` and `CDEVMCTC` for the Channel sample are not supplied as they will be auto-installed by the processing of @CICSProgram annotation.
+
+
+### Option 1 - Deploying using CICS Explorer SDK and the provided CICS bundle project
+1. Deploy the CICS bundle project 'com.ibm.cics.server.examples.osgi.link.bundle' from CICS Explorer using the **Export Bundle Project to z/OS UNIX File System** wizard. This CICS bundle includes the osgi bundlepart, the MCLC & MCLM transactions and the CDEVMCLM & CDEVMCTM programs to run the sample.
+
+
+### Option 2 - Deploying using CICS Explorer SDK with own CICS bundle project
+1. Copy and paste the built JAR from your *projects/cics-java-osgi-link-app/target* or *projects/cics-java-osgi-link-app/build/libs* directory into a new Eclipse CICS bundle project.
+2. Create a new OSGi bundlepart that references the JAR (OSGi bundle) file. 
+3. Optionally customise the CICS bundle contents, perhaps adding a TRANDEF of your choice
+4. Right click using the ** Export Bundle Project to z/OS UNIX File System ** wizard.
+
+
+### Option 3 - Deploying using CICS Explorer (Remote System Explorer) and CICS Bundle ZIP
+1. Connect to USS on the host system
+2. Create the bundle directory for the project.
+3. Copy & paste the built CICS bundle ZIP file from your *projects/cics-java-osgi-link-bundle/target* or *projects/cics-java-osgi-link-bundle/build/distributions* directory to z/FS on the host system into the bundle directory.
+4. Extract the ZIP by right-clicking on the ZIP file > User Action > unjar...
+5. Refresh the bundle directory
+
+
+### Option 4 - Deploying using command line tools
+1. Upload the built CICS bundle ZIP file from your *projects/cics-java-osgi-link-bundle/target* or *projects/cics-java-osgi-link-bundle/build/distributions* directory to z/FS on the host system (e.g. FTP).
+2. Connect to USS on the host system (e.g. SSH).
+3. Create the bundle directory for the project.
+4. Move the CICS bundle ZIP file into the bundle directory.
+5. Change directory into the bundle directoy.
+6. Extract the CICS bundle ZIP file. This can be done using the `jar` command. For example:
+   ```shell
+   jar xf file.zip
+   ```
+
+---
 
-1. CICS resource definitions for the bundle, programs, transactions and a JVM server are supplied in a group CDEVSAMP 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-link-bundle project.
-Note that the resource definitions for the CICS programs `CDEVMCLC` and `CDEVMCTC` for the Channel sample are not supplied as they will be autoinstalled by the processing of @CICSProgram annotation.
+## Installing the CICS bundle
+### Installing the CICS bundle from a CICS terminal
+1. Create a new bundle definition, setting the bundle directory to the deployed bundle directory:
+   ```
+   BUNDLE(CDEVCJOL) GROUP(CDEVCJOL) BUNDLEDIR(/path/to/bundle/directory)
+   ```
+2. Install the bundle
 
-1. First deploy the CICS bundle project to z/FS.
-   1. Via CICS explorer "Export to UNIX filesystem".
-   2. Via the bundle deploy endpoint (create the bundle definition in step 5 first).
-   3. Via FTP to z/FS, and extract the ZIP file.
 
-1. Update the BUNDLEDIR attribute on the BUNDLE resource to match the zFS location of the deployed CICS bundle project. 
+### Installing the CICS bundle with CICS Explorer
+1. Definitions > Bundle Definitions
+2. Right-click > New...
+3. Fill in the Bundle and Group names as `CDEVJODB`
+4. Fill in the Bundle Directory to point to the directory you expanded the ZIP
+5. Install the bundle
 
-1. Install the sample group CDEVCJOL 
+---
 
 
 ## Running

cics-java-osgi-link-app/.classpath

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+	<classpathentry kind="src" path="src/main/java"/>
+	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.8/"/>
+	<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
+	<classpathentry kind="src" path=".apt_generated">
+		<attributes>
+			<attribute name="optional" value="true"/>
+		</attributes>
+	</classpathentry>
+	<classpathentry kind="output" path="bin/"/>
+</classpath>

cics-java-osgi-link-app/.project

@@ -20,10 +20,21 @@
 			<arguments>
 			</arguments>
 		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.ManifestBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.pde.SchemaBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
 	</buildSpec>
 	<natures>
 		<nature>org.eclipse.jdt.core.javanature</nature>
 		<nature>org.eclipse.m2e.core.maven2Nature</nature>
 		<nature>org.eclipse.buildship.core.gradleprojectnature</nature>
+		<nature>org.eclipse.pde.PluginNature</nature>
 	</natures>
 </projectDescription>

cics-java-osgi-link-app/.settings/org.eclipse.buildship.core.prefs

@@ -0,0 +1,13 @@
+arguments=
+auto.sync=false
+build.scans.enabled=false
+connection.gradle.distribution=GRADLE_DISTRIBUTION(WRAPPER)
+connection.project.dir=
+eclipse.preferences.version=1
+gradle.user.home=
+java.home=
+jvm.arguments=
+offline.mode=false
+override.workspace.settings=false
+show.console.view=false
+show.executions.view=false

cics-java-osgi-link-app/.settings/org.eclipse.core.resources.prefs

@@ -1,4 +1,3 @@
 eclipse.preferences.version=1
 encoding//src/main/java=UTF-8
-encoding//src/main/resources=UTF-8
 encoding/<project>=UTF-8

cics-java-osgi-link-app/.settings/org.eclipse.jdt.apt.core.prefs

@@ -1,4 +1,5 @@
 eclipse.preferences.version=1
 org.eclipse.jdt.apt.aptEnabled=true
-org.eclipse.jdt.apt.genSrcDir=target/generated-sources/annotations
-org.eclipse.jdt.apt.genTestSrcDir=target/generated-test-sources/test-annotations
+org.eclipse.jdt.apt.genSrcDir=.apt_generated
+org.eclipse.jdt.apt.genTestSrcDir=.apt_generated_tests
+org.eclipse.jdt.apt.reconcileEnabled=true

cics-java-osgi-link-app/.settings/org.eclipse.jdt.core.prefs

@@ -1,9 +1,15 @@
 eclipse.preferences.version=1
+org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
+org.eclipse.jdt.core.compiler.codegen.methodParameters=do not generate
 org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.8
+org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
 org.eclipse.jdt.core.compiler.compliance=1.8
+org.eclipse.jdt.core.compiler.debug.lineNumber=generate
+org.eclipse.jdt.core.compiler.debug.localVariable=generate
+org.eclipse.jdt.core.compiler.debug.sourceFile=generate
+org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
 org.eclipse.jdt.core.compiler.problem.enablePreviewFeatures=disabled
-org.eclipse.jdt.core.compiler.problem.forbiddenReference=warning
-org.eclipse.jdt.core.compiler.problem.reportPreviewFeatures=ignore
-org.eclipse.jdt.core.compiler.processAnnotations=enabled
-org.eclipse.jdt.core.compiler.release=enabled
-org.eclipse.jdt.core.compiler.source=1.8
+org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
+org.eclipse.jdt.core.compiler.problem.reportPreviewFeatures=warning
+org.eclipse.jdt.core.compiler.release=disabled
+org.eclipse.jdt.core.compiler.source=1.8

cics-java-osgi-link-app/src/main/resources/META-INF/MANIFEST.MF renamed to cics-java-osgi-link-app/META-INF/MANIFEST.MF

@@ -1,6 +1,23 @@
 
 plugins {
     id 'java'
+    id 'eclipse'
+}
+
+java
+{
+	sourceCompatibility = JavaVersion.VERSION_1_8
+	targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+
+// If in Eclipse, add Javadoc to the local project classpath
+eclipse 
+{
+    classpath 
+    {
+        downloadJavadoc = true
+    }
 }
 
 dependencies {
@@ -12,6 +29,6 @@ description = 'CICS OSGi link application'
 
 jar {
     manifest {
-        from 'src/main/resources/META-INF/MANIFEST.MF'
+        from 'META-INF/MANIFEST.MF'
     }
 }

cics-java-osgi-link-app/build.gradle

@@ -0,0 +1,5 @@
+bin.includes = META-INF/,\
+               .
+source.. = src/main/java/
+jre.compilation.profile = JavaSE-1.8
+output.. = bin/

cics-java-osgi-link-app/build.properties

@@ -33,7 +33,7 @@
                 <version>3.3.0</version>
                 <configuration>
                     <archive>
-                        <manifestFile>src/main/resources/META-INF/MANIFEST.MF</manifestFile>
+                        <manifestFile>META-INF/MANIFEST.MF</manifestFile>
                     </archive>
                 </configuration>
             </plugin>

cics-java-osgi-link-app/pom.xml

@@ -0,0 +1,13 @@
+arguments=
+auto.sync=false
+build.scans.enabled=false
+connection.gradle.distribution=GRADLE_DISTRIBUTION(WRAPPER)
+connection.project.dir=../cics-java-osgi-link-app
+eclipse.preferences.version=1
+gradle.user.home=
+java.home=
+jvm.arguments=
+offline.mode=false
+override.workspace.settings=false
+show.console.view=false
+show.executions.view=false

cics-java-osgi-link-bundle/.settings/org.eclipse.buildship.core.prefs

@@ -0,0 +1,2 @@
+eclipse.preferences.version=1
+org.eclipse.ltk.core.refactoring.enable.project.refactoring.history=false