Running HybridEdge

HybridEdge allows you to connect Solace PubSub+ with other any messaging system that is supported by Apache Camel, such as ActiveMQ, RabbitMQ, IBM MQ and Kafka. HybridEdge comes bundled with Solace JMS, ActiveMQ and RabbitMQ Camel Components. The Solace JMS Camel Component uses the Solace JMS client API and leverages the Camel JMS component. Solace HybridEdge and its associated samples can be found here.

Instructions for Running HybridEdge

Follow these steps to get HybridEdge up-and-running. Please note that when the instructions refer to the 'current directory' they mean the directory that contains the README.html file and run scripts.

  1. This step is optional and only necessary if you are connecting to a legacy messaging system other than ActiveMQ or RabbitMQ: Download a Camel component jar file for the system you wish to connect to and copy the file to the jars directory.
  2. If you want to try the sample Processor, copy samples/MyProcessor.class into the current directory. The Camel configuration file samples/hybrid-edge.xml is set up to use this processor.
  3. Copy the application.properties file from the samples directory into the current directory and edit it. Enter the Solace host URL, message vpn name, username, and password as appropriate. Also the spring.main.sources property should have the name of the config file you are using. The file should then look something like this:

    # Solace credentials
    solace.jms.host=mr-xxxxxx.messaging.solace.cloud:20000
    solace.jms.msgVpn=myvpn
    solace.jms.clientUsername=my-client-username
    solace.jms.clientPassword=a3i5gm9r1n3s05sc3384k9mlhs
    # Camel/Spring config files should be listed here.
    spring.main.sources=hybrid-edge.xml
    # Required so that Camel will keep running
    camel.springboot.main-run-controller=true

  4. Find a sample config file in the samples directory that is named after the third-party system you wish to connect to. Copy that file into the current directory. For example, if you are using RabbitMQ, copy samples/rabbitmq.xml into the current directory.
  5. Edit the config file that you copied in the previous step. Change the topic or queue names and the connection properties as required.
  6. Execute the run script.

Solace JMS Endpoint Properties

A Solace Camel JMS endpoint has the following structure:

solace-jms: topic|queue : topicOrQueueName [? property=value [& property=value] ... ]

For example:

solace-jms:topic:/my/topic?deliveryMode=2&timeToLive=60000

Note that in an xml file, ampersands need to be written as & and the greater-than symbol needs to be written as >

The Solace JMS component reuses the standard Camel JMS component because it supports the same set of properties. Refer to the Camel JMS component documentation for details.

Solace JMS Connection Factory Properties

It's necessary to configure the Solace JMS Connection Factory properties as well as those on the JMS endpoint. This is done by editing the Spring application.properties file. An example was presented in Instructions for Running HybridEdge, but for reference here's the list of supported properties.

Required:

solace.jms.host
solace.jms.msgVpn
solace.jms.clientUsername
solace.jms.clientPassword

Optional:

solace.jms.clientDescription
solace.jms.compressionLevel
solace.jms.connectionRetries
solace.jms.connectionRetriesPerHost
solace.jms.connectTimeoutInMillis
solace.jms.deliveryMode
solace.jms.directTransport
solace.jms.dynamicDurables
solace.jms.keepAliveCountMax
solace.jms.keepAliveIntervalInMillis
solace.jms.readTimeoutInMillis
solace.jms.reconnectRetries
solace.jms.reconnectRetryWaitInMillis
solace.jms.respectTtl
solace.jms.sslCipherSuites
solace.jms.sslTrustedCommonNameList
solace.jms.sslTrustStore
solace.jms.sslTrustStoreFormat
solace.jms.sslTrustStorePassword
solace.jms.sslValidateCertificate
solace.jms.sslValidateCertificateDate

See the Solace JMS API documentation and the JMS Properties Reference for details on these properties. Also note that the clientDescription property defaults to showing the component and underlying Camel versions, for example, CamelSolaceJMS version 1.0.0 Camel version: 2.21.0

Connection Factory Session Caching

This component uses Spring's CachingConnectionFactory to cache connections. By default the cache size is 10.

You can increase the cache size by setting this property,

solace.jms.sessionCacheSize

Property Setting Methods

Solace JMS Connection Factory properties can be set using either Java system properties or environment variables rather than using the application.properties file since the component uses Spring.

Java System Properties

On the command line you can set properties like this:

java -Dsolace.jms.host=myhost.com ...

Environment Variables

You can set properties as environment variables using this form:

SOLACE_JMS_HOST=myhost.com
SOLACE_JMS_MSG_VPN=vpn1

Property Settings for Specific Use-Cases

In this section we'll present the recommended property settings for a number of common use-cases

Guaranteed Messaging Acknowledgments

Consider the case of subscribing from Solace PubSub+ and publishing to another JMS broker, and in addition there is no need to acknowledge a message from Solace PubSub+ until you are sure that the message was received on the other broker.

You'll want to ensure that the directTransport property is false (which is the default)

solace.jms.directTransport=false

As well, you'll need to ensure that the transacted property is set on the Solace endpoint, for example,

<c:from uri="solace-jms:queue:testQueue?transacted=true"/>

Encrypting Passwords

HybridEdge supports the Camel method of encrypting passwords, which uses the jasypt library. The following steps show how to perform password encryption (Please see the examples in samples/encryption).

  1. Download these jars from Maven Central:

    camel-jasypt-2.21.1.jar or later

    jasypt-1.9.2.jar or later

  2. Pick a password that will be used to encrypt and decrypt your Solace password, for example, myCamelPassword.
  3. Run the following command to encrypt your Solace password, for example mySolacePassword:

    java -cp "camel-jasypt-2.21.1.jar:jasypt-1.9.2.jar" org.apache.camel.component.jasypt.Main -c encrypt -p myCamelPassword -i mySolacePassword

    Note:  In Windows, the classpath separator used in the -cp argument should be a semicolon, not a colon).

    jasypt will respond with something like this:

    Encrypted text: mCdmWUhQSQu+1AYUGq48R75WfUanyOf3lV6i89IKZt0=

    Surround the encrypted password with ENC(...) and put it into your application.properties file like this:

    solace.jms.clientPassword=ENC(mCdmWUhQSQu+1AYUGq48R75WfUanyOf3lV6i89IKZt0=)

  4. To finish, provide the jasypt password as a system property in the HybridEdge command line or as an environment variable:

    java -Djasypt.password=myCamelPassword ...

    or

    export JASYPT_PASSWORD=myCamelPassword

Solace JMS Headers

Solace generates extra headers:

JMS_Solace_DeadMsgQueueEligible
JMS_Solace_DeliverToOne
JMS_Solace_ElidingEligible

Although this is permissible according to the JMS specification, some JMS providers might reject messages with these headers. Therefore a processor is included which, when used, will remove any headers with names starting with JMS_Solace.

To use it, add this line to your route xml config file:

<bean id="stripSolaceHeadersProcessor" class="com.solace.camel.component.jms.StripSolaceHeadersProcessor"/>

and then include it in your route like this:

<c:from uri="solace-jms:queue:myQueue"/>
<c:bean ref="stripSolaceHeadersProcessor"/>
<c:to uri="wmq:queue:inQueue"/>

Third-Party Component Instructions

RabbitMQ

Change hostname in the endpoint as appropriate. Add any additional properties as required, including credentials.

Refer to samples/rabbitmq.xml for an example of how to configure the RabbitMQ component. Configuration instructions can be found here.

ActiveMQ

Change brokerURL property value in the bean definition as appropriate. Add any additional properties as required, including credentials.

Refer to samples/activemq.xml for an example of how to configure the ActiveMQ component. Configuration instructions can be found here.