Use WebSphere MQ (manufactured by IBM) as JMS provider in Message Queue reception. WebSphere MQ is asynchronous communication infrastructure of message queueing type for data communication between system programs of different models.

Message Queue reception is supported in WebSphere MQ version 7.5.

The following figure shows WebSphere MQ configuration:

Figure 2-57 WebSphere MQ configuration

Legend:

Queue manager: Management program organizing queues and listeners

Queue: Queue object organizing JMS objects

Listener: Listener to receive or send messages by queue manager

Note

Queue manager of WebSphere MQ cannot access the server by channel authentication in initial status. For this, it is necessary to change the setting so that channel authentication is not used or to change the channel authentication rules set by default. For WebSphere MQ setting methods, see IBM manual.

You can specify the send option (JMS header and properties) to send messages. The following shows details of send options of Message Queue reception:

(a) Details of JMS header

All setting values of the send option (JMS header) are transformed to String type and are set in the header message. At this stage, if value is null or blank, the tag is blank.

The following table describes the details of JMS header:

Table 2-8 Details of JMS header

Header name	Setting contents	Setting time	Possibility of setting in client
JMSDestination	Queue name in which message is registered	Set when QueueSession.createSender(Queue queue) method is issued.	N
JMSDeliveryMode	Value showing message persistence	Set when the message is sent.	N
JMSMessageID	Message identifier to uniquely identify each message sent by the provider	Set when the message is sent.	N
JMSTimestamp	Value showing message sending time (unit: milliseconds)	Set when the message is sent.	N
JMSExpiration	Value showing time for which message is valid (unit: milliseconds)	Set when the message is sent.	N
JMSRedelivered	Value showing whether the message is being redelivered	Set when a message delivered to the application needs to be redelivered by recovery.	N
JMSPriority	Message priority	You can specify by QueueSender.setPriority() method, or QueueSender.send() method.	Y
JMSReplyTo	Response destination address	Set when Message.setJMSReplyTo() method is issued.	Y
JMSCorrelationID	Correlation identifier to correlate a message to another message	Set when Message.setJMSCorrelationID() method is issued.	Y
JMSType	Message type provided by the application when a message is sent	Set when Message.setJMSType() method is issued.	Y

Legend:

Y: Can be specified.

N: Cannot be specified.

(b) Details of properties

Message properties are configured from the properties set by JMS provider and properties that the user can set in the client.

Properties set by JMS provider

Properties set by JMS provider contain JMS standard properties and properties set by WebSphere MQ. All items in which either property is set are set in the header message.

• JMS standard properties
  JMS standard properties are prefixed with the item name "JMSX".
  The following table lists and describes JMS standard properties:
  

  Table 2-9 List of JMS standard properties

  Item name	Description
  JMSXUserID	User ID of message sender
  JMSXAppID	ID of message sending application
  JMSXDeliveryCount	Number of times a message is re-received
  JMSXGroupID	ID of group to which the message belongs
  JMSXGroupSeq	Message order number in the group
  JMSXProducerTXID	Transaction identifier
  JMSXConsumerTXID	Transaction identifier
  JMSXRcvTimestamp	Message reception time
  JMSXState	Item used in the provider

• Properties set by WebSphere MQ
  Properties set by WebSphere MQ are included in the properties for provider. Properties for provider are prefixed with the item name "JMS_". Among these properties, properties prefixed with the item name "JMS_IBM_" are WebSphere MQ properties.
  

Properties set by user

Properties that are optional to the user are set by using "set<Type name>Property(String name,<Type name> value)" method.

All values set in a property are transformed to String type and set in the header message.

The following table lists the data types that you can set in a property:

Table 2-10 List of data types you can set in a property

Data type	Setting method
Boolean	setBooleanProperty(String name, boolean value)
Byte#1	setByteProperty(String name, byte value)
Short	setShortProperty(String name, short value)
Integer	setIntProperty(String name, int value)
Long	setLongProperty(String name, long value)
Float	setFloatProperty(String name, float value)
Double	setDoubleProperty(String name, double value)
String	setStringProperty(String name, String value)
Object#2	setObjectProperty(String name, Object value)

Note#1

If you set Byte type value, the item transformed to Integer type numeric value is set in the header message as a character string. The range of numeric values set is -127-127.

Note#2

If Object is set in data type, you can use all data types (Boolean, Byte, Short, Integer, Long, Float, Double and String).

MQ resource adapter is used for passing messages from JMS provider (IBM WebSphere MQ system) to Message Queue reception.

The connection relation between MQ resource adapter and Message Queue reception is that you can correlate multiple receptions for 1 resource adapter but you cannot correlate multiple resource adapters for 1 reception.

Specify the correlation of MQ resource adapter and Message Queue reception in Message Queue reception definition file. The specified contents are enabled when Message Queue reception starts. At this stage, you must start MQ resource adapter in advance, which is correlated with Message Queue reception. Setting contents of Message Queue reception are not enabled, since Message Queue reception cannot start if the correlated MQ resource adapter is not started.

The connection relation between Message Queue reception and MQ resource adapter is described here.

