Configuring the Receiver JMS Adapter

Use

You need to configure the receiver JMS adapter to convert XML messages from the Integration Engine into JMS messages.

To configure the adapter you must specify the following:

The corresponding Java class
General adapter settings
The message type to be received
The transformation class and the bindings implemented in the transformation class
A dispatcher class (optional) with the corresponding settings and the user exits and their settings that are to be called by the dispatcher
How to address the Integration Engine
Settings specific to the respective JMS provider

Prerequisites

You have:

Installed the corresponding adapter.
Selected the adapter on the configuration screen.
Chosen Configure to call the configuration of the adapter module.

Procedure

The configuration of the receiver JMS adapter comprises six functional sub areas:

The version specification for the configuration
version=30

This specification is mandatory. If no specification is entered, the configuration is interpreted as an XI 2.0 adapter configuration. Other values are not permitted and trigger an error.
Java class name for the receiver JMS adapter
Specify the class name as follows:
classname=
```
com.sap.aii.messaging.adapter.ModuleTransport2JMS
```
This specification is mandatory.
General adapter settings
You can set the following general parameters for the receiver JMS adapter:
- JMSSession.sessionTransacted=true or false
  The default value is
```
true
```
  .
  This parameter determines whether a transactional JMS session should be used or not. Following processing of a message, a transactional session ends either with a COMMIT, or in the case of an error, with a ROLLBACK.
- JMS.MessageProducer.DeliveryMode=
```
PERSISTENTNON_PERSISTENT
```
  or
  The default value is
```
PERSISTENT
```
  .
  This parameter controls the delivery mode of the JMS messages to be sent.
- errorDelay
  The default value for this parameter is 0.
  
  This parameter determines how long the system waits before processing further messages if an error occurs. In transactional processing, it can make sense to specify a certain time period, for example, because messages with errors remain in the queue following a ROLLBACK.
- reconnectDelay
  The default value for this parameter is -1.
  
  This parameter controls whether and after what time period an attempt is made to reestablish the connection following a connection error on the JMS side. The time period must be specified in milliseconds. No attempt is made if the value is set to -1.
  
  Note
  Your JMS provider must support the registration of an ExceptionListener for this.
- forceReconnectString =<string>
  This parameter gives you the option of forcing a reconnection if the JMS provider does not call the ExceptionListener registered by the JMS adapter when a connection error occurs in the outbound case.
  
  If a JMSException is thrown when sending a message, the free text contained there (provider-specific) is compared with the specified string. Once the period of time specified in the parameter reconnectDelay has passed, an attempt is made to reestablish the connection.
The message type to be received or sent
On the HTTP side, the JMS adapter knows the following message types:
- TransportMessage
  This is essentially a (single or multipart) MIME message with a connection to the transport protocol (HTTP). It transports an XMBMessage.
- XMBMessage
  This is an SAP-defined SOAP message with attachments that is logically based on a multipart-MIME message.
On the JMS side, the JMS adapter knows the following messages:
- JMSMessage
- JMSTextMessage
- JMSBytesMessage
- JMSObjectMessage
- JMSStreamMessage
- JMSMapMessage
For more information, see the correspondingdocumentation on JMS .

The architecture of the JMS adapter is designed so that every HTTP message can be mapped to a JMS message.

In the configuration, specify which message type is to be received:
- TransportMessage.type=
```
TransportMessageXMBMessage
```
  or
  The default value is
```
XMBMessage.
```
Also specify the JMS message type to be sent:
- JMSMessage.type=
```
TextMessageBytesMessage
```
  or
  The default value is
```
JMSTextMessage.
```
The transformation class in which the bindings for the conversion of different message formats are implemented, and the definition of the particular bindings for the message formats.
In the configuration, specify the transformation class to be used under transformClass. The following classes are supplied:
- com.sap.aii.messaging.adapter.trans.JMSTunneling
- com.sap.aii.messaging.adapter.trans.JMSSinglePayloadBinding
You can define your own binding at any point and apply it to the JMS adapter by implementing a class that enhances the class com.sap.aii.messaging.adapter.trans.Transform and entering this class as the transformation class. Use the classes JMSTunneling or JMSSinglePayloadBinding as templates; their functions are explained briefly below:

In the class com.sap.aii.messaging.adapter.trans.JMSTunneling, a binding is implemented for each of the following cases:
- TransportMessage → JMSTextMessage
- TransportMessage → JMSBytesMessage
- XMBMessage → JMSTextMessage
- XMBMessage → JMSBytesMessage
As you can see from the class name, each binding is a kind of JMS tunneling. This means that the TransportMessage or XMBMessage is transported in the JMS payload.

