Accessing MQ Provider through EGL Java Application

Content

Introduction

Applications can send messages to each other using a message queue or topic managed by a message broker (an MQ provider). 

• An application can write a message to a queue. 

       When another application consumes the message, then the message takes off the queue.

• An application can publish a message to a topic and One or more applications can receive the messages by subscribing to that topic.

EGL supports the following MQ providers:

• IBM® MQ (formerly WebSphere® MQ or MQSeries®)
• RabbitMQ 
• Apache ActiveMQ ®

 The EGL runtime handles the underlying communication with the MQ provider. This action allows EGL applications to communicate with EGL and non-EGL applications without knowledge of the communication network's lower levels and the other applications' location.

Prerequisites 

• IBM Rational Business Developer 9.7 (RBD).
• IBM MQ, RabbitMQ, or Apache ActiveMQ 
• Knowledge of developing applications or web services using EGL and RBD.

• EGL is compatible with version 0.58 of the client, available here: Qpid JMS 0.58.0 - Apache Qpid™

1. An EGL Record type- represents the structure of the data being read/written. 
2. An EGL logic part (Program/Library/Service)- issues EGL I/O statements against a record variable.
3. An EGL Resource Association- links the EGL Record to a physical file or system. This resource association is a component of the EGL project’s Build Descriptor.

EGL provides a built-in Record type called MQRecord, which contains additional properties related to MQ 

queueName / topicName
The name of the resource association element that is to be linked to MQRecord. If the property isTopicRecord value is no (the default), then queueName is used. Otherwise, topicName is used.

isTopicRecord
Specifies whether this MQRecord is for a message queue or topic. The default value of this property is no.

topicString
Identifies the topic that the EGL application will publish/subscribe to. Here, Wildcards and separators can be used.

includeMsgInTransaction
Specifies whether MQ operation is to be transacted. If the value is yes (the default), then MQ operations can be committed or rolled back by the user.
When you combine messages in a transaction that defines a unit of work, the messages can be committed or rolled back as a group. When a unit of work is committed, everything included in the transaction is finalized. When a unit of work is rolled back, everything included in the transaction will be removed.
In other environments, the resources for different managers are committed independently from one another. When user use sysLib.commit() and sysLib.rollback(), EGL automatically issues the appropriate MQ calls for commits and rollbacks.

messageFormat
The format of the message sent and received. The supported formats are mentioned below.

• BINARY – the MQ record is serialized/deserialized as an unformatted message. This is the default format, and is compatible with EGL applications written prior to RBD 9.7. The sender and receiver application needs to know the structure of the EGL MQ record.
• TEXT – the MQ record is converted to and from an unformatted string. It has the same effect as BINARY.
• JSON – the MQ record is converted to and from a JSON-formatted string

subscriptionName
The name of the topic subscription that EGL clients use to listen for topic messages. This name has the following format:

              [ClientID]:subscriptionName

ClientID indicates that this subscription is unique to the EGL client (i.e. non-shared subscription). If this option is omitted, a shared subscription is used.

• For IBM MQ via JMS, a subscription with the provided name will be created and managed by IBM MQ. Here, predefined subscriptions cannot be used.
• For RabbitMQ, this option has no effect. Instead, topic exchanges are used, defined in the resource association.
• For Apache ActiveMQ, the ClientID is mandatory. Shared subscriptions cannot be used.

Figure 1 Record definitions for EGL MQ access

• Add 
  Writes a message to a message queue or publishes the message to a topic.
• getNext
  Reads the next message from the message queue or subscribes to a topic.

• Commit
  • If the user invokes sysLib.commit(), it issues a close command, or the EGL application/service invocation completes successfully, then the EGL runtime performs a commit.
  • Messages added to the queue or topic will be published.
  • Messages read from a queue will be dequeued.
• Rollback
  • If the user invokes sysLib.rollback() or an unhandled exception occurs in the EGL application/service invocation, then a EGL runtime performs a rollback to the last commit.
  • Messages added to the queue or topic will not be published.
  • Messages read from a queue will be requeued.

Figure 3 Specifying the message destination at run time

EGL MQ Resource Associations

For the EGL runtime to access message queues and topics, a Resource Association must be created to link the MQRecord to an MQ provider. The name of the Resource Association must match the queueName or topicName of the MQRecord.

