PublishMQ SPI Implementation

Table of ContentsScreenshots 2

Invoke an action 3

How to configureuse 6

Classpath 6

Configuration Properties 7

Bootstrapping 7

Configure ActiveMQ 8

Canonical DTOs 10

Generate Canonical DTO referencing Apache Isis DTOs 10

Centralized Spring configuration 10

Database Migrations 11

Known issues 12

Submodules 13

publishmqservicespi 13

publishmqjdo 13

publishmqcamel 14

publishmqstatusclient 14

Dependencies 15

This module (isis-module-publishmq) provides an implementation of Apache IsisPublisherService SPI that submits an XML representation of anMemberInteractionDtos to an ActiveMQ queue

The quickstart app also demonstrates how this member interaction event(action invocation or property edit) can be routed using Apache Camel wherebythe payload is enriched using Apache Isis own Restful Objects viewer (obtainingadditional information)

The diagram below shows the moving parts

One of the design objectives for the PublishMq module is to allow the ActiveMQqueue (and therefore any Camel routing) to be either embedded (as in theexample app) or to be remote This is one of the reasons why the payload postedto the queue is the XML representation of a JAXB object (the InvocationDto)

Note that the example app does not include an external system(General Ledger in the diagram) ie step 12

1

Table of ContentsScreenshots 2

Invoke an action 3

How to configureuse 6

Classpath 6

Configuration Properties 7

Bootstrapping 7

Configure ActiveMQ 8

Canonical DTOs 10

Generate Canonical DTO referencing Apache Isis DTOs 10

Centralized Spring configuration 10

Database Migrations 11

Known issues 12

Submodules 13

publishmqservicespi 13

publishmqjdo 13

publishmqcamel 14

publishmqstatusclient 14

Dependencies 15

This module (isis-module-publishmq) provides an implementation of Apache IsisPublisherService SPI that submits an XML representation of anMemberInteractionDtos to an ActiveMQ queue

The quickstart app also demonstrates how this member interaction event(action invocation or property edit) can be routed using Apache Camel wherebythe payload is enriched using Apache Isis own Restful Objects viewer (obtainingadditional information)

The diagram below shows the moving parts

One of the design objectives for the PublishMq module is to allow the ActiveMQqueue (and therefore any Camel routing) to be either embedded (as in theexample app) or to be remote This is one of the reasons why the payload postedto the queue is the XML representation of a JAXB object (the InvocationDto)

Note that the example app does not include an external system(General Ledger in the diagram) ie step 12

1

This module (isis-module-publishmq) provides an implementation of Apache IsisPublisherService SPI that submits an XML representation of anMemberInteractionDtos to an ActiveMQ queue

The quickstart app also demonstrates how this member interaction event(action invocation or property edit) can be routed using Apache Camel wherebythe payload is enriched using Apache Isis own Restful Objects viewer (obtainingadditional information)

The diagram below shows the moving parts

One of the design objectives for the PublishMq module is to allow the ActiveMQqueue (and therefore any Camel routing) to be either embedded (as in theexample app) or to be remote This is one of the reasons why the payload postedto the queue is the XML representation of a JAXB object (the InvocationDto)

Note that the example app does not include an external system(General Ledger in the diagram) ie step 12

1

ScreenshotsThe modulersquos functionality can be explored by running the quickstart with example usage using theorgincodedomainappexampleappmodulesExampleDomSpiPublishMqAppManifest

A home page is displayed when the app is run

This returns the first demo object (an instance of PublishMqDemoObject)

2

Invoke an actionThe updateName() action is defined as

Action( semantics = SemanticsOfIDEMPOTENT publishing = PublishingENABLED ①)public PublishMqDemoObject updateName( ParameterLayout(named=Name) final String name) setName(name) return this

① invocations of this action will be published to the configured implementation ofPublishingService

Invoke the action

the value of the name property should of course be updated

3

From the activity menu the published events (also persisted as entities) can be inspected

one of which is to update the name

4

The published entity contains XML which captures the details of the member interaction

5

How to configureuseYou can either use this module out-of-the-box or you can fork this repo and extend to your ownrequirements

The module itself consists of several submodules

bull the publishmq-dom-servicespi submodule

which contains the PublishingService SPI implementation that actually publishes to anActiveMQ queue

bull the (optional but recommended) publishmq-dom-jdo submodule

which allows published events to be persisted as PublishedEvent entities

bull the (optional) publishmq-dom-camel submodule

which provides utility class to help route messages

bull the (optional) publishmq-dom-statusclient

that provides utility classes to log status messages with the originating system via theRestfulObjects viewerrsquos REST API

ClasspathUpdate your classpath

bull by adding importing the parent modulersquos dependency into in your parent modulersquos pomxml

ltdependencyManagementgt ltdependenciesgt ltdependencygt ltgroupIdgtorgisisaddonsmodulepublishmqltgroupIdgt ltartifactIdgtisis-module-publishmq-domltartifactIdgt ltversiongt$incode-platformversionltversiongt lttypegtpomlttypegt ltscopegtimportltscopegt ltdependencygt ltdependenciesgtltdependencyManagementgt

where incode-platformversion property is set appropriately for the version

bull by adding the -dom-servicespi dependency in your projectrsquos dom modulersquos pomxml

6

ltdependenciesgt ltdependencygt ltgroupIdgtorgisisaddonsmodulepublishmqltgroupIdgt ltartifactIdgtisis-module-publishmq-dom-servicespiltartifactIdgt ltdependencygt ltdependenciesgt

bull (if you are using Camel for routing and want to use the AddExchangeHeaders utility class) byadding (in the appropriate module within your app) the dependency

ltdependenciesgt ltdependencygt ltgroupIdgtorgisisaddonsmodulepublishmqltgroupIdgt ltartifactIdgtisis-module-publishmq-dom-camelltartifactIdgt ltdependencygt ltdependenciesgt

Note that the quickstart with embedded camel configures this already so use as aguide if need be

Check for later releases by searching Maven Central Repo

Configuration PropertiesIn isisproperties

isisproperties

isisservicesPublisherServiceUsingActiveMqvmTransportUri=vmbrokerisisservicesPublisherServiceUsingActiveMqmemberInteractionsQueue=memberInteractionsQueueisisservicesPublisherServiceUsingActiveMqenabled=true

The properties shown above are the defaults

BootstrappingIn the AppManifest update its getModules() method eg

7

ltdependenciesgt ltdependencygt ltgroupIdgtorgisisaddonsmodulepublishmqltgroupIdgt ltartifactIdgtisis-module-publishmq-dom-servicespiltartifactIdgt ltdependencygt ltdependenciesgt

bull (if you are using Camel for routing and want to use the AddExchangeHeaders utility class) byadding (in the appropriate module within your app) the dependency

ltdependenciesgt ltdependencygt ltgroupIdgtorgisisaddonsmodulepublishmqltgroupIdgt ltartifactIdgtisis-module-publishmq-dom-camelltartifactIdgt ltdependencygt ltdependenciesgt

Note that the quickstart with embedded camel configures this already so use as aguide if need be

Check for later releases by searching Maven Central Repo

Configuration PropertiesIn isisproperties

isisproperties

isisservicesPublisherServiceUsingActiveMqvmTransportUri=vmbrokerisisservicesPublisherServiceUsingActiveMqmemberInteractionsQueue=memberInteractionsQueueisisservicesPublisherServiceUsingActiveMqenabled=true

The properties shown above are the defaults

BootstrappingIn the AppManifest update its getModules() method eg

7

Override public ListltClassltgtgt getModules() return ArraysasList( orgisisaddonsmodulepublishmqPublishMqModuleclass )

You might also need to specify the package for any new services that you have written egimplementation of ContentNegotiationService or similar

Configure ActiveMQConfigure ActiveMQ so that the publishing service implementation can post to a queue calledmemberInteractionsQueue

In the quickstart with embedded camel app this is done using Spring (activemq-configxml)

ltbeans xmlns=httpwwwspringframeworkorgschemabeans xmlnsxsi=httpwwww3org2001XMLSchema-instance xsischemaLocation=httpwwwspringframeworkorgschemabeanshttpwwwspringframeworkorgschemabeansspring-beansxsd httpactivemqapacheorgschemacorehttpactivemqapacheorgschemacoreactivemq-corexsdgt ltbroker xmlns=httpactivemqapacheorgschemacore brokerName=broker dataDirectory=$activemqdata useShutdownHook=false useJmx=true gt ltdestinationsgt ltqueue physicalName=memberInteractionsQueuegt ltdestinationsgt ltbrokergtltbeansgt

This is bootstrapped in the webxml

8

ltlistenergt ltlistener-classgtorgspringframeworkwebcontextContextLoaderListenerltlistener-classgtltlistenergtltcontext-paramgt ltparam-namegtcontextConfigLocationltparam-namegt ltparam-valuegt classpathactivemq-configxml ltparam-valuegtltcontext-paramgt

9

Canonical DTOsThe quickstart with embedded camel app contains a few other little tricks that may be useful if youare looking to deploy a similar architecture for your own application

Generate Canonical DTO referencing Apache IsisDTOsAs of 1130 Apache Isis includes the ixnxsd (member interaction) schema (replacing andgeneralizing the aimxsd provided from 190 through 112x) The PublishingServiceMq uses thisixnxsd schema (or rather its Java JAXB equivalent InteractionDto) directly

The similar commonxsd is also used by the demo app in the construction of its own canonicalDemoObjectDto (use of OidDto to represent a bookmark to a published domain object)

Centralized Spring configurationIn the example app Spring is used to bootstrap ActiveMQ (activemq-configxml) and Camel (camel-configxml) and also the fake SOAP Subscriber (externalSystemFakeServer-configxml) Theconfiguration for all is centralized through a propertyPlaceholderConfigurer bean (defined inpropertyPlaceholderConfigurer-configxml) The location of the property file is specified in thewebxml

ltcontext-paramgt ltparam-namegtspringconfigfileltparam-namegt ltparam-valuegtclasspathspringpropertiesltparam-valuegtltcontext-paramgt

where springproperties is

activemqdata=activemq-dataenrichWithCanonicalDtobase=httplocalhost8080restfulenrichWithCanonicalDtousername=svenenrichWithCanonicalDtopassword=passupdateExternalSystemAdapterendpointAddress=httplocalhost8080soapExternalSystemAdapterDemoObject

If necessary the location of this config file can be overridden see this topic in the Apache Isis userguide

10

Canonical DTOsThe quickstart with embedded camel app contains a few other little tricks that may be useful if youare looking to deploy a similar architecture for your own application

Generate Canonical DTO referencing Apache IsisDTOsAs of 1130 Apache Isis includes the ixnxsd (member interaction) schema (replacing andgeneralizing the aimxsd provided from 190 through 112x) The PublishingServiceMq uses thisixnxsd schema (or rather its Java JAXB equivalent InteractionDto) directly

The similar commonxsd is also used by the demo app in the construction of its own canonicalDemoObjectDto (use of OidDto to represent a bookmark to a published domain object)

Centralized Spring configurationIn the example app Spring is used to bootstrap ActiveMQ (activemq-configxml) and Camel (camel-configxml) and also the fake SOAP Subscriber (externalSystemFakeServer-configxml) Theconfiguration for all is centralized through a propertyPlaceholderConfigurer bean (defined inpropertyPlaceholderConfigurer-configxml) The location of the property file is specified in thewebxml

ltcontext-paramgt ltparam-namegtspringconfigfileltparam-namegt ltparam-valuegtclasspathspringpropertiesltparam-valuegtltcontext-paramgt

where springproperties is

activemqdata=activemq-dataenrichWithCanonicalDtobase=httplocalhost8080restfulenrichWithCanonicalDtousername=svenenrichWithCanonicalDtopassword=passupdateExternalSystemAdapterendpointAddress=httplocalhost8080soapExternalSystemAdapterDemoObject

If necessary the location of this config file can be overridden see this topic in the Apache Isis userguide

10

Database Migrationsbull 88 - add sequence to StatusMessage

Search for issue-88-add-sequence-to-StatusMessage-pksql in this repo

bull 89 - change order of PublishedEvent pk

Search for issue-89-change-order-of-PublishedEvent-pksql in this repo

11

Known issuesNone known at this time

12

SubmodulesThe publishmq module actually consists of four distinct submodules which can be used to someextend independently

publishmqservicespiMaven can report modules dependencies of this submodule using

mvn dependencylist -o -pl modulesspipublishmqimplservicespi -DexcludeTransitive=true

which excluding Incode Platform and Apache Isis modules returns these compileruntimedependencies

orgapacheactivemqactivemq-alljar5111

For further details on 3rd-party dependencies see

bull Apache ActiveMQ

publishmqjdoThis submodule can be considered optional (though its use is recommended) If not included thenpublished messages are simply not persisted as JDO entities

Maven can report modules dependencies of this submodule using

mvn dependencylist -o -pl modulesspipublishmqimpljdo -D excludeTransitive=true

which excluding Incode Platform and Apache Isis modules returns these compileruntimedependencies

orgslf4jslf4j-apijar1721

From the Incode Platform it uses

bull publishmqservicespi submodule above

For further details on 3rd-party dependencies see

bull Slf4J

13

SubmodulesThe publishmq module actually consists of four distinct submodules which can be used to someextend independently

publishmqservicespiMaven can report modules dependencies of this submodule using

mvn dependencylist -o -pl modulesspipublishmqimplservicespi -DexcludeTransitive=true

which excluding Incode Platform and Apache Isis modules returns these compileruntimedependencies

orgapacheactivemqactivemq-alljar5111

For further details on 3rd-party dependencies see

bull Apache ActiveMQ

publishmqjdoThis submodule can be considered optional (though its use is recommended) If not included thenpublished messages are simply not persisted as JDO entities

Maven can report modules dependencies of this submodule using

mvn dependencylist -o -pl modulesspipublishmqimpljdo -D excludeTransitive=true

which excluding Incode Platform and Apache Isis modules returns these compileruntimedependencies

orgslf4jslf4j-apijar1721

From the Incode Platform it uses

bull publishmqservicespi submodule above

For further details on 3rd-party dependencies see

bull Slf4J

13

publishmqcamelThis submodule is considered optional because it merely provides a supporting utility class(AddExchangeHeaders)

Maven can report modules dependencies of this submodule using

mvn dependencylist -o -pl modulesspipublishmqimplcamel -D excludeTransitive=true

which excluding Apache Isis modules returns these compileruntime dependencies

orgapachecamelcamel-corejar2152orgapachecamelcamel-springjar2152orgapachecamelcamel-spring-javaconfigjar2152orgapachecamelcamel-jmsjar2152

For further details on 3rd-party dependencies see

bull Apache Camel

publishmqstatusclientThis submodule is considered optional it provides the mechanism for a beans within a Camel routeto report status back to the originating system via the RestfulObjects viewerrsquos REST API

Using the status client requires the originating system to have configuredpublishmqjdo to persist the status messages

Maven can report modules dependencies of this submodule using

mvn dependencylist -o -pl modulesspipublishmqimplstatusclient -DexcludeTransitive=true

which excluding Apache Isis modules returns these compileruntime dependencies

orgslf4jslf4j-apijar1721orgjbossspecjavaxwsrsjboss-jaxrs-api_20_specjar100Finalcomfasterxmljacksoncorejackson-databindjar280

For further details on 3rd-party dependencies see

bull Slf4J

bull Jackson

14

DependenciesIn addition to Apache Isis this module also depends upon

bull ActiveMQ

bull (optional) Camel

15