Define the plugin expected experience

[davenice]

(original description from @ind1go)

Scenario 1 - super-basic

It's pretty much a no-op - the user is just getting started. What's the minimal CICS bundle that can be built.

This scenario is also the simplest way to represent some of the other changes I'm proposing.

/* 
 * Resolve and apply the plugin
 * Named reverse-domain-style as per
 * https://guides.gradle.org/implementing-gradle-plugins/#assigning_appropriate_plugin_identifiers
 * - compare Gradle plugins for Android or Node.js
 */
plugins {
    id 'com.ibm.cics.bundle' version '1.0.0'
}

// Information about this artifact
version '1.0.0-SNAPSHOT'

Expected behaviour

When I execute the built-in build task Then:

• The following tasks run sequentially:

  :buildCICSBundle
  :packageCICSBundle
  :assemble
  :build

• An empty (except for META-INF/cics.xml) CICS bundle is produced and stored in project.distsDir i.e. build/distributions in this default case.

Non-exhaustive differences from now

• Different plugin ID (note repo name, plugin JAR etc can/should stay the same as now - c.f. Android or Node.js plugins which serve multiple plugins from a single JAR.

• Omitting cicsBundle... extensions in build.gradle won't fail the build.

Scenario 2 - dependencies

The user adds some Java dependencies to their CICS bundle, which will be built into the resultant CICS bundle.

plugins {
    id 'com.ibm.cics.bundle' version '1.0.0'
}

// Information about this artifact
version '1.0.0-SNAPSHOT'

repositories {
    mavenCentral()
}

dependencies {
    cicsBundlePart 'some.group:some-ear-on-maven-central:1.2.3@ear'
    cicsBundlePart project(':my-local-war')
}

cicsBundle {
    build {
        defaultJVMServer = "MYJVM"
    }
}

Expected behaviour

When I execute the built-in build task Then:

• The following tasks run sequentially:

  :buildCICSBundle
  :packageCICSBundle
  :assemble
  :build

• A CICS bundle with the external EAR and local WAR dependencies is produced and stored in project.distsDir.

Non-exhaustive differences from now

• Differently-named extension cicsBundle which merges the build and deploy extensions.
• build sub-section of cicsBundle extension to separate it from deployment.
• Camel-casing of defaultJVMServer.

Scenario 3 - manual setup

The user is going off-piste, probably as part of some larger-scale Gradle build. They want to take the individual parts of the CICS bundle build and wire them together as they need. They don't want the plugin's magic applied - they want to use individual parts.

/*
 * Don't actually apply the plugin i.e. it's available on the classpath
 * of the build script, but the apply() method is not called.
 */
plugins {
    id 'com.ibm.cics.bundle' version '1.0.0' apply false
}

// Information about this artifact
version '1.0.0-SNAPSHOT'

task buildABundle(type: com.ibm.cics.cbgp.BuildBundleTask) {
    outputDirectory = file "${buildDir}/bundleStage1"

}

task addABundleFile {
    dependsOn buildABundle
    ext.outputFile = new File(file(buildABundle.outputDirectory), "META-INF/ME.txt")
    outputs.file outputFile
    doLast {
        outputFile.text = "My custom text entry"
    }
}

task packageABundle(type: com.ibm.cics.cbgp.PackageBundleTask) {
    dependsOn buildABundle
    dependsOn addABundleFile
    inputDirectory = file "${buildDir}/bundleStage1"
    destinationDirectory = file "${buildDir}/bundleStage2"
    archiveFileName = "the-bundle-1.2.3.zip"
}

task auditBundle(type: Zip) {
    dependsOn packageABundle
    eachFile { fileCopyDetails ->
        // Run check on each bundle part
    }
    from zipTree(packageABundle.archiveFile)
    destinationDirectory = file "${buildDir}/bundleStage3"
    archiveFileName = packageABundle.archiveFileName
}

task customBuild

customBuild.dependsOn auditBundle

Expected behaviour

WORK IN PROGRESS - still to consider:

• How does the JVM server or other configuration get supplied

Non-exhaustive differences from now

• The tasks currently require the extension to be specified but here's it's not necessary
• Not sure whether the tasks currently offer enough by way of (ready-only, perhaps) output properties so subsequent tasks can build on them or use their information

Scenario 4 - deployment

The user augments their existing build by adding deployment.

plugins {
    id 'com.ibm.cics.bundle' version '1.0.0'
}

// Information about this artifact
version '1.0.0-SNAPSHOT'

repositories {
    mavenCentral()
}

dependencies {
    cicsBundlePart 'some.group:some-ear-on-maven-central:1.2.3@ear'
    cicsBundlePart project(':my-local-war')
}

cicsBundle {
    build {    
        defaultJVMServer = "MYJVM"
    }
    deploy {
    cicsplex = "..."
    region = "..."
    bunddef = "..."
    csdgroup = "..."
    url = "..."
    username = "..."
    password = "..."
    insecure = false
    }
}

Expected behaviour

When I execute the deployCICSBundle task Then:

• The following tasks run sequentially:

  :buildCICSBundle
  :packageCICSBundle
  :deployCICSBundle

The CICS bundle is built and deployed.

Non-exhaustive differences from now

• deploy sub-section of cicsBundle extension.

---

Other scenarios to consider:

• The single-module scenario from the Maven plugin, i.e. the Java module is also packaged as a CICS bundle.

[tom-foyle]

@ind1go Do you particularly want to keep this issue ongoing? All the points in here have now been addressed apart from Scenario 3 for manual setup. I'm thinking we could copy that example into #8 and then close this issue?

[ledina]

Closing issue as we think we have all the scenarios captured now