IBM MQ

Sample properties for IBM MQ are shown in Figure 4, which links the MQRecord with topicName CONTT (Figure 1) to an IBM MQ system. 
Note that exchangeName and exchangeType are not applicable for IBM MQ.

• Provider
  • IBMMQ – Supports existing EGL MQ applications that use IBM MQ options records. Here, Message Queues are supported but not Topics. It uses the IBM AMQP Java driver.
  • IBMMQJMS - This Supports Message Queues and Topics but does not support IBM MQ options records. It uses IBM MQ JMS driver.
• Channel
  • This is the name of the IBM MQ channel used to connect to.
• systemName
  • Specifies the IBM MQ queue manager and the initial values of the queue name or topic string, in one the following format:
    • QueueManagerName:Quename
    • QueueManagerName::TopicString
    • QueueManagerName
• subscriptionName
  • The initial value of the subscriptionName in the MQ record property.

RabbitMQ

Sample properties for RabbitMQ are shown in Figure 5 which links the MQRecord with a topicName of CONTTRAB to a RabbitMQ system.

Note: channel and subscriptionName are not applicable for RabbitMQ.

Figure 5 Resource Association for RabbitMQ

• Provider
  RABBITMQ - Supports Message Queues and Topics. It uses RabbitMQ Java Client Library.
• exchangeName
  This is the name of the RabbitMQ message exchange used to connect to. If the exchange does not exist, an exchange will be created using the exchangeType property defined in the resource association.
• exchangeType
  • When creating a RabbitMQ exchange, this property specifies the type of the message exchange. The topicString property becomes a routing key for routing messages in the exchange. Refer to the supported types mentioned below:
    • NONE – no message exchange is used. Queues are accessed directly. Use this, if the value of isTopicRecord is set to no.
    • DIRECT is for 1-Many exchange listeners with the same single-word routing key. This option is available if the value of isTopicRecord is set to yes.
    • FANOUT is for 1-Many exchange listeners, regardless of routing key. This option is available if the value of isTopicRecord is set to yes.
    • TOPIC is for 1-Many exchange listeners with the same routing key. This key contains separators and wildcards. This option is available if the value of isTopicRecord is set to yes.
  • If the value of the MQ record option isTopicRecord is set to yes, then the default value of exchangeType is TOPIC. Otherwise, the default value is NONE.
• systemName
• Specifies the RabbitMQ virtual host name and the initial values of the queue name or topic string, in one the following format:
  • VirtualHostName:Quename
  • VirtualHostName::TopicString
  • VirtualHostName

Apache ActiveMQ

Sample properties for ActiveMQ are shown in Figure6, which links the MQRecord with a topicName of CONTTAC to an ActiveMQ system. 

Note: channel, exchangeName, and exchangeType are not applicable for ActiveMQ.

Figure 6 Resource Association for Apache ActiveMQ

• Provider
  • ACTIVEMQJMS – It uses the Apache Qpid JMS Driver to access ActiveMQ

• systemName
  • Specifies the initial values of the queue name or topic string, in one the following format:
  •  :Quename
  • ::TopicString
  •      
• subscriptionName
  • The initial value of the subscriptionName MQ record property.

Common Properties
These are the properties, which have the same meaning across all MQ providers.

• conversionTable
  • When the messageFormat is NONE or TEXT, this option specifies the name of the conversion table used to perform automatic data conversion during the message access. 
• Host
  • The TCP/IP hostname of the MQ provider
• Port
  • The TCP/IP port number of the MQ provider
• User
  • The username to connect with
• Password
  • The password for the user

Deploying EGL MQ Applications

EGL MQ applications can be deployed as standalone applications or web services. 

For standalone Java-generated applications, the drivers need to access the MQ provider. The user must provide the information in the Java classpath (Refer to Figure 7)
 

Figure 7 Java Build Path for IBM MQ access

For web applications, the drivers need to access the MQ provider. The user must provide the information in the WEB-INF/lib folder (Refer to Figure 8).

Figure 8 Web Library Path for IBM MQ access

Conclusion

This whitepaper details how an EGL application can send or receive messages using message queues or publishing/subscribing to topics.