Configuring the Receiver JMS Adapter 

Use

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

Procedure

...

       1.      Under Transport Protocol, select the JMS provider:

○       SonicMQ JMS Provider

○       WebSphereMQ (MQ Series) JMS Provider

○       Access JMS Provider with JNDI

○       (Read) JMS Provider Administered Objects from File

○       Access JMS Provider Generically

       2.      The Message Protocol is JMS 1.x.

       3.      Select the Adapter Engine on the Integration Server, or select a non centrally installed Adapter Engine.

This selection is not available in the PCK.

Defining Connection Parameters

       4.      Select the Target tab page.

       5.      Depending on the transport protocol you have selected, make specifications for the respective JMS provider.

Defining SonicMQ JMS Provider Settings

Defining WebSphereMQ (MQ Series) JMS Provider Settings

Defining JMS Provider Settings for JNDI Access

Specifying Files for Administrable Objects of the JMS Provider

Defining Generic Access to the JMS Provider

       6.      To make additional settings or replace the default settings, select Set Additional JMS Parameters or Replace Default Settings and enter the parameters and values in the table.

For example, you can set the following parameters and values:

JMSMessageClass with value com.ibm.jms.JMSMessage

JMS.Message.method.setStringProperty with value java.lang.String XAppId, java.lang.String myapp

Defining JMS Settings

       7.      Select the Processing tab page.

       8.      If you want to use a transactional JMS session, select Transactional JMS Session.

Following processing of a message, a transactional session ends either with a COMMIT, or in the case of an error, with a ROLLBACK.

       9.      Select the Delivery Mode of Message Producer:

○       Persist JMS Messages in the JMS Provider

○       Do Not Persist JMS Messages in the JMS Provider

   10.      Under JMS ReplyTo Queue Name, specify the name of the queue to which the responses are to be sent.

   11.      Under JMS Message Expiry Period (msecs), specify the expiry period of the JMS message in milliseconds.

   12.      Specify the JMS Message Priority.

   13.      Enter theUser and the Password with confirmation for accessing the JMS Queue.

Defining Correlation Settings

   14.      Set the JMS Correlation ID to:

○       PI Message ID (MessageID) (default value)

○       PI Reference ID (RefToMessageID)

○       PI Conversation ID (ConversationID)

○       No value

   15.      If you want to save the JMS correlation ID of the request, select Store JMSCorrelationID of Request.

   16.      Specify what the JMS Property is to be set to.

   17.      Select the Value of the JMS Property:

○       PI Message ID (MessageID) (default value)

○       PI Reference ID (RefToMessageID)

○       PI Conversation ID (ConversationID)

○       No value

Defining PI Settings

   18.      Select the 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.

   19.      The adapter can 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.

Select Handling of Pending PI Messages:

○       Throw Exception (Message Retry Possible Later)

○       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 is not yet 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.

   20.      Under Time Period for Duplicate Check for EO(IO) (secs), specify when the IDs are to be deleted.

To check for duplicate messages, IDs must be saved in the database. To prevent the database from getting unnecessarily large, these IDs are deleted after a certain amount of time.

For example, if you check message monitoring daily, deletion can take place after one day.

   21.      If the JMS receiver is an application, the JMS adapter should return a delivery acknowledgment. Select Send PI Delivery Acknowledgment (Adapter Is Endpoint).

Defining Error Handling Settings

   22.      Under Wait 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, for example, it can make sense to specify a certain time period, because messages with errors remain in the queue following a ROLLBACK.

   23.      Under Wait Before Reconnect (msecs), specify a period of time after which an attempt is made to reestablish a connection following a connection error on the JMS side.

If you enter -1, no attempt is made to reestablish the connection.

Your JMS provider must support the registration of an ExceptionListener for this.

   24.      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 the parameter Reconnect if Exception Text Starts With.

If a JMS exception is thrown when sending a message, the free text specified here is compared with the specified string. Once the period of time specified in Wait Before Reconnect (msecs) 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.

Defining Adapter-Specific Message Attributes

   25.      Select the Advanced tab page.

   26.      To evaluate adapter-specific attributes in the message header of the PI message, select Use Adapter-Specific Message Attributes.

   27.      If you want missing message attributes to trigger an error message, select Fail If Adapter-Specific Message Attributes Missing.

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.

   28.      To evaluate the following attributes in PI message headers, set the corresponding indicators:

○       JMS Message Correlation ID: (technical name: DCJMSCorrelationID)

○       JMS Message Expiration: (technical name: DCJMSExpiration)

○       JMS Message Priority: (technical name: DCJMSPriority)

○       JMS Message ReplyTo Destination: (technical name: DCJMSReplyTo)

○       JMS Message Time Stamp: (technical name: DCJMSTimestamp)

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

○       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 PI message.

Under Java Type, you define the JMS Java message type for the attribute in the created JMS message. You can enter the following:

■       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.

Defining the Adapter Status

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

Defining Additional Parameters

   31.      Specify the additional parameter Names and Values in the table.

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.