(a) Connection relations that can be set up (in MQ resource adapter)

You can set up one of the following connection relations:

• If connection relation between resource adapter and reception is 1:1
• If connection relation between resource adapter and reception is 1:n

The following figures show the examples:

(Example 1) If connection relation between resource adapter and reception is 1:1

Description

• 1 Message Queue reception correlates to 1 MQ resource adapter
• 1 MQ resource adapter correlates to 1 Message Queue reception

(Example 2) If connection relation between resource adapter and reception is 1:n

Description

• Multiple Message Queue receptions correlate to 1 MQ resource adapter
• 1 MQ resource adapter correlates to 1 Message Queue reception

(b) Connection relations that cannot be set up (in MQ resource adapter)

You cannot set n:1 configuration for connection relation between the resource adapter and reception, since you cannot specify multiple resource adapters for 1 reception.

The following figure shows an example:

(Example)

Description

• 1 Message Queue reception correlates to 1 MQ resource adapter
• Multiple MQ resource adapters correlate to 1 Message Queue reception

Queue is a queue object compiling JMS objects and is managed by the queue manager.

The connection relation between a queue and Message Queue reception is that multiple receptions can correlate to 1 queue but multiple queues cannot correlate to 1 reception.

The connection relation between Message Queue reception and queue is described here.

(a) Connection relations that can be set up (in queues)

You can set up one of the following connection relation:

• If the connection relation between a queue and reception is 1:1
• If the connection relation between a queue and reception is 1:n

The following figures show the examples:

(Example 1)If connection relation between a queue and reception is 1:1

Description

• 1 queue exists in 1 queue manager
• 1 Message Queue reception correlates to 1 queue

(Example 2)If connection relation between a queue and reception is 1:n

Description

• 1 queue exists in 1 queue manager
• 2 Message Queue receptions correlate to 1 queue

(b) Connection relations that cannot be set up (in queues)

You cannot set up n:1 configuration for connection relation between a queue and reception, since you cannot specify multiple queues for 1 reception.

(Example 1)If there is 1 queue manager

Description

• 2 queues exist in 1 queue manager
• 1 Message Queue reception correlates to queue 1 and queue 2

(Example 2)If there are multiple queue managers

Description

• 2 queue managers exist
• 1 queue exists in each queue manager
• 1 Message Queue reception correlates to queue 1 and queue 2

While creating a business process, you must match the receive activity communication model with the communication model of Message Queue reception.

You can set business process persistence as persistent or non-persistent.

However, please note that if you set non-persistent, there may be duplicate message delivery when a fault occurs.

The connection relation between a business process and Message Queue reception is that multiple receptions can correlate to 1 business process but multiple business processes cannot correlate to 1 reception.

The connection relation between Message Queue reception and business processes is described here.

(a) Connection relations that can be set up (in business processes)

You can set up one of the following connection relations:

• If connection relation between a business process and reception is 1:1
• If connection relation between a business process and reception is 1:n

The following figures show the examples:

(Example 1)If connection relation between a business process and reception is 1:1

Description

• 1 business process correlates to 1 Message Queue reception
• 1 Message Queue reception correlates to 1 business process

(Example 2)If connection relation between a business process and reception is 1:n

Description

• 1 business process correlates to 1 Message Queue reception
• Multiple Message Queue receptions correlate to 1 business process

(b) Connection relations that cannot be set up (in business processes)

You cannot set up n:1 configuration for connection relation between a business process and reception, since you cannot define multiple business processes for 1 reception.

The following figure shows an example:

(Example)

Description

• Multiple business processes correlate to 1 Message Queue reception
• 1 Message Queue reception correlates to 1 business process

You can configure various systems according to the communication model used in Message Queue reception.

Configuration examples in the following cases are explained here.

• If Message Queue reception is used in an asynchronous communication model
• If Message Queue reception is used in a synchronous communication model

(a) If Message Queue reception is used in asynchronous communication model

Preconditions

1. A business process that defines Message Queue reception is created.
2. Communication model of Message Queue reception is defined as "Asynchronous".

Example of configuration

The following figure shows an example of configuration of Message Queue reception and business process:

Description

1. Register the message in WebSphere MQ server queue from MQ client program.
2. Message is sent from WebSphere MQ server to Message Queue reception (HCSC server).
3. Message Queue reception invokes the business process.
4. After all activity processes end, Message Queue reception process also ends.
5. WebSphere MQ server commits the transaction and deletes the message from the queue.
   

   Reference note

   In this configuration example, the message is maintained till the request process is finished. Due to this, the message is not deleted from the queue while the business process is being processed. However, if the duplicate delivery prevention process is executed or if the message is moved by rollback restrictions, the message is not deleted from the queue. To prevent duplicate delivery of messages, see "(8) Preventing duplicate message delivery while using Message Queue reception".

(b) Using Message Queue reception in synchronous communication model

Preconditions

1. A business process that defines Message Queue reception is created.
2. Communication model of Message Queue reception is defined as "Synchronous".

Example of configuration

The following figure shows an example of configuration of Message Queue reception and business process:

Description

