Guide - Messaging

Product Version

7.7

Product To Version

 
Status

final

1 Introduction

This guide introduces the event messaging system of Intershop Commerce Management from the configuration perspective. It is addressed to administrators or DevOps who configure and maintain Intershop Commerce Management instances.

Info

Prior to Intershop version 7.7 the information provided in this document were part of the Administration and Configuration Guide that can be found in the Knowledge Base.

Note

All relevant setup options are to be configured in advance via dedicated deployment script files, before actually executing the deployment. So be aware that if you modify the Intershop Commerce Management configuration after it is deployed, all changes will be overridden with the settings specified for your deployment.

The messaging cartridge is the Intershop Commerce Management component used to send event messages inside an Intershop Commerce Management cluster. It implements an API that integrates simple multicast messaging in addition to an extensible framework for adapting external messaging systems to Intershop Commerce Management. Currently, JMS and JGroups are supported out of the box; additional systems can be implemented on a project-specific base.

There are four types of events that are distributed. Each type uses a dedicated messaging channel. The name of the messaging channel is identical with the prefix of its corresponding configuration properties:

  • General application server events (event manager of the core cartridge)
    intershop.event, to be configured in <IS.INSTANCE.SHARE>/system/config/cluster/appserver.properties.
    For details about configuring general event messaging, see the tables below and Cookbook - Messaging.
  • Cache engine message events (cache cartridge)
    intershop.cacheengine.wrapped, to be configured in <IS.INSTANCE.SHARE>/system/config/cluster/cache.properties.
    For details about configuring cache engine messaging, see Guide - Cache Engine Administration.
  • ORM cache synchronization events (orm cartridge)
    intershop.cacheSync, to be configured in <IS.INSTANCE.SHARE>/system/config/cluster/orm.properties.
    For details about configuring ORM cache synchronization events, see Guide - ORM Engine Administration.
  • Tomcat cluster management events
    intershop.tcm.event, to be configured in <IS.INSTANCE.SHARE>/system/tcm/config/tcm.properties.
    For details about configuring cluster management event messaging, see Guide - Node Manager.

Note

If there are several Intershop Commerce Management clusters in one subnet, a cluster may receive events from a foreign cluster if both clusters happen to be using the same messaging channel (address) and port. In this case, you have to specify a unique messaging channel and port for each cluster.

Depending on the used messaging system (multicast, JMS, JGroups or a custom implementation), the set of specific properties may vary. But for convenience and compatibility reasons, the configuration of the existing messaging channels reside in the same properties files and start with the same prefix. That is, when configuring event messaging in your Intershop Commerce Management systems, you can select one of the three available messengers, where multicast is the default, by enabling and adjusting the corresponding pre-configured settings, or you can implement a custom solution using the pre-configured systems as a blueprint.

2 Multicast Messaging Setup

Multicast communication is the default method used for sending event messages between applications. Its configuration options are listed below:

Property

Description

messengerClass

Sets the messenger class to be used (required), the default is com.intershop.beehive.messaging.internal.multicast.MulticastMessenger.

multicastAddress

Sets the class D IP address of the multicast group (required). Supports values between 239.0.0.1 and 239.255.255.255.

multicastPort

Sets the UDP port for the multicast group (required). Any valid port number above 1024 is allowed.

multicastInterface

Sets the IP of the nework interface for outgoing packets. If there are multiple network adapters installed, you can specify the IP of the network interface to use for multicast messaging. This allows, for example, to separate administrative traffic from Web front traffic.

multicastTimeToLive

Sets the time to live for the multicast socket, used for multicast routing.

By default, multicast messages are sent only to systems on a local network. If the multicast messages are intended to be sent to distant networks, and if there is a special multicast router on the local network, the application can increase the scope of the multicast by using multicastTimeToLive property. The default time-to-live value is 1, which means the multicast is limited to a local network. If the value is 2, the multicast can forwarded through at most one gateway, and so forth. The maximum value is 255. Note again that in this case, the routers must be configured to pass the IP multicast traffic between the connected application server subnets.

multicastReceiveBufferSize

Sets the size of the ReceiveBuffer for packets, should be configured in the underlying operating system as well.

multicastListenerThreads

Sets the number of spawned threads for receiving multicast packets.

multicastPacketSize

Sets the size of the byte array for the receive() method of the multicast listener threads and therefore the maximum size of a packet, maximum is 64k.

3 JGroups Messaging Setup

With JGroups, sending and receiving occurs over a JGroups channel, the payload is a byte array. There are three sending modes: no acknowledgement, async acknowledgement, sync acknowledgement.

