HybridEdge Starter Project

Introduction

HybridEdge is a Solace Corporation software product that makes it easy to connect existing systems, and in particular messaging systems, to Solace Messaging. It requires minimum setup and configuration.

The HybridEdge Starter Project allows developers to write more advanced integration products when more custom logic is required. It is based on Spring Boot and already contains the dependencies required to connect to a Solace messaging product.

Internally, it uses Apache Camel to connect with the integration points.

Usage

• Clone this repository by running

  git clone https://github.com/SolaceProducts/solace-hybridedge.git

• Edit src/main/resources/application.properties, adding the Solace host URL, message VPN name, username, and password as required. Prepend the host URL with smfs:// and use the corresponding TLS/SSL port if you want to use an encrypted connection. 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

• A sample configuration file is provided in src/main/resources/hybrid-edge.xml. You can test with that, or copy a sample Camel configuration file from the samples directory into the src/main/resources directory, and edit it as required (see below for more details). You can either rename it to hybrid-edge.xml, or change the spring.main.sources property in application.properties.

• Edit the build.gradle file, adding any required dependencies to Camel connectors such as ActiveMQ or RabbitMQ.

• Make sure the gradlew script is executable and then build the application by running

  ./gradlew assemble

• Start the application by running

  java -jar build/libs/hybrid-edge-starter.jar

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 >.

Because the Solace JMS Camel Component reuses the standard Camel JMS Component, it supports the same set of properties.

Please see the Camel JMS Component documentation for details.

Solace JMS Connection Factory Properties

Besides the properties on the JMS endpoint, it is necessary to configure the Solace JMS Connection Factory properties.

This is done by editing the Spring application.properties file. An example was given at the top of this document, but for reference, here is 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

Please see the Solace JMS API documentation and the JMS Properties Reference for details on these properties.

N.B. The clientDescription property defaults to showing the component and underlying Camel versions, e.g.

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 this by setting the property in the application.properties file:

solace.jms.sessionCacheSize

Methods of setting properties

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

Java system properties

On the command line you can set properties like this: java -Dsolace.jms.host=myhost.com ...

Environment Variables

You can set the properties as environment variables in this form:

SOLACE_JMS_HOST=myhost.com
SOLACE_JMS_MSG_VPN=vpn1

Properties for specific use cases

Guaranteed Messaging Acknowledgements

Suppose you are subscribing from a Solace instance and publishing to another JMS broker, and you don't want to acknowledge a message from Solace until you are sure that the message was received on the other broker.

In this case, you want to ensure that the directTransport property is false (which is the default anyway):

solace.jms.directTransport=false

Further, you need to ensure that the transacted property is set on the Solace endpoint, e.g.

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

Encrypting passwords

HybridEdge supports the Camel method of encrypting passwords. which uses the jasypt library.

Here are instructions on how to do this:

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, e.g. 'myCamelPassword'

3. Run this 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 that on Windows, the classpath separator used in the -cp argument should be a semicolon, not a colon).

   Jasypt will respond with something like:

   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. Finally, 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

The Solace JMS API 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 as a bean definition to your Camel XML configuration 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 Components

Here are some product-specific instructions.

RabbitMQ

Use the file samples/rabbitmq.xml as a reference. Change the hostname in the endpoint as appropriate. Add any additional properties as required, including credentials.

Configuration instructions are here: http://camel.apache.org/rabbitmq.html

ActiveMQ

Use the file samples/activemq.xml as a reference. In particular, note the bean configuration:

<bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
    <property name="brokerURL" value="tcp://localhost:61616"/>
</bean>

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

Configuration instructions are here: http://camel.apache.org/activemq.html