1. Register the message in WebSphere MQ server queue from MQ client program.
2. Message is sent from WebSphere MQ server to Message Queue reception (HCSC server).
3. Message Queue reception invokes the business process.
4. After the reply activity process ends, the information required for execution after reply activity is stored in Reliable Messaging or asynchronous EJB and Message Queue reception process also ends.
5. WebSphere MQ server commits the transaction and deletes the message from the queue.
6. The activity set after reply activity is executed according to the information stored in Reliable Messaging or asynchronous EJB.
   

   Reference note

   In this configuration example, you can delete the message from the queue before processing of the business process ends. However, if an exception occurs in the processing of the business process after the reply activity, it is necessary to resend the request because the message is deleted from the queue.

You must use transactions same as those of WebSphere MQ queue manager, since the queue rolls back when an exception occurs in Message Queue reception. For this, use a container management transaction for Message Queue reception transaction. By this, the transaction is committed at the same time as when WebSphere MQ queue is committed.

The following figure shows the range of transactions performed when Message Queue reception is used:

Figure 2-58 Range of transactions performed when Message Queue reception is used

Message Queue reception is processed by using transactions same as those of WebSphere MQ queue manager. However, the business process is processed by transactions different from WebSphere MQ queue manager. Due to this, the process terminates abnormally in Message Queue reception and even when the message returns to the beginning of the queue to execute rollback, the business process transaction might end normally. In this status, if the message is resent by rollback, the same process is re-executed in the business process in which the process was executed once. To prevent such processes, perform a process to prevent duplicate delivery of messages. To prevent duplicate delivery of messages, see "(8) Preventing duplicate message delivery while using Message Queue reception".

If the request process ends abnormally, the business process for which the process is executed once is reprocessed when the message to execute rollback returns to the beginning of the queue and the message is resent.

Perform settings for preventing duplicate message delivery in Message Queue reception. With these settings, you can prevent re-execution of a business process that is already executed due to resending of a message.

(a) Preconditions to prevent duplicate delivery

If all the following conditions are met, check prevention duplicate delivery:

• Database is used.
• Execution history is valid (status persistence in business process properties is "yes").

(b) Points to be considered when using prevention of duplicate delivery

The points to be considered when prevention of duplicate delivery is set are as follows:

• You must estimate the database capacity, since execution history is too managed.
• A business process in which system exception has occurred must be re-executed.

(c) Measures to be taken when a fault occurs in a business process

Examples of the main faults occurring in business processes and the operations and actions to be performed when prevention of duplicate delivery is set are described here.

(Example 1)If a fault occurs before registering to the message correlation information table

Details on the display of execution history, request message status and actions to be taken in this case are as follows:

• Display of execution history
  Not executed
  
• Request message status
  Rolled back and request message is resent.
  If the cause is an invalid message (such as null), continue the rollback only for the number of executions of the specified rollback.
  
• Action
  Set the number of rollback restrictions.
  Remove the message in which the fault occurred.
  

(Example 2)If a fault occurs during process execution of a business process

Details on the display of execution history, request message status and actions to be taken in this case are as follows:

• Display of execution history
  Executing or error
  
• Request message status
  Rolled back when fault occurred and committed as normal termination by duplicate delivery prevention check when the 2nd request message is sent.
  
• Action
  Use the re-execution command or operating environment screen and re-execute the business process.
  

(Example 3)If a fault occurs after processing of a business process ends

The following shows execution history display, request message status and action in this case:

• Execution history display
  Normal termination
  
• Request message status
  Rolled back when fault occurred and committed as normal termination by duplicate delivery prevention check when the 2nd request message is sent.
  
• Action
  Not required.
  

(Example 4)If a fault occurs after reply activity process of a business process ends

Details on the display of execution history, request message status and actions to be taken in this case are as follows:

• Display of execution history
  Executing
  
• Request message status
  Request message is not sent because the queue is committed after the reply activity process ends.
  
• Action
  Use the re-execution command or operating environment screen and re-execute the activity after the reply activity.
  

Always roll back if a fault occurs during the request process in Message Queue reception. This is to prevent unlimited loops by moving messages to the queue specified in the dead letter queue of the queue manager or the back out re-queue of the queue.

Set the number of rollbacks in WebSphere MQ queue manager and the queue.

For details on the setting methods, see WebSphere MQ manual.

Items set in queue manager

The following table describes the setting item correlated to rollback set in the queue manager:

Table 2-11 Setting item correlated to rollback set in the queue manager

Setting item	Setting contents	Value that can be set	Default value
DEADQ	Dead letter queue name	Queue name	SYSTEM.DEAD.LETTER.QUEUE

Items set in queue

The following table describes the setting items correlated to rollback set in queue:

Table 2-12 Setting items correlated to rollback set in queue

Setting item	Setting contents	Value that can be set	Default value
BOTHRESH	Backout threshold value	0-999999999	0
BOQNAME	Backout re-queue name	Queue name	None

Note

You must take care while specifying a value (time for which message is maintained) in QueueSender#send parameter set in the client. Even if the message is moved to the dead letter queue, it is deleted, if the time specified is exceeded.