ibm / cics-bundle-maven Goto Github PK

At the moment, anyone who wants to try out the plugin has to download and build the source.

Using the snapshot repository will give us a way for users to more easily try out non-release versions.

The Explorer implementation that generates cics.xml injects a build time within the <manifest> tag, like:

    <meta_directives>
        <timestamp>2014-02-11T12:55:48.222Z</timestamp>
    </meta_directives>

The Maven implementation should do similar.

When deploying an app into a region which isn't part of a sysplex, I get this:

Deploying bundle to http://winmvs2c.hursley.ibm.com:22566 into region null/null

OK, I've not specified the <region> or <cicsplex> tag in the pom.xml, but messages with null inside look wrong.
The cdsgroup is always there, perhaps deploying to that ? with an optional region/cicsplex in the message would be better ?

I am trying to re-deploy a bundle via the maven plugin. The installed bundle resource has one UNUSABLE and one ENABLED bundle parts and as such the bundle itself is in a DISABLED state. The DISCARD fails as a result.

Need to DISABLE before DISCARD irrelevant of the bundle enable status

Give assurances about using this library by documenting how to get support (in addition to what's already in CONTRIBUTING.md), and that support is included in your CICS TS license.

At the moment the symbolic name is written into the bundlepart with the version in.

This needs to be updated so that the version is written into the correct xml attribute, separately from the name. So the XML should look something like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <osgibundle symbolicname="myosgi" version="1.0.0" jvmserver="JVMONE"/>

In the scenarios where we create a CICS bundle from an existing project, using the bundle-osgi / bundle-war / bundle-ear / bundle-eba goals, the classifier attribute claims to be optional with a default value of cics-bundle, but omitting it from pom.xml results in a deployment failure with the error message:

[ERROR] Failed to execute goal com.ibm.cics:cics-bundle-maven-plugin:1.0.1-SNAPSHOT:deploy (default) on project standalone-war: Some of the supplied parameters were invalid:
[ERROR]  - bundle: Error reading bundle manifest: Supplied CICS bundle must have a manifest at META-INF/cics.xml

Also, the comment in the samples makes it sound like the cics-bundle value is somehow significant to the packaging method, whereas I think it's actually just an arbitrary string which is appended to the zip filename?

<!-- The bundle classifier indicates that the war should be packaged into a CICS bundle -->
<classifier>cics-bundle</classifier>

Relevant doc pages:
https://github.com/IBM/cics-bundle-maven#create-a-cics-bundle-from-an-existing-java-module-using-cics-bundle-maven-plugin
https://ibm.github.io/cics-bundle-maven/bundle-war-mojo.html#classifier

Support for bundle import statements. We don't think this is likely to be essential for the kind of use we're targetting.

As mentioned in #14, we think a standard ordering could fulfil most requirements.

Currently the bundlepart filename is derived from the symbolic name. However it's possible to use names that aren't valid on some filesystems.

The docs for https://ibm.github.io/cics-bundle-maven/deploy-mojo.html need improving such that
it's clear the and parameters should be omitted if the region is a stand-alone one.

----------------- conversation leading up to this issue being raised ------------------
So for a stand-alone region, with A CMCI-enabled Liberty JVM server, and a normal liberty JVM server, I still don’t know what value to put for the field. Or perhaps this isn’t a supported configuration ?
Context: Trying to use the maven plug-ins to deploy a JCICSX sample. (edited)

Tom Foyle
For a stand-alone region, you should remove the and fields, as they are not relevant.

David Knibb
yep - because your single region (SMSS) is not part of a CICSplex.

Stew Francis
If the doc doesn't make that clear, can you raise a defect so we can address that? Thanks Mike!

Mike Cobbett
It could be clearer. A Required:No is the only hint I think. https://ibm.github.io/cics-bundle-maven/deploy-mojo.html

Stew Francis
Yeah I agree. The doc there should say in which environments it's required, and which it isn't.
If you could raise an issue against that repo, that'd be great

Currently to deploy you either have to specify the bundle location, or it will default to getting the artifact for that maven project. Allow specifying a bbundle published as another artifact.

https://ibm.github.io/cics-bundle-maven/plugin-info.html - in the top left navigation is a link to the parent pom. We need to remove this, either by configuring the build (which would be ideal) or worst case by doing some kind of transform in post-site.

Continuing from #69 , the samples delivered should be built as part of the main build, to ensure that samples are updated when we break them.
This will likely require a wiremock server set up for them to hit during the deploy step.

For instance, pipeline resources require supporting files to be present in EBCDIC on the server.

We'd need to detect the pipeline resource additional file and transcode it during build time.

Other unsupported resources include...
Atomservice (needs to be EBCDIC)
JVM server (JVM profile needs to be local USS/zFS encoding)
Node.js
Pipeline (config file needs to be IBM-037)
Web service (additional files need to be transferred as binary)
EBA
XML Transform
JSON Transform

Currently we don't bind anything to the install phase, which means CICS bundle artifacts never make it to your local maven repo when using the cics-bundle packaging type. We should bind the install plugin to correct this.

Add an additional supported bundlepart type for Enterprise Bundle Archives.

I downloded manven and can run mvn -v
I downloaded the openliberty,io microprofile4 sample

the next step says run mvn liberty:dev

???? what do I do woth the microprofile4.zip so that that mvn liberty:dev will work.

Common code around bundle generation able to be used elsewhere

• Update samples so that both options can be deployed simultaneously. Currently the war is named the same in both so cannot both be installed and enabled at the same time.

• Add version number to maven-compiler-plugin to fix warning

• Update the docs in regards to issues with certificates/trust store

• Rename default JVM server in the samples

Allow self signed certificates and hostnames that don't match the certificate (for virtual hosts with one certificate).

Currently we default defaultjvmserver to MYJVMS. However there's no sensible default JVM server name. If users are bundling a Java app, they need to specify a JVM server name.

We should alter the behaviour so that if a JVM server name isn't provided either via defaultjvmserver or specific JVM servers on every relevant project, the build fails and the user is warned.

The only people this will affect is those who genuinely are happy with the default because they have a JVM server called MYJVMS .... it seems that this group will be vanishingly small!

We should provide a couple of sample bundles. We could provide both a 'standalone' bundle that packages a pre-existing WAR project, and a WAR project that is configured to produce a bundle.

We should deliver these as sample projects within cics-bundle-maven/samples and build them automatically as part of our build.

While demoing we noticed that during a deploy we could do with some more log messages or confirmation that things are working.

Two obvious options...

1. Do as Liberty do and document statically within git - they have a docs folder containing markdown e.g. https://github.com/WASdev/ci.maven/blob/master/docs/compile-jsp.md
2. Do as Tycho do and generate Maven doc (we'd need some static info as well e.g. for usage) e.g. https://www.eclipse.org/tycho/sitedocs/tycho-compiler-plugin/plugin-info.html

If there are no external dependencies for java types and nothing in the resources folder for other bundle parts the build would complete successfully with an empty CICS bundle.
Produce a warning message in this case.

Maven plugins permit the use of user properties, i.e. system properties that are recognised by the plugin and can be used to override its configuration. For example, from the invoker plugin:

These give flexibility to the build and allow overriding in different environments more easily.

Best practice for user properties is now to pick a prefix (invoker above) to namespace your properties, avoiding clashes with other plugins.

Currently we don't include any license text in the built binary. We should include the EPL v2 license.

To improve the workflow in Eclipse, m2e features can be used to auto-build with the Eclipse build cycle, and to show generated resources without a manual refresh.

Tasks:

• Introduce m2e mapping to validate CICS bundles on incremental builds
• Use BuildContext to communicate file changes to be refreshed

This works fine in the reactor case.

When specifying the deployment URL in settings.xml, users shouldn't have to specify the path to the deploy endpoint, as that's going to be the same everywhere. Just where it's hosted should be sufficient.

Git can natively host markdown, but the Maven doc is produced in HTML.

Push the Maven doc to github pages at the end of the build (probably via a gh-pages branch).

Potentially also pull across the readme as an index page.

Validate during build to match existing validation in CICS Explorer where possible.

• name of generated bundle part (valid characters, no spaces)
• jvmserver name validity ... probably don't want to mandate because of option to allow default JVM server for the region
• verify behaviour if dependent Java project doesn't build cleanly
• ...?

I'm using jdk 1.8. I get this error when I try to create the cics-bundle for the demo-war sample project.

Command used: mvn clean install
Error messages:
[WARNING] Error injecting: com.ibm.cics.cbmp.BundleWarMojo
java.lang.NoClassDefFoundError: com/ibm/cics/bundle/parts/BundlePublisher$PublishException
...
Failed to execute goal com.ibm.cics:cics-bundle-maven-plugin:1.0.0:bundle-war (default) on project demo-war-bundle: Execution default of goal com.
ibm.cics:cics-bundle-maven-plugin:1.0.0:bundle-war failed: A required class was missing while executing com.ibm.cics:cics-bundle-maven-plugin:1.0.0:bundle
-war: com/ibm/cics/bundle/parts/BundlePublisher$PublishException

Primarily for the plugin documentation (rather than project documentation) - so plugin-info.html, *-mojo.html and related.

Not sure whether we can cut down the generated doc to just that.

These seem to be the key Maven plugins:
https://maven.apache.org/plugins/maven-site-plugin/
https://maven.apache.org/plugins/maven-project-info-reports-plugin/
https://maven.apache.org/plugin-tools/maven-plugin-plugin/index.html

See Gradle fix and implement similar here.
IBM/cics-bundle-gradle#17
IBM/cics-bundle-gradle#27

Maven generates the version as SNAPSHOT in the filename - would be good to look at the right way to avoid this.

[ERROR] Failed to execute goal com.ibm.cics:cics-bundle-maven-plugin:1.0.3-SNAPSHOT:deploy (default) on project cics-java-liberty-restapp: Execution default of goal com.ibm.cics:cics-bundle-maven-plugin:1.0.3-SNAPSHOT:deploy failed: Text may not be null -> [Help 1]

What does that mean ? It's not clear what it's complaining about...

Diagnosed by stew:

Ok the dependency from cics-bundle-maven-plugin wasn't updated to use the snapshot version of cics-bundle-common. If you could raise a defect Mike, that'd be great. Public repo is fine

    <dependency>
      <groupId>com.ibm.cics</groupId>
      <artifactId>cics-bundle-common</artifactId>
      <version>1.0.2</version>
    </dependency>

The pom I used:

<?xml version=“1.0” encoding=“UTF-8"?>
<project xmlns=“http://maven.apache.org/POM/4.0.0” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xsi:schemaLocation=“http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd”>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.ibm.cics</groupId>
  <artifactId>cics-java-liberty-restapp</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>war</packaging>
  <dependencies>
    <!-- https://mvnrepository.com/artifact/javax.xml.bind/jaxb-api -->
    <dependency>
      <groupId>javax.xml.bind</groupId>
      <artifactId>jaxb-api</artifactId>
      <version>2.3.1</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>javax.servlet-api</artifactId>
      <version>3.1.0</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javax.annotation</groupId>
      <artifactId>jsr250-api</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
    </dependency>
    <dependency>
      <groupId>javax.ws.rs</groupId>
      <artifactId>javax.ws.rs-api</artifactId>
      <version>2.0.1</version>
    </dependency>
    <!-- JCICSX dependency -->
    <dependency>
      <groupId>com.ibm.cics</groupId>
      <artifactId>com.ibm.cics.jcicsx</artifactId>
      <version>1.000.0-5.6</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
  <pluginRepositories>
    <!-- Configure Sonatype OSS Maven snapshots repository -->
    <pluginRepository>
      <id>sonatype-nexus-snapshots</id>
      <name>Sonatype Nexus Snapshots</name>
      <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
      <releases>
        <enabled>false</enabled>
      </releases>
    </pluginRepository>
  </pluginRepositories>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
        </configuration>
      </plugin>
      <!-- The below bundles the application as a WAR in a CICS bundle and deploys this to CICS using the CICS bundle deployment API.
           This is optional and can be removed if you don’t wish to deploy the application this way -->
      <plugin>
        <groupId>com.ibm.cics</groupId>
        <artifactId>cics-bundle-maven-plugin</artifactId>
        <version>1.0.3-SNAPSHOT</version>
        <executions>
          <execution>
            <!-- These goals will firstly run the war packaging on the project, and then will run the deploy goal, which will happen during the verify phase of the lifecycle by default-->
            <goals>
              <goal>bundle-war</goal>
              <goal>deploy</goal>
            </goals>
            <configuration>
              <!-- The bundle classifier indicates that the war should be packaged into a CICS bundle -->
              <classifier>cics-bundle</classifier>
              <!-- Update the default JVM server that the application will be installed into by default, This is used when creating the bundle, and goes into the CICS bundle’s manifest -->
              <jvmserver>DFHWLP</jvmserver>
              <!-- Set the URL of the deploy target -->
              <url>http://winmvs2c.hursley.ibm.com:22566</url>
              <!-- We’d recommend that you use Maven’s password encryption, or supply your credentials using environment variables or properties, as shown here. -->
              <username>MCOBBE</username>
              <password></password>
              <!-- Identify which bundle definition you’re going to use from the CSD and which region and CICSPlex you want to deploy to -->
              <bunddef>DEMOBUNDLE</bunddef>
              <csdgroup>SOMETHING_HERE</csdgroup>
              <!-- in a stand-alone region, neither of these parameters are needed: -->
              <!-- <cicsplex>CICPY022</cicsplex> -->
              <!-- <region>CICPY022</region> -->
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

#14 covers non-Java based bundle parts.

It would be good to build Node bundle parts which we haven't taken into account for that issue.

The Java-based bundle parts we currently support (WAR/EAR/JAR) are configured by setting dependencies in the pom file and adding the cics-bundle-maven-plugin.

This issue considers adding support for other bundle parts. There are a few categories of these:

1. Simple bundle parts - e.g. URI map
2. Bundle parts with additional files - e.g. JVM server, which has an associated JVM profile file
3. Other Java-based bundle parts we haven't added support for - e.g. EBA projects

In this issue I'm primarily thinking about (1) and (2). (3) should likely follow the same approach as WAR/EAR/JAR.

Having discussed this we have two potential approaches; one where the cics.xml is generated at build time, and one where the cics.xml is a hybrid - partly provided by the user and partly generated based on the pom.xml.

The advantage of having the cics.xml generated is that there is less to go wrong and a clearer path for the user. The disadvantage is that there are some aspects of cics.xml that won't lend themselves to being specified in a pom (e.g. ordering of definitions). For the moment I'm not addressing other elements that could be included in cics.xml.

Approach 1

a) User supplies bundle parts and supporting files if applicable into src/main/cics-bundle
b) In the build phase, copy these files across
c) In the build phase, detect provided bundle part files and generate defines in the cics.xml (as with the Java-based bundles)
d) The defines would be ordered in a way that will cater for the vast majority of use cases (so, traditional definition bundle parts before Java-based bundle parts, pipeline before webservice)

Approach 2 (this was the original issue description)

This a we're considering is like this:
a) Put bundle part files (e.g. mymap.urimap) into src/main/cics-bundle
b) Put cics.xml file into src/main/cics-bundle/META-INF
c) Early in the build phase, copy these files across as the basis for our final CICS bundle
d) When processing the Java-based bundle parts extend the user-provided cics.xml file by appending the Java-based bundle parts specified in the pom (initially).

Further work could include alterations in CICS Explorer to allow users to create bundle parts and a CICS manifest using the GUI directly into the Maven project.

e) At this point we could allow users to add the Java-based bundle parts into the cics.xml using the GUI - the GUI would check the Maven dependencies for available projects. This would then allow the order of the Java-based bundle parts to be controlled.

The initial code drop for handling CICS resources included pipeline resources. However the additional supporting files will need transcoding into EBCDIC as part of the build.

This was outside of the scope of the original code drop and therefore I'm removing pipeline support as a defect.

The prerequisites in the readme should point to the knowledge centre for how to set up the CICS bundle deployment API when these are published.

(variables in attributes as introduced with CICSBT)