incodehq/ixn-relay

Message relay, which forwards messages persisted to Outbox (Incode Platform's publishoutbox module) to a Message Broker.

This project has been archived to a private repo on gitlab

Interaction Relay

This microservice is a companion to the Incode Platform's publishmq module, an implementation of Apache Isis' PublisherService SPI. Its job is to relay interaction messages from the "outbox" of an Apache Isis application to a target message broker:

• the "outbox" is the OutboxEvent table in the Apache Isis database

• the message broker is ActiveMQ, though the architecture is pluggable so other broker implementations could also be supported.

When messages have been successfully relayed, they are removed from the outbox.

It can be used in conjunction with the incodehq/ixn-subscriber to publish messages from an Apache Isis application to an integration webapp (eg implemented using Apache Camel), but without either the Apache Isis app nor the integration app having knowledge of the other.

[ixn-relay] as ir
[Apache Isis\nApp] as app
[Integration\nApp] as ia
[ActiveMQ] as mb
[ixn-subscriber] as is

app <-d. ir
is -.r-> ia
mb .d-> is
ir -.r-> mb

Design

The relay doesn’t access the Apache Isis database directly, instead it uses the OutboxClient that is provided by the Incode Platform. The Apache Isis app in turn uses the OutboxEventService component (also part of the Incode Platform).

The diagram below sketches the main classes:

hide empty members

component "ixn-relay" {
    package spi {
        interface Relay {
            handle()
        }
    }

    package relay-mq {

        class RelayMq implements Relay {
        }
    }

    package webapp {

        class PollingRoute {
        }
        class Dispatcher {
        }
        class OutboxClient <<incode platform>> {
        }
    }
}

component ActiveMQ {
}

component "Apache Isis\nApp" {
    class "OutboxEventService" <<incode platform>> {
    }
}

OutboxClient .l-> OutboxEventService : "http GET"

PollingRoute .d-> Dispatcher
Dispatcher -> "0..*" Relay
Dispatcher -d-> OutboxClient

RelayMq .r-> ActiveMQ : JMS send

The PollingRoute is responsible for kicking off the Dispatcher periodically, which uses the OutboxClient to check if there are any messages in the outbox.

If so, the Dispatcher loops over all available Relay implementations.

Finally, the RelayMq implementation posts the interaction to the specified ActiveMQ JMS queue.

Configuration

This microservice has been implemented using Spring Boot, and so is configured using an application.yaml file:

logging:
  config: classpath:logback.xml

camel:
  springboot:
    main-run-controller: true

spring:
  activemq:
    broker-url: tcp://localhost:61616

app:
  relay-mq:
    queue-name:
      memberInteractionsQueue
  polling-period: 10s
  outbox-client:
    base: http://localhost:8080/restful/
    username: sven
    password: pass

  tracing:
    tracing-type: none

Note	If ApacheMQ broker is not running, then Camel will keep retrying. That’s because camel.springboot.main-run-controller is set to true.

Local Testing

Prereqs : Message Broker

This image requires an instance of Apache ActiveMQ to be running. The easiest way to do this is using the incodehq/activemq-mssqlserver Docker image. Note, this will default to using an in-memory database, so it has no hard pre-reqs itself.

For example:

export TAG=20191011.1912.master.880118bc

docker run -d -p61616:61616 -p8161:8161 incodehq/activemq-mssqlserver:$TAG

Then, log on using: http://localhost:8161

How to run the example

The configuration file above shows Camel configured to connect to a remote broker (tcp://localhost:61616).

To run, just use maven:

mvn -pl webapp spring-boot:run

Docker

A Docker image of this app is available at Docker hub.

To allow configuration to be easily externalized, the image expects a /run/secrets directory to exist, and switches to and then runs the application in that directory. Spring Boot will then automatically pick up that configuration and use it.

Typically therefore all that is required is to define an application.yaml or application.properties file as a secret. If the secret filename has a prefix, as may be the case for Docker swarm namespacing, (eg foo.bar.application.yaml) then a symbolic link (eg application.yaml) will be automatically created to the secret filename.