Feature/todo-adapter

todo-template/README.md

@@ -0,0 +1,46 @@
+# Caplin Todo List Adapter Template
+
+This project provides a starting point for writing integration Adapters based on the Caplin DataSource Java API. The build is written in gradle and requires either a local installation of gradle or an internet connection over which gradle can be downloaded. This is done seamlessly with the provided `gradlew` script files.
+
+## Getting started
+This section outlines the basic steps necessary to build, deploy and start the Adapter.
+
+1. download/clone the repository
+2. change the project name in settings.gradle. This will be used as the name for the artifact.
+3. change the username and password in the `build.gradle` file to your caplin credentials
+4. run `gradle assemble`
+5. deploy the zip file created in `build/distributions/` into your Deployment Framework
+6. configure the host for the deployed blade with the `./dfw hosts` command
+7. start the adapter with `./dfw start <adapterName>`
+
+
+## Development modes
+In addition to creating an adapter blade that can be deployed using the Caplin Deployment Framework the build has two more tasks that make it easier to run the adapter from an IDE. The two modes modes differ **run against a local DFW** and **run against a remote DFW** and are explained in more detail in the following two sections.
+
+### Connect an adapter from an IDE to a local DFW
+In order for the Liberator and Transformer to know abou the blade they need the configuration bundled with this blade. The concept of a **config only blade** is essentially a blade that contains only configuration and no binary. When this blade is deployed, the difference to a full blade is that `./dfw start` will not start up the adapter. At this point the integration adapter can be started from the IDE. The following bullet points outline the recommended way of setting this up.
+
+1. run `gradle assemble -PconfigOnly`
+2. deploy the zip file created in `build/distributions/` into your Deployment Framework
+3. create a run configuration for the main class of your project
+ * set the environment variable `CONFIG_BASE` to point to the `global_config/` folder in your DFW
+ * set the working directory to `<dfw location>/active_blades/<AdapterName>/DataSource `
+4. Run the adapter using the run configuration just created
+
+### Connect an adapter from an IDE to a remote DFW
+Sometimes, the Liberator and Transformer will not be on the host that is being developed on. In this case the above approach will not work. To solve this issue the build has a task `createWorkingDirectory` that generates necessary (limited) configuration to allow the adapter to connect to a remote host. The following steps are required to set this up.
+
+1. run `gradle assemble -PconfigOnly`
+2. deploy the zip file created in `build/distributions/` into your Deployment Framework (remote host)
+3. run `gradle setupWorkingDirectory` which will create the folder `build/env` for use as a working directory. This will also require some default properties to be overridden with the -P command line switch. See the [Gradle Documentation]( https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_properties_and_system_properties). Supported options are:
+ * thisLeg - defaults to `1` and only needs to be changed if you want to connect to the failover leg
+ * liberatorHost - defaults to `localhost` and will need to be changed to the host Liberator runs on
+ * liberatorPort - defaults to `15001` and might need to be changed to the Liberator datasrc port
+ * transformerHost - defaults to `localhost` and will need to be changed to the host Transformer runs on
+ * transformerPort - defaults to `15002` and might need to be changed to the Transformer datasrc port
+4. Once the working directory has been created check the generated file `build/env/blade_config/environment-ide.conf` for correctnes of generated arguments
+5. Create a run configuration with the directory `build/env/DataSource` as a working directory
+6. Start the Adapter using the run configuration just created
+
+## Issues
+For issues with the templates please contact Caplin Support or raise an issue on Github.

todo-template/blade/DataSource/bin/start-jar.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+#
+# Start the TodoTemplateAdapter Java DataSource.
+#
+# $1 - Path to java executable
+# $2 - Path to datasource XML file
+# $3 - Path to fields XML file
+# $4 - Java definitions ( optional )
+#
+# Returns the process id of the Java process.
+#
+
+BLADENAME=@adapterName@
+
+if [ "$1" = "CONFREADER" ]; then
+   shift
+   confreading=1
+   jar=`ls "$BINARY_ROOT"/lib/datasource-java*.jar|head -1`
+else
+   confreading=0
+   jar=`ls "$BINARY_ROOT"/lib/$BLADENAME*.jar|head -1`
+   classpath="${BINARY_ROOT}/lib/*"
+
+   echo "Classpath: $jar"
+fi
+
+if [ $confreading = 1 ]; then
+   java -jar "$jar" "$@"
+   exit $?
+else
+   java -cp "$classpath" -jar "$jar" "$@" > "$LOGDIR"/java-$BLADENAME.log 2>&1 &
+   echo $!
+fi

todo-template/blade/DataSource/etc/datasource.conf

@@ -0,0 +1,78 @@
+##################################################
+#
+# Include base configuration
+#
+if "${ENV:CONFIG_BASE}x" != "x"
+    include-file ${ENV:CONFIG_BASE}bootstrap.conf
+    include-file ${ENV:CONFIG_BASE}fields.conf
+endif
+
+include-file ${ccd}/../../blade_config/bootstrap.conf
+include-file ${ccd}/../../blade_config/fields.conf
+
+datasrc-name ${ADAPTER_NAME}${THIS_LEG}-%h
+
+##################################################
+#
+# Logging configuration
+#
+log-dir %r/var
+log-level INFO
+
+log-use-parent-handlers TRUE
+
+event-log event-${ADAPTER_NAME}.log
+
+##################################################
+#
+# Local DataSource peer-id
+#
+datasrc-local-label            ${ADAPTER_NAME}${THIS_LEG}
+
+##################################################
+#
+# Liberator peer
+#
+add-peer
+        local-type              active|contrib
+        remote-name             liberator${THIS_LEG}
+        addr                    ${LIBERATOR${THIS_LEG}_HOST}
+        port                    ${LIBERATOR${THIS_LEG}_DATASRCPORT}
+        heartbeat-time          15
+        heartbeat-slack-time    5
+end-peer
+
+if "${FAILOVER}" == "ENABLED"
+        add-peer
+                local-type              active|contrib
+                remote-name             liberator${OTHER_LEG}
+                addr                    ${LIBERATOR${OTHER_LEG}_HOST}
+                port                    ${LIBERATOR${OTHER_LEG}_DATASRCPORT}
+                heartbeat-time          15
+                heartbeat-slack-time    5
+        end-peer
+endif
+
+##################################################
+#
+# Transformer peer
+#
+add-peer
+        local-type              active|contrib
+        remote-name             transformer${THIS_LEG}
+        addr                    ${TRANSFORMER${THIS_LEG}_HOST}
+        port                    ${TRANSFORMER${THIS_LEG}_DATASRCPORT}
+        heartbeat-time          15
+        heartbeat-slack-time    5
+end-peer
+
+if "${FAILOVER}" == "ENABLED"
+        add-peer
+                local-type              active|contrib
+                remote-name             transformer${OTHER_LEG}
+                addr                    ${TRANSFORMER${OTHER_LEG}_HOST}
+                port                    ${TRANSFORMER${OTHER_LEG}_DATASRCPORT}
+                heartbeat-time          15
+                heartbeat-slack-time    5
+        end-peer
+endif

todo-template/blade/Liberator/etc/rttpd.conf

@@ -0,0 +1,59 @@
+include-file ${ccd}/../../blade_config/bootstrap.conf
+
+add-peer
+        label                     ${ADAPTER_NAME}${THIS_LEG}
+        remote-name               ${ADAPTER_NAME}${THIS_LEG}
+        remote-type               active
+        heartbeat-time            15
+        heartbeat-slack-time      5
+end-peer
+
+if "${FAILOVER}" == "ENABLED"
+        add-peer
+                label                   ${ADAPTER_NAME}${OTHER_LEG}
+                remote-type             active
+                remote-name             ${ADAPTER_NAME}${OTHER_LEG}
+                heartbeat-time          15
+                heartbeat-slack-time    5
+        end-peer
+endif
+
+# Map the username into the container subject
+object-map /PRIVATE/TODO/CONTAINER /PRIVATE/%u/TODO/CONTAINER
+
+add-data-service
+        service-name        ${ADAPTER_NAME}TransformerContainerSvc${THIS_LEG}
+        include-pattern     ^/PRIVATE/[[email protected]]/TODO
+
+        add-source-group
+                required
+                if "${FAILOVER}" == "ENABLED"
+                        if "${LOAD_BALANCING}" == "ENABLED"
+                                #
+                                # Load balancing with 2 legs
+                                #
+                                add-priority
+                                        label   transformer${THIS_LEG}
+                                        label   transformer${OTHER_LEG}
+                                end-priority
+                        else
+                                #
+                                # Failover with 2 legs
+                                #
+                                add-priority
+                                        label   transformer${THIS_LEG}
+                                end-priority
+                                add-priority
+                                        label   transformer${OTHER_LEG}
+                                end-priority
+                        endif
+                else
+                        #
+                        # One leg only
+                        #
+                        add-priority
+                                label   transformer${THIS_LEG}
+                        end-priority
+                endif
+        end-source-group
+end-data-service

todo-template/blade/Transformer/etc/transformer.conf

@@ -0,0 +1,56 @@
+include-file ${ccd}/../../blade_config/bootstrap.conf
+
+add-peer
+        label                     ${ADAPTER_NAME}${THIS_LEG}
+        remote-name               ${ADAPTER_NAME}${THIS_LEG}
+        remote-type               active
+        heartbeat-time            15
+        heartbeat-slack-time      5
+end-peer
+
+if "${FAILOVER}" == "ENABLED"
+        add-peer
+                label                   ${ADAPTER_NAME}${OTHER_LEG}
+                remote-type             active
+                remote-name             ${ADAPTER_NAME}${OTHER_LEG}
+                heartbeat-time          15
+                heartbeat-slack-time    5
+        end-peer
+endif
+
+add-data-service
+        service-name        ${ADAPTER_NAME}ContainerSvc${THIS_LEG}
+        include-pattern     ^/PRIVATE/[[email protected]]/TODO
+
+        add-source-group
+                required
+                if "${FAILOVER}" == "ENABLED"
+                        if "${LOAD_BALANCING}" == "ENABLED"
+                                #
+                                # Load balancing with 2 legs
+                                #
+                                add-priority
+                                        label   ${ADAPTER_NAME}${THIS_LEG}
+                                        label   ${ADAPTER_NAME}${OTHER_LEG}
+                                end-priority
+                        else
+                                #
+                                # Failover with 2 legs
+                                #
+                                add-priority
+                                        label   ${ADAPTER_NAME}${THIS_LEG}
+                                end-priority
+                                add-priority
+                                        label   ${ADAPTER_NAME}${OTHER_LEG}
+                                end-priority
+                        endif
+                else
+                        #
+                        # One leg only
+                        #
+                        add-priority
+                                label   ${ADAPTER_NAME}${THIS_LEG}
+                        end-priority
+                endif
+        end-source-group
+end-data-service

todo-template/blade/blade_config/bootstrap.conf

@@ -0,0 +1,5 @@
+define ADAPTER_NAME                 @adapterName@
+
+if "${ENV:CONFIG_BASE}x" == "x"
+    include-file               ${ccd}/environment-ide.conf
+endif

todo-template/blade/blade_config/fields.conf

@@ -0,0 +1,4 @@
+add-field   TYPE2_KEY   -2500
+
+add-field   operation       -3001
+add-field   description     -3002

todo-template/build.gradle

@@ -0,0 +1,96 @@
+import org.apache.tools.ant.filters.ReplaceTokens
+
+apply plugin: 'java'
+
+ext {
+    major = 0
+    minor = 0
+    patch = 0
+
+    adapterName = project.name
+    replacements = [
+            adapterName: adapterName,
+    ]
+}
+
+version = major + "." + minor + "." + patch
+
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    compile(group: 'com.caplin.platform.components.datasource', name: 'datasource-java', version: '6.2.+') { transitive = false }
+}
+
+jar {
+    manifest {
+        attributes(
+                'Main-Class': 'com.caplin.template.TodoTemplateAdapter',
+                "Class-Path": configurations.compile.collect { it.getName() }.join(' ')
+        )
+    }
+}
+
+
+task createKit(type: Zip, dependsOn: jar) {
+    archiveName = adapterName + "-" + version + ".zip"
+    def topDirName = archiveName.substring(0, archiveName.lastIndexOf("."))
+
+    into("${topDirName}") {
+        from "${project.projectDir}/blade"
+        include 'blade_config/bootstrap.conf'
+        if (!project.hasProperty("configOnly")) {
+            include 'DataSource/bin/start-jar.sh'
+        }
+        filter(ReplaceTokens, tokens: replacements)
+    }
+
+    into("${topDirName}") {
+        from "${project.projectDir}/blade"
+        exclude 'blade_config/bootstrap.conf'
+        exclude 'DataSource/bin/start-jar.sh'
+    }
+
+    if (!project.hasProperty("configOnly")) {
+        into("${topDirName}/DataSource/lib") {
+            from([project.jar.outputs, configurations.compile])
+        }
+    }
+}
+
+task setupWorkingDirectory(type: Copy) {
+
+    from("${project.projectDir}/blade") {
+        include 'blade_config/bootstrap.conf'
+        filter(ReplaceTokens, tokens: replacements)
+    }
+    from("${project.projectDir}/blade") {
+        exclude 'blade_config/bootstrap.conf'
+        exclude 'DataSource/bin'
+        exclude 'Liberator'
+        exclude 'Transformer'
+    }
+    into("${buildDir}/env")
+}
+
+task createEnvironmentConfig << {
+    String thisLeg = (project.hasProperty("thisLeg") ? project.thisLeg : "1")
+
+    String content = """
+                     define THIS_LEG                            ${thisLeg}
+                     define LIBERATOR${thisLeg}_HOST            ${(project.hasProperty("liberatorHost") ? project.liberatorHost : "localhost")}
+                     define LIBERATOR${thisLeg}_DATASRCPORT     ${(project.hasProperty("liberatorDsPort") ? project.liberatorDsPort : "15001")}
+                     define TRANSFORMER${thisLeg}_HOST          ${(project.hasProperty("transformerHost") ? project.transformerHost : "localhost")}
+                     define TRANSFORMER${thisLeg}_DATASRCPORT   ${(project.hasProperty("transformerDsPort") ? project.transformerDsPort : "15002")}
+                     """.stripIndent()
+
+
+    new File("${setupWorkingDirectory.getDestinationDir().getAbsolutePath()}/blade_config/").mkdirs()
+    new File("${setupWorkingDirectory.getDestinationDir().getAbsolutePath()}/blade_config/environment-ide.conf").text=content
+}
+
+setupWorkingDirectory.finalizedBy createEnvironmentConfig
+
+assemble.dependsOn(createKit)

todo-template/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+#Thu Nov 24 12:19:48 GMT 2016
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-3.2-bin.zip