Configuring the Receiver JMS Adapter

 Configuring the Receiver JMS Adapter 

Use

You need to configure the receiver JMS adapter to be able to convert XI messages from the Integration Server or the PCK into JMS messages.

Integration

You configure the adapter on the Parameters tab page during the definition of a communication channel in the Integration Server or in the PCK. In addition to the adapter configuration, you can use the Module tab page to specify generic modules in the module processor, which give the adapter additional functions.

Prerequisites

       1.      You have created a new communication channel or have opened an existing one.

       2.      On the Parameters tab page you have selected the adapter type JMS.

       3.      You have selected the Receiver radio button to define the adapter as a receiver adapter.

Activities

To configure the adapter, specify the following:

Transport Protocol

SonicMQ JMS Provider

WebSphereMQ (MQ Series) JMS Provider

Access JMS Provider with JNDI

(Read) JMS Provider Administered Objects from File

Access JMS Provider Generically

Message Protocol

JMS 1.x

Adapter Engine

Select the Adapter Engine on the Integration Server, or select a non-centrally installed Adapter Engine. This selection is not available in the PCK.

Target Tab Page

Depending on the transport protocol you have selected, make specifications for the respective JMS provider. See the relevant JMS-provider documentation for details about the individual parameters. See also: JMS-Provider-Specific Settings

Processing Tab Page

JMS Settings

Parameter	Entry
Transactional JMS Session	If you want to use a transactional JMS session, set the indicator. Following processing of a message, a transactional session ends either with a COMMIT, or in the case of an error, with a ROLLBACK.
Delivery Mode of Message Producer	Specify the quality of service of the message producer. You have the following options: ·        Persist JMS Messages in the JMS Provider ·        Do Not Persist JMS Messages in the JMS Provider
JMS ReplyTo Queue Name	Specify the name of the queue to which the responses are to be sent.
JMS Message Expiration Period (msecs)	Specify the expiry period of the JMS message as a JMS parameter in milliseconds.
JMS Message Priority	Specify the priority of the JMS message.
JMS Queue User	User for accessing the JMS queue
JMS Queue Password	Password (with confirmation) for accessing the JMS queue

Correlation Settings

Define the correlation settings.

·        Set JMSCorrelationID To:

¡        XI Message ID (MessageID) (default value)

¡        XI Reference ID (RefToMessageID)

¡        XI Conversation ID (ConversationID)

¡        No Value

·        Store JMSCorrelationID of Request

Set the indicator if you want to save the JMS correlation ID of the request.

·        Set this JMSProperty

Enter the JMS Property Name.

·        Specify which value the JMS property is to have:

¡        XI Message ID (MessageID) (default value)

¡        XI Reference ID (RefToMessageID)

¡        XI Conversation ID (ConversationID)

¡        No Value

XI Settings

Parameter	Entry
Mapping of Message	·        If you want the JMS payload to contain the entire message, choose Entire Message = JMS Payload. ·        If you only want the JMS payload to contain the payload of the message, choose Message Payload = JMS Payload.
Handling of Pending XI Messages	The adapter is able to identify whether the connection has been terminated between the JMS commit and the commit in the database of the Adapter Framework. The adapter identifies the resulting duplicate data record. You can choose from the following settings: ·        Throw Exception (Message Retry Possible Later) (Default) ·        Bypass Pending Warning and Send Message to JMS (Duplicates Possible) A duplicate data record is created if the JMS commit is executed, but not the commit in the database of the Adapter Framework. If you select this option, you must make sure that this message has not yet been received in the JMS environment. ·        Mark Message as Delivered (Message Loss Possible) The message is lost if the JMS commit has not yet been executed. If you select this option, you must make sure that this message has already been received in the JMS environment. For an example of how this parameter is used, see below under Example.
Time Period for Duplicate Check for EO(IO) (secs)	To check for duplicate messages, IDs must be saved in the database. To prevent the database from getting unnecessarily large, these IDs must be deleted after a certain amount of time. Specify in seconds the time period after which you want IDs to be deleted (after one day, for example, if you check message monitoring daily).
Send XI Delivery Acknowledgment Back (Adapter Is Endpoint)	If the JMS receiver is an application, the JMS adapter should send a delivery acknowledgment. Set the indicator.

Error Handling Settings

Parameter	Entry
Wait Time After Message Error (msecs)	Enter the number of milliseconds that the adapter must wait when a processing error occurs before further messages are processed. 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.
Wait Before Reconnect (msecs)	Specify a period of time after which an attempt will be made to reestablish a 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. Your JMS provider must support the registration of an ExceptionListener for this.
Reconnection if Exception Text Starts with	If the JMS provider does not call the ExceptionListener registered by the JMS adapter when a connection error occurs, you can force the connection to be reestablished by setting this parameter. If a JMS exception is thrown when sending a message, the free text contained here is compared with the specified string and once the period of time specified in Wait Before Reconnect (ms) has passed, an attempt is made to reestablish the connection. Only set this parameter if your JMS provider does not support the registration of an ExceptionListener.

Advanced Tab Page

Adapter-Specific Message Properties

To evaluate adapter attributes in the message header of the XI message, choose Use Adapter-Specific Message Attributes.

To evaluate the following attributes in XI message headers, set the corresponding indicators:

·        If you want missing message attributes to trigger error messages, choose Fail on Missing Adapter Message Properties. If the indicator is set and the header for adapter-specific message attributes or one of the set attributes is missing from the message, this leads to a delivery exception in the audit log of the message.

If you do not set the indicator, and message attributes are missing, the adapter accesses information from the adapter configuration.

Name	Technical Name
JMS Message Correlation ID	DCJMSCorreleationID
JMS Message Expiration	DCJMSExpiration
JMS Message Priority	DCJMSPriority
JMS Message ReplyTo Destination	DCJMSReplyTo
JMS Message Timestamp	DCJMSTimestamp

If you want to set additional JMS message attributes, select Specify Additional JMS Message Properties (10 Maximum).

·        In the table, enter the Name and Java Type of the JMS message properties whose values are to be included in the message header of the XI message.

Under Java Type, you define the JMS Java message type for the attribute in the created JMS message. The following are possible entries:

¡        boolean

¡        byte

¡        short

¡        int

¡        long

¡        float

¡        double

¡        String

The technical names of the additional attributes are DCJMSMessageProperty0, DCJMSMessageProperty1, ..., DCJMSMessageProperty9.

You can enter more than ten properties in the table, however, only the first ten are taken into account.

The attribute namespace for the adapter is http://sap.com/xi/XI/System/JMS.

Adapter Status

Set the adapter to Active to enable messages to be exchanged.

Additional Parameters

To make additional settings or replace the default settings, enter the parameters and values in the table.

You can set the following parameters, for example:

Name	Value
JMSMessageClass	com.ibm.jms.JMSMessage
JMS.Message.method.setStringProperty	java.lang.String XAppId, java.lang.String myapp

You can set additional JMS parameters for all JMS providers.

Example

Below is a typical procedure for handling pending messages:

...

       1.      The default setting for the parameter of the receiver JMS adapter is Throw Exception.

       2.      You see the following exception in the message or adapter monitor:

The channel is configured to throw a recoverable, temporary error for this warning (default). Decide whether you want to bypass this message. If so, set the Pending Handling channel parameter to 'Bypass' and restart the message afterwards.

       3.      Make sure that no further messages are sent through this communication channel by deactivating the corresponding sender channel.

       4.      Check whether the message or messages have arrived in the JMS environment.

                            a.      If the message has arrived in the JMS environment, select Mark Message as Delivered (Message Loss Possible).

                            b.      If the message has not arrived in the JMS environment, select Bypass Pending Warning and Send Message to JMS (Duplicates Possible).

                            c.      Choose Repeat in message monitoring.

If some messages have arrived in the JMS environment and some have not, you must perform the procedure twice and resend the respective messages in each case.

       5.      Reset the parameter in the communication channel to Throw Exception.

       6.      Activate the corresponding sender communication channel.