You do not need to set any further configuration parameters. The message types specified in step 3 control which binding is used at runtime.

In the class com.sap.aii.messaging.adapter.trans.JMSSinglePayloadBinding, a binding is implemented for each of the following cases:
- TransportMessage → JMSTextMessage
  The payload of a TransportMessage is used as the payload of a JMSTextMessage. The value in the HTTP header field is used to determine whether the payload of the TransportMessage is text-based:
  content-Type (=
```
text/...
```
  )
- TransportMessage → JMSBytesMessage
  The payload of a TransportMessage is used as the payload of a JMSBytesMessage. The value in the HTTP header field is used to determine whether the payload of the TransportMessage is not text-based:
  content-Type ( <>
```
text/...
```
  )
- XMBMessage → JMSTextMessage
  The payload of a XMBMessage is used as the payload of a JMSTextMessage. The payload type is used to determine whether the payload of the XMBMessage is text-based: The header data of the XMBMessage is ignored.
- XMBMessage → JMSBytesMessage
  The payload of a XMBMessage is used as the payload of a JMSBytesMessage. The payload type is used to determine whether the payload of the XMBMessage is not text-based: The header data of the XMBMessage is ignored.
While JMS is used by the bindings in the class JMSTunneling as a kind of means of transport, bindings in the class JMSSinglePayloadBinding are much more specific.
The dispatcher class and the user exits to be called by the dispatcher (optional)
The receiver JMS adapter provides you with a dispatcher that you can use to convert messages before they are sent. The settings required for the dispatcher are explained in the example .
Specifications for Integration Engine addressing
- XI.httpPort=
```
<port_no>
```
```
<port_no>
```
  specifies the HTTP server port that receives the messages from the Integration Engine.
- XI.httpService=
```
<service>
```
  <service> describes the service part of the address where the Integration Engine must send its messages.
These specifications are mandatory.
Note
If, for example, you have specified
```
XI.httpPort=1234XI.httpService=/JMS
```
and , the end point address of the JMS adapter in the Integration Engine must be specified as follows:
```
http://<JMSAdapterhost>:1234/JMS
```
Caution
The end point address must be extended as follows for the Integration Engine in Release 1.0:
```
http://<JMSAdapterhost>:1234/JMS?action=execute&pipelineid=Receiver
```
If the Integration Engine message is sent to a non-specified adapter service, the system displays the following error message:

No registered listener for <service> found
The system displays the same message if the adapter is initialized, but has not been started (status
```
STOPPEDINITIALIZED
```
or ).
Provider-specific settings
For more information about provider-specific settings, see Settings for the JMS Provider .
The adapter can send back a synchronous system acknowledgement if the sender requests it. The acknowledgment confirms that the message was delivered to the receiver.
- If you want to send back a synchronous system acknowledgment, set XI.AckFinal=true. This is the default.
- If you want to prevent a synchronous system acknowledgement from being sent back, even if the sender requests it, set XI.AckFinal=false.

Example

Below is an example configuration for the receiver JMS adapter:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

# JMS Adapter Configuration

# This configuration can be used as a template to configure the

# JMS receiver adapter

#**************************************************************************

# Set XI message protocol version.This example is designed for XI 3.0

version=30

#**************************************************************************

# JMS message sender class Uncomment for sending JMS messages

classname=com.sap.aii.messaging.adapter.ModuleTransport2JMS

#**************************************************************************

# set if a transacted JMS Session should be used (default:true)

#JMSSession.sessionTransacted=false

# set the delivery mode of the JMS MessageProducer (QueueSender, default:PERSISTENT)

#JMS.MessageProducer.DeliveryMode=NON_PERSISTENT

# set delay in milliseconds before processing next message after an error

# (default:0)

#errorDelay=10000

# set delay in milliseconds before trying to reestablish the JMS connection

# after a connection error (default:-1 (do not try to reconnect))

#reconnectDelay=10000

# force reconnect (only to be used if the JMS Provider does not support the

# JMSExceptionListener functionality) the reconnect is only attempted if

# the JMSException message contains the forceReconnectString or if the

# forceReconnectString is set to * (default:forceReconnectString is not

# set -> no reconnect is attempted

#forceReconnectString=MQJMS2007

#**************************************************************************

# set the message formats you want to process

# formats are only needed if they cannot be evaluated at runtime

# JMSMessage Type can be set to TextMessage or BytesMessage

# it is only used for sending JMS messages

#JMSMessage.type=BytesMessage

JMSMessage.type=TextMessage

# TransportMessage Type can be set to TransportMessage or XMBMessage

