Introduction
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
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.
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 |
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 |
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. |
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 |
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. |
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 |
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 |
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). |
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:
| Property | Description |
|---|---|
| messengerClass | The messenger class to use for AWS messaging is com.intershop.beehive.messaging.internal.aws.AwsMessenger. |
| awsTopicName | This 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. |
| awsRegion | The 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. |
| awsReceiveMessageWaitTimeSeconds | The 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. |
| awsSendAsync | Enables 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.