Installing Bridges to InterMW

Bridge installation to an InterMW instance consists of the following steps:

  • copying bridge JAR file together with its dependencies to the INTER-MW webapp library inside the INTER-MW Docker container
  • copying bridge configuration file (if any) to the INTER-MW configuration directory
  • restarting INTER-MW
  • creating IPSM alignments and channels for the bridge

For an example of a bridge installation and a testing procedure, please see Bridge development guide.

Prerequisites

  • INTER-MW deployment which version must match the version of mw.bridges.api dependency used in the bridge POM file:
<dependency>
    <groupId>eu.interiot.intermw</groupId>
    <artifactId>mw.bridges.api</artifactId>
    <version>2.1.0-SNAPSHOT</version>
</dependency>

Version of the INTER-MW Docker deployment can be obtained by running docker ps command and checking the intermw image tag:

docker.inter-iot.eu/intermw:v2.1.0

Installing Bridge JARs

Build and package the bridge by running following Maven command:

mvn clean package

Copy the bridge JAR file created in the previous step to lib directory of INTER-MW webapp inside the INTER-MW Docker container using the following command:

docker cp <path-to-bridge-jar-file> <intermw-container>:/usr/local/tomcat/webapps/ROOT/WEB-INF/lib

To check whether bridge JAR file is available within the INTER-MW library, run the following command:

docker exec <intermw-container> ls -l /usr/local/tomcat/webapps/ROOT/WEB-INF/lib | grep <bridge-name>

In addition, you also have to copy into the INTER-MW library (i.e. lib directory) all runtime dependencies that are required by the bridge project and don't already exist there. Make sure that dependencies added to INTER-MW library don't cause dependency conflict. The mw.bridges.api dependency together with its sub-dependencies are already included in the INTER-MW library.

You can get a list of all dependencies available in INTER-MW library by listing lib directory content:

docker exec <intermw-container> ls -l /usr/local/tomcat/webapps/ROOT/WEB-INF/lib

To display dependency tree for the bridge project (runtime dependencies), run the following command:

mvn dependency:tree -Dscope=runtime

Installing Bridge Configuration File

In case the bridge requires a configuration file (e.g. ExampleBridge.properties), it has to be copied to the INTER-MW configuration directory:

docker cp src/main/resources/<bridge-config-file> <intermw-container>:/etc/inter-iot/intermw

Note: INTER-MW configuration directory is mapped to the intermw_config Docker volume to persist after the container is deleted.

To list the configuration directory content, run:

docker exec <intermw-container> ls -l /etc/inter-iot/intermw

Restarting INTER-MW

Finally, INTER-MW has to be restarted to detect new bridge. Run following command inside the INTER-MW Docker Compose deployment directory from where the INTER-MW was deployed:

docker-compose restart intermw

To make sure new bridge was detected and registered successfully, search for the string Registering bridges... in INTER-MW log file:

docker-compose logs intermw | grep -A 5 "Registering bridges"

In case of ExampleBridge, the following log statements can be found in the logs:

DEBUG eu.interiot.intermw.bridge.Context.registerBridges(Context.java:208) - Registering bridges...
DEBUG eu.interiot.intermw.bridge.Context.registerBridges(Context.java:210) - Scanning package eu.interiot...
DEBUG eu.interiot.intermw.bridge.Context.registerBridges(Context.java:214) - Following bridges have been found: [class eu.interiot.intermw.bridge.example.ExampleBridge]
DEBUG eu.interiot.intermw.bridge.Context.registerBridges(Context.java:220) - Bridge eu.interiot.intermw.bridge.example.ExampleBridge for platform type http://example.inter-iot.eu/example-platform has been registered.
DEBUG eu.interiot.intermw.bridge.Context.registerBridges(Context.java:224) - Bridge registration has finished successfully.

The term bridge registration means that the bridge class has been related to the corresponding platform type. Bridge is instantiated (an instance of Bridge class is created) when an actual platform is registered for specific platform type. See chapter Registering platform.

Creating IPSM Alignments and Channels for the Bridge

IPSM alignments and channels for the bridge can be created using IPSM Swagger UI available at http://localhost:8888/swagger/ (assuming local IPSM deployment on default port). Each platform instance requires its own IPSM channels.

Creating Alignments

Expand Alignments section and use POST /alignments operation to create new alignments by uploading alignment XML document.

Creating Channels

Expand Channels section and use POST /channels operation to create following two channels:

  • downstream channel: mw-ipsm-downstream-<platform-id> -> ipsm-mw-downstream-<platform-id>
  • upstream channel: mw-ipsm-upstream-<platform-id> -> ipsm-mw-upstream-<platform-id>

Use the syntax as follows to create the channels.

Downstream Channel

For IPSM version 0.4.* use the following format:

{
  "source": "mw-ipsm-downstream-<platform-id>",
  "inpAlignmentId": <alignment-id>,
  "outAlignmentId": 0,
  "sink": "ipsm-mw-downstream-<platform-id>",
  "parallelism": 1
}

For IPSM version 0.5.* use the following format:

{
  "source": "mw-ipsm-downstream-<platform-id>",
  "inpAlignmentName": "<name>",
  "inpAlignmentVersion": "<version>",
  "outAlignmentName": "<name>",
  "outAlignmentVersion": "<version>",
  "sink": "ipsm-mw-downstream-<platform-id>",
  "parallelism": 1
}

Upstream channel

For IPSM version 0.4.* use the following format:

{
  "source": "mw-ipsm-upstream-<platform-id>",
  "inpAlignmentId": <alignment-id>,
  "outAlignmentId": 0,
  "sink": "ipsm-mw-upstream-<platform-id>",
  "parallelism": 1
}

For IPSM version 0.5.* use the following format:

{
  "source": "mw-ipsm-upstream-<platform-id>",
  "inpAlignmentName": "<name>",
  "inpAlignmentVersion": "<version>",
  "outAlignmentName": "<name>",
  "outAlignmentVersion": "<version>",
  "sink": "ipsm-mw-upstream-<platform-id>",
  "parallelism": 1
}

where <platform-id> is encoded platform ID. Special characters must be replaced with underscore character, e.g. http://example.inter-iot.eu/platforms/1 is encoded to http_example.inter-iot.eu_platforms_1.