# it is used for sending and receiving TransportMessages and XMBMessages

#TransportMessage.type=TransportMessage

TransportMessage.type=XMBMessage

#**************************************************************************

# uncomment and adjust parameters for Transformation Type

# (binding of JMS TransportMessage); insert your class here for an

# individual binding between JMS and TransportMessage

# uncomment the following line for using bindings that belong to Tunneling

#transformClass=com.sap.aii.messaging.adapter.trans.JMSTunneling

# uncomment the following line for using bindings that belong to

# SinglePayloadBinding

transformClass=com.sap.aii.messaging.adapter.trans.JMSSinglePayloadBinding

#**************************************************************************

# uncomment and adjust parameters for the HTTP listener ports to wait for

# XI messages

XI.httpPort=3333

XI.httpService=/JMS

#**************************************************************************

# uncomment and adjust parameters for loading JMS administrated objects via

# JNDI

# uncomment and adjust parameters if not the default context should be used

#JNDI.InitialContext.property.1=java.lang.String

#{javax.naming.Context.INITIAL_CONTEXT_FACTORY}, java.lang.String

#com.sap.engine.services.jndi.InitialContextFactoryImpl

#JNDI.InitialContext.property.2=java.lang.String

#{javax.naming.Context.PROVIDER_URL}, java.lang.String localhost:50004

#JNDI.InitialContext.property.3=java.lang.String

#{javax.naming.Context.SECURITY_PRINCIPAL}, java.lang.String Administrator

#JNDI.InitialContext.property.4=java.lang.String

#{javax.naming.Context.SECURITY_CREDENTIALS}, java.lang.String sap

# set the Lookup Names

#JMS.JNDILookupNameQueueConnectionFactory=jmsfactory/default/joetest

#JMS.JNDILookupNameQueue=jmsQueues/default/sapDemoQueue

#**************************************************************************

# uncomment and adjust parameters for loading JMS administrated objects

# from the file system

#JMS.FileNameQueueConnectionFactory=SAPQueueConnectionFactory.ser

#JMS.FileNameQueue=SAPQueue.ser

#**************************************************************************

# uncomment and adjust parameters for creating SonicMQ

# JMS administrated objects

JMS.QueueConnectionFactoryImpl.classname=progress.message.jclient.QueueConnectionFactory

JMS.QueueConnectionFactoryImpl.constructor=java.lang.String p49512:2506

JMS.QueueImpl.classname= progress.message.jclient.Queue

JMS.QueueImpl.constructor=java.lang.String SampleQ1

#**************************************************************************

# uncomment and adjust parameters for creating WebSphereMQ

# JMS administrated objects

#JMS.QueueConnectionFactoryImpl.classname=com.ibm.mq.jms.MQQueueConnectionFactory

#JMS.QueueConnectionFactoryImpl.method.setHostName=java.lang.String p24537

#JMS.QueueConnectionFactoryImpl.method.setChannel=java.lang.String JAVA.CHANNEL

#JMS.QueueConnectionFactoryImpl.method.setTransportType=java.lang.Integer {com.ibm.mq.jms.JMSC.MQJMS_TP_CLIENT_MQ_TCPIP}

#JMS.QueueConnectionFactoryImpl.method.setQueueManager=java.lang.String QM_p24537

#JMS.QueueImpl.classname= com.ibm.mq.jms.MQQueue

#JMS.QueueImpl.constructor=java.lang.String postcard

#JMS.QueueImpl.method.setTargetClient=java.lang.Integer {com.ibm.mq.jms.JMSC.MQJMS_CLIENT_NONJMS_MQ}

#**************************************************************************

# uncomment and adjust parameters for using a dispatcher ***

#Dispatcher.class=com.sap.aii.messaging.adapter.ConversionDispatcher

#Dispatcher.namespace=namespace1

#namespace1.ConversionDispatcher.logPayload=true

#namespace1.Service.1=Plain2XMLService

#namespace1.Plain2XMLService.class=com.sap.aii.af.sdk.xi.adapter.Conversion

#namespace1.Plain2XMLService.xml.conversionType=SimplePlain2XML

#namespace1.Plain2XMLService.xml.processFieldNames=fromConfiguration

#namespace1.Plain2XMLService.xml.fieldNames=a,b,c

#namespace1.Plain2XMLService.xml.fieldSeparator=;

#namespace1.Service.2=XSLTService

#namespace1.XSLTService.class=com.sap.aii.af.sdk.xi.adapter.XSLTConversion

#namespace1.XSLTService.XSLTConversion.XSLTFileName=Data/DemoConversion.xsl

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++