The configurable options for JGroups are listed below:

Property

Description

messengerClass

Sets the messenger class to be used (required), the default is com.intershop.beehive.messaging.internal.jgroups.JGroupsMessenger.

jgroupsChannelName

Sets the JGroups channel (required), a message sent to a channel is received by all clients registered to this channel.

jgroupsProtocolStackConfigFile

Optional configuration for the underlying protocol stack used by JGroups.

jgroupsRequestTimeout

Sets the request timeout for message sending. When a message is sent and the client does not respond within the request timeout, the delivery counts as failed. Setting this to 0 means wait indefinitely.

groupsResenderRequestTimeout

Sets the request timeout for the message resender.

jgroupsAcknowledge

Enables message acknowledgements (true|false).

jgroupsSyncAcknowledge

If message acknowledgment is enabled, specifies whether to do it synchronously. If so, the message sender thread waits for all acknowledgments to arrive before continuing. Otherwise the acknowledgment is delegated to a future listener.

jgroupsRunnerThreadSleep

Specifies how long the run() method of the messenger thread will sleep (0 = no sleep).

jgroupsResenderThreadSleep

Specifies how long the message resender threads waits between resend attempts.

4 JMS Messaging Setup

This service must be set up with a JMS server that provides the configured event topics (event channel, tcm channel, etc.). This should be a stand-alone server for optimal performance, though the amount of RAM depends on the number of messages you expect.

The configurable options for JGroups are listed below:

Property

Description

messengerClass

Sets the messenger class to be used (required), the default is com.intershop.beehive.messaging.internal.jms.JmsMessenger.

jmsBackend

Sets the type of the JMS provider backend (hornetq|activemq). This parameter is required.

jmsProviderURL

Needed to lookup the JMS components with JNDI on the JMS server. This parameter is required.

jmsTopicName

Sets the name of the JMS topic the messages are sent to / received from.

jmsReceiveMessagesSync

Sets how the JMS messenger receives messages. Synchronously means the receive() happens in the messenger thread. Asynchronously means a separate listener thread is spawned.

jmsSessionAcknowledgeMode

The mode JMS messages are acknowledged.

jmsPublisherDeliveryMode

The deliveryMode for the topic publisher, sets if the JMS server stores the messages in a database so they could be redelivered after JMS server restart. If this is wanted the JMS server has to be configured accordingly. See javax.jms.MessageProduce.

jmsDisableMessageId

Sets if a message id is added to the JMS message header. Reduces the message size if not set.

jmsDisableMessageTimestamp

Sets if a timestamp ID is added to the JMS message header. Reduces the message size if not set.

jmsRunnerThreadSleep

This sets how long the run() method of the messenger thread will sleep (0 = no sleep). This is the fallback configuration if values are not set in the configuration (defined in the messenger class).

5 AWS Messaging Setup

This messaging configuration can be used within the Amazon AWS environment to support application server configuration.

Note

The implementation of the AWS messaging uses the AWS SNS and SQS services, for which charges apply.

The configurable options for AWS messaging are listed below:

PropertyDescription
messengerClassThe messenger class to use for AWS messaging is com.intershop.beehive.messaging.internal.aws.AwsMessenger.
awsTopicNameThis configures different communication channels within the AWS infrastructure. The name should be used similar to the messaging type, e.g., awsEvent. Ensure that each messaging channel uses a unique name (e.g., by using the default values of the configuration files). The SNS topic is created on the fly, if it does not exist.
awsRegionThe AWS region there the servers are used, e.g., eu-west-1. Find valid region names in the AWS documentation.
awsCredentialsProviderClassName(Optional) The credential provider used to identify the communication channel to the AWS system. It is recommended to use the default provider com.amazonaws.auth.InstanceProfileCredentialsProvider as it gets the credentials from the IAM service. You may consult the AWS SDK configuration for different credential provider implementations but you have to consider the security implications for each.
awsReceiveMessageWaitTimeSecondsThe event polling timeout for new messages (default: 20 seconds). Lower values may speed up the server shutdown delay but may result in more chargeable service calls.
awsSendAsyncEnables the asynchronous sending of events. This is faster but can suppress send errors (default: false).

The user used to run the server needs the following permissions configured:

  • "sns:*" on all resources ("*") or limited to a defined set of resources
  • "sqs:*" on all resources ("*") or limited to a defined set of resources

  • "iam:List*" and "iam:Get*" on all resources ("*") or limited to a defined set of resources

Consult the AWS documentation to create the correct configuration.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets