permissioning-template

Caplin Permissioning Adapter Template

This project provides a starting point for writing permissioning integration adapters based on Caplin's Java DataSource API and Caplin's Java Permissioning API. Permissioning integration adapters provide real-time permissioning configuration to Caplin's Permissioning Service, a Liberator auth module. For more information about Caplin's Permissioning Service, see Liberator: User Authentication and Permissioning.

This template is a Gradle project. To avoid compatibility issues between the version of Gradle required by the project and the version of Gradle installed on your system, always run the project's Gradle tasks using the Gradle Wrapper from the root of the project: ./gradlew task

Note: the Gradle Wrapper requires an Internet connection. For more information, see Executing a build with the Wrapper in the Gradle documentation.

Getting started

Follow the instructions below to create a new adapter project based on the Permissioning Adapter Template.

Copy and customise the template

1. Clone, or download and extract the latest version of the Caplin Project Templates repository:

   • Clone:

     $ git clone https://github.com/caplin/project-templates.git
     

   • Download:

     $ wget http://github.com/caplin/project-templates/archive/master.zip
     $ unzip -qoa master.zip
     

2. Copy the template directory permissioning-template and rename it to the name of your new project (for example, MyPermissioningAdapter):

   $ cp -r ./permissioning-template ~/src/MyPermissioningAdapter
   

3. Edit the file ~/src/MyPermissioningAdapter/settings.gradle, and change the value of the rootProject.name variable to the name of your adapter project (MyPermissioningAdapter). When you later export your project as an adapter blade, the project name will be used as the name for the blade.

4. If you have a Caplin website account and Internet access to https://repository.caplin.com, follow the steps below to enable automatic downloading of this project's Caplin dependencies:

   1. In your ~/.gradle/gradle.properties file (create it if it does not exist), add the following lines, replacing <username> and <password> with your Caplin credentials:

      caplinNexusUser=<username>
      caplinNexusSecret=<password>
      

5. If you don't have a Caplin website account and Internet access to https://repository.caplin.com, follow the steps below to manage this project's Caplin dependencies manually:

   1. In this project's build.gradle file, comment out the maven block for https://repository.caplin.com:

      /*maven {
          credentials {
              username "$caplinNexusUser"
              password "$caplinNexusSecret"
          }
          url "https://repository.caplin.com"
      }*/

   2. In this project's build.gradle file, uncomment the implementation fileTree(...) line in the dependencies block:

      dependencies {
          implementation fileTree(dir: 'lib', include: '*.jar')
          ...
      }

   3. Copy the following Caplin libraries to this project's lib directory:

      • Java DataSource API 7.1.x: datasource-version-jar-with-dependencies.jar

      • Java Permissioning API 7.0.x: permissioning-datasource-version.jar

Import your new project into an IDE

Follow the instructions below to import your new adapter project into Eclipse or IntelliJ IDEA.

Eclipse

These instructions require the Buildship Gradle Integration plugin. To install the plugin, click Help > Eclipse Marketplace and search for Buildship.

To import your project into Eclipse, follow the steps below:

1. In Eclipse, click File > Import. The Import dialog appears.

2. Click Existing Gradle Project. The Import Gradle Project dialog appears.

3. Under Project location, deselect Use default location.

4. In the Location field, select your adapter's project directory: ~/src/MyPermissioningAdapter

5. Click Finish.

IntelliJ IDEA

To import your project into IntelliJ IDEA, follow the steps below:

1. Click File > New > Project from existing sources

2. Select the project's Gradle build file: ~/src/MyPermissioningAdapter/build.gradle

Running your adapter within an IDE

Integration adapters are designed to run within the context of a Deployment Framework (DFW), but they can be configured to run within an IDE during their development. This saves you time and allows you to take advantage of your IDE's debugging tools.

Regardless of whether your adapter is running in your IDE or in a DFW, it needs a working directory and the configuration details of the Liberator or Transformer it connects to. How these requirements are met within an IDE depends on whether the Liberator or Transformer is local or remote to your development machine.

Running your adapter with a local Liberator or Transformer

This section describes how to connect an adapter in an IDE to a Liberator or Transformer in a Deployment Framework (DFW) on your local machine.

To provide Liberator or Transformer with your adapter's configuration, follow the steps below:

1. From the root of your project, run ./gradlew assemble -PconfigOnly. This command packages your adapter's configuration (but not the binary) within a config-only blade under build/distributions/.

2. Copy the config-only blade to the kits directory of your local DFW.

3. From the root of the local DFW, run the command ./dfw deploy to deploy the config-only blade.

4. From the root of the local DFW, run the command ./dfw versions to confirm that the config blade has been deployed.

Note: if you change your adapter's configuration, you must repeat the steps above.

To provide your adapter with a working directory and the configuration of the Liberator or Transformer it connects to, follow the steps below:

1. In your IDE, create a run configuration for the main class of your project:

   1. Set the run configuration's working directory to dfw_location/active_blades/adapter_name/DataSource, where dfw_location is the path to your local DFW, and adapter_name is the name of your adapter.

      Note: on Microsoft Windows, which does not recognise Unix-style symbolic links, use the path dfw_location\kits\adapter_name\adapter_name-version\DataSource

   2. Create a run-configuration environment variable CONFIG_BASE with the value dfw_location/global_config/, where dfw_location is the path to your local DFW. This provides your adapter with the path to the configuration of the Liberator or Transformer it connects to.

      Note: the value of CONFIG_BASE must end with a trailing slash.

2. Run the adapter using the new run configuration.

Running your adapter with a remote Liberator or Transformer

This section describes how to connect an adapter in an IDE to a Liberator or Transformer in a Deployment Framework (DFW) on a remote host.

To provide Liberator or Transformer with your adapter's configuration, follow the steps below:

1. From the root of your project, run ./gradlew assemble -PconfigOnly. This command packages your adapter's configuration (but not the binary) within a config-only blade under build/distributions/.

2. Copy the config-only blade to the kits directory of the remote DFW.

3. From the root of the remote DFW, run the command ./dfw deploy to deploy the config-only blade.

4. From the root of the remote DFW, run the command ./dfw versions to confirm that the config blade has been deployed.

To provide your adapter with a working directory and the configuration of the Liberator or Transformer it connects to, follow the steps below:

1. From the root of your project, run ./gradlew setupWorkingDirectory, specifying one or more of the properties listed below.

   The setupWorkingDirectory task creates a minimal execution environment for your adapter under build/env. The environment includes a working directory and the minimal configuration required to connect to the remote Liberator or Transformer.

   The setupWorkingDirectory build task accepts the following Gradle properties:

   • -PthisLeg=value: defaults to 1. Change this if you want to connect to the failover leg.

   • -PliberatorHost=value: defaults to localhost. This must be changed to the host that Liberator runs on.

   • -PliberatorDsPort=value: defaults to 15001. Change this if the Liberator uses a different DataSource port number.

   • -PtransformerHost=value: defaults to localhost. This must be changed to the host Transformer runs on.

   • -PtransformerDsPort=value: defaults to 15002. Change this if the Transformer uses a different DataSource port number.

2. Open the generated configuration file build/env/blade_config/environment-ide.conf and check that the configuration has been generated correctly. Make manual corrections to the file as required.

3. In your IDE, create a run configuration with the working directory set to build/env/DataSource.

4. Run the adapter using the new run configuration.

Note: if you change your adapter's configuration, you must repeat the steps above.

Setting JVM options

To pass options to the Java virtual machine (JVM) that runs your adapter in your IDE, add the JVM options to the adapter's run configuration.

To pass options to the Java virtual machine (JVM) that the Deployment Framework uses to run your adapter, export environment variable CAPLIN_BLADE_JAVA_OPTIONS. For example, to specify that the JVM has an initial heap size of 128MB and a maximum heap size of 256MB, add -Xms128m -Xmx256m as options to the java command, as shown below:

export CAPLIN_BLADE_JAVA_OPTIONS="-Xms128m -Xmx256m"

The JVM heap sizes in this example are illustrative only. Profile your adapter to determine the optimal values for your use cases.

Building and deploying the adapter blade

Follow the steps below to build and deploy your adapter.

1. From the root of your project, run ./gradlew assemble. This command packages your adapter in an adapter blade under build/distributions/.

2. Deploy the adapter blade to each Deployment Framework in your deployment infrastructure. For instructions on how to deploy an adapter blade to a Deployment Framework, see Deploy a custom blade.

How to report issues with the template

To report an issue with the template, please contact Caplin Support or raise an issue on GitHub.