By default, the Elastic Path Commerce publishes event messages to JMS Topics and consumes them using nondurable subscribers. This is ideal for development purposes as it requires no configuration. However, this configuration will cause messages to be lost if the subscribers are offline, making it not ideal for production.

In production, you can use one of the following consumption approaches, each with varying benefits:

1. Configure the event message consumers to be Durable Subscribers
2. Use virtual destinations (recommended when available)
3. Implement a recipient list consumer to forward messages to multiple queues (recommended when virtual destinations not available)

You can configure the subscribers to your JMS topics so that subscribers are durable, which allows subscribers to still receive messages while offline. However, durable subscribers don't support competing consumers. This means running multiple instances of each JMS consumer application will result in each message being processed multiple times. For this reason, when using durable subscribers, we advise you to run only a single instance of each JMS consumer application. Consider the other approaches if you want to run multiple instances of each JMS consumer application.

To configure a durable subscriber, you'll need to set two additional identifiers: A clientId, which is a unique identifier at the application level, and a durableSubscriptionName, which identifies each topic subscription.

The application-level client ID can be configured by overriding the jmsConfig Spring bean in your extension project and adding an additional clientId property.

<bean id="jmsConfig" parent="jmsConfigTemplate">
	<property name="clientId" value="YOUR_APPLICATION_CLIENT_IDENTIFIER"/commerce-legacy/>
</bean>

Each topic subscription requires a unique identifier as the application may have multiple subscriptions to the same topic for different purposes. For example, the Commerce Engine has one subscriber to the "ep.orders" topic that sends order confirmation emails, and another subscriber to the same topic that sends order shipment confirmation emails. To use durable subscribers, each of these subscribers must supply a unique durableSubscriptionName.

To add thedurableSubscriptionName property, append it to the Endpoint URI definition as a query parameter in the format jms:topic:ep.messagetopic?durableSubscriptionName=mySubscriber.

You can configure the existing subscribers in the Commerce Engine to support a durableSubscriptionName by adding a context to the relevant settings framework value.

The following table shows the necessary configuration to utilize durable subscribers with all of the default Commerce Engine message consumers. Note that these context values do not exist by default and will have be created.

Virtual destinations gives the dual benefits of a decoupled publisher/subscriber architecture and reliable load-balancing of message processors.

We recommend you configure the Commerce Engine to publish messages to virtual destinations instead of standard JMS topics as this allows clusters of competing consumers to each subscribe to queues, which represent the topic, without processing every message multiple times.

The following example demonstrates a cluster of two identical Integration servers 1 and 2 that each contain two JMS consumers A and B that subscribe to the "ep.orders" virtual topic:

To utilize virtual destinations, register each subscriber component within the Commerce Engine as an individual output queue within the virtual topic. For example, to accommodate both the message consumer that creates order confirmation emails and the message consumer that creates order shipment confirmation emails, the "ep.orders" virtual topic should be configured with two virtual destination queues: "ep.orders.OrderConfirmation" and "ep.orders.OrderShipmentConfirmation". Each of these would exist as JMS queues to which all messages on the "ep.orders" topic are published.

Virtual destinations are configured within the JMS Broker; please refer to the broker's documentation for detailed configuration instructions.

After configuring the virtual destinations within the JMS broker, add the following settings context values to configure each subscriber's assigned queue. Refer to the "Suggested value" column for sample queue names.

If your JMS Broker doesn't support virtual destinations, you can choose to implement a recipient list consumer to replicate the behaviour of virtual destinations.

Your recipient list consumer should be configured with a list of all of the output JMS queue endpoints, as shown in the following section, and should publish all messages on the incoming queue to each of the required queues. In the following example, each recipient list consumer would forward every incoming message on the "ep.orders" queue to queues "ep.orders.A" and "ep.orders.B".

When utilizing the recipient list consumer approach, configure the settings outlined for the virtual destinations approach, then reconfigure the input endpoints to be queues rather than topics.

The following describes a sample recipient list message forwarding route builder and its Spring XML configuration:

public class SampleRecipientListMessageForwardingRouteBuilder extends RouteBuilder {
 
	private Endpoint incomingEndpoint;
	private Collection<Endpoint> outgoingEndpoints;

	@Override
	public void configure() throws Exception {
		from(incomingEndpoint)
			.transacted()
			.to(outgoingEndpoints);
	}
 
	// getters and setters
 
}

<beans
        xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:camel="http://camel.apache.org/schema/spring"
		xmlns:util="http://www.springframework.org/schema/util"
        xsi:schemaLocation="
                http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
				http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.xsd
                http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
        ">
 
    <camel:camelContext id="sample-recipient-list-forwarder" xmlns="http://camel.apache.org/schema/spring">
		<routeBuilder ref="sampleRecipientListMessageForwardingRouteBuilder"/commerce-legacy/>
    </camel:camelContext>
  
	<bean id="sampleRecipientListMessageForwardingRouteBuilder" class="com.example.SampleRecipientListMessageForwardingRouteBuilder">
		<property name="incomingEndpoint">
			<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
				<property name="camelContextId" value="sample-recipient-list-forwarder" />
				<property name="uri" value="jms:ep.eventmessagetype"/commerce-legacy/>
			</bean>
		</property>
		<property name="outgoingEndpoints">
			<util:list>
				<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
					<property name="camelContextId" value="sample-recipient-list-forwarder" />
					<property name="uri" value="jms:ep.eventmessagetype.Queue1"/commerce-legacy/>
				</bean>
				<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
					<property name="camelContextId" value="sample-recipient-list-forwarder" />
					<property name="uri" value="jms:ep.eventmessagetype.Queue2"/commerce-legacy/>
				</bean>
				<bean class="org.apache.camel.spring.CamelEndpointFactoryBean">
					<property name="camelContextId" value="sample-recipient-list-forwarder" />
					<property name="uri" value="jms:ep.eventmessagetype.Queue3"/commerce-legacy/>
				</bean>
				<!-- etc. -->
			</util:list>
		</property>
	</bean>
 
</beans>

The list of outgoing queues to create for each Commerce Engine event message channel can be found in the virtual destination configuration table.