MQ Connectivity scenario 4: Fan out per device request-reply

In this scenario, a IBM® MQ topic subtree is mapped to an Eclipse Amlen topic subtree for requests. Messages that are put on topics in the IBM MQ topic subtree are forwarded to the equivalent Eclipse Amlen topic subtree for requests. A different Eclipse Amlen topic subtree is mapped to a IBM MQ topic subtree for responses. Messages that are put on topics in the Eclipse Amlen topic subtree are forwarded to the equivalent IBM MQ topic subtree for responses.

Background to this scenario

This MQ Connectivity scenario extends the basic Eclipse Amlen fan-out per device request-reply end-to-end scenario.

In this scenario, the back end system is replaced by IBM MQ. Request messages are sent from IBM MQ, and Eclipse Amlen forwards the messages on to Eclipse Amlen topics. The subscriber applications subscribe to the topics, and receive messages in the same way as the basic scenario. The subscriber applications then send response messages in the same way as the basic scenario, and Eclipse Amlen forwards the messages on to IBM MQ topics.

You must complete the steps in Scenario: Fan-out per device request-reply to set up the basic scenario before you implement the MQ Connectivity extension.

Planning and implementing the solution

Plan your solution
In this scenario, consider the following key points:

  • What type of destination mapping rule do you need?

    Destination mapping rules identify the source and destination of a message. The source is either an Eclipse Amlen topic, topic subtree, or queue, or a IBM MQ topic, topic subtree, or queue. Similarly, the destination is either an Eclipse Amlen topic, topic subtree, or queue, or a IBM MQ topic, topic subtree, or queue. For more information about the different rule types, see Configuring destination mapping rules.

    In this scenario, request messages are sent from many IBM MQ topics in a subtree. This subtree must be preserved when messages are forwarded. Therefore, the following rule is required: IBM MQ topic subtree to Eclipse Amlen topic subtree.

    Response messages are sent from many subscriber topics in a subtree. This subtree must be preserved when the messages are forwarded to IBM MQ. Therefore, the following rule is also required: Eclipse Amlen topic subtree to IBM MQ topic subtree.

  • Is the order of messages important?

    If the order that messages arrive in is important to your solution, you must set up your solution in a particular way. If you use multiple queue managers to send messages, messages can be sent out of order. If you use multiple queue managers to receive messages, messages can be received out of order.

    However, IBM MQ cannot handle the same volume of messages as Eclipse Amlen. Therefore, in solutions that involve a high volume of messages, you can use multiple queue managers to ensure that a backlog of messages does not build up on Eclipse Amlen. If the message backlog reaches the maximum message count that is set on the destination mapping rule, messages cannot be sent until the backlog reduces.

    When messages are moved from IBM MQ to Eclipse Amlen, Eclipse Amlen forwards persistent messages within transactions, and forwards nonpersistent messages immediately. Therefore, nonpersistent messages can be forwarded before earlier persistent messages are forwarded within a transaction. In this case, message order is not preserved.

    When MQTT messages are moved from Eclipse Amlen to IBM MQ, Eclipse Amlen forwards QoS 1 and QoS 2 messages within transactions, and forwards QoS 0 messages immediately. Therefore, QoS 0 messages can be forwarded before earlier QoS 1 and QoS 2 messages are forwarded within a transaction. In this case, message order is not preserved.

    When JMS messages are moved from Eclipse Amlen to IBM MQ, Eclipse Amlen forwards both JMS persistent and nonpersistent messages within transactions. If a nonpersistent message has the ConnectionFactory property DisableACK set, the message is forwarded immediately. Therefore, nonpersistent JMS messages with DisableACK set can be forwarded before earlier JMS messages are forwarded within a transaction. In this case, message order is not preserved.

    In this scenario, IBM MQ is the source of the messages, and a single queue manager is sufficient to handle the volume of messages. All the messages that are sent have the same quality of service. Therefore, the order of messages is automatically preserved.

Write your applications
Continuing from the basic scenario, the subscriber applications are set up, and subscribe to the topic string Shutdown/Request/clientID, where clientID specifies the client ID of the machine application. The subscriber applications are also set up to publish to the topic string Shutdown/Response/clientID, where clientID specifies the client ID of the machine application.
For the IBM MQ applications, use the sample IBM MQ applications amqspub and amqssub.
Alternatively, you can write your own IBM MQ application. For more information about writing IBM MQ publish/subscribe applications, see Writing publish/subscribe applications in the IBM MQ documentation. For more information about writing IBM MQ queuing applications, see Writing a queuing application in the IBM MQ documentation.
Set up your infrastructure
  1. Set up IBM MQ:
    1. Create a queue manager to handle the messages. In this scenario, the queue manager is called ShutdownQM. From the command line of the IBM MQ system, enter the following commands:

      crtmqm ShutdownQM

      strmqm ShutdownQM

    2. Make a note of the IP address or host name of the IBM MQ system. These details are used when you create a queue manager connection.
    3. The following steps use MQSC commands, which must be run from an MQSC command prompt. From the command line, enter the following command to start MQSC:

      runmqsc ShutdownQM

    4. Create a server-connection channel for the queue manager. In this scenario, the server-connection channel is called MQ.MSG.SVRCONN. From the MQSC prompt, enter the following command:

      DEFINE CHANNEL(MQ.MSG.SVRCONN) CHLTYPE(SVRCONN) TRPTYPE(TCP)

    5. Start a listener for the queue manager. In this scenario, the listener is called ShutdownQL, and listens on port 1414. From the MQSC prompt, enter the following commands:

      DEFINE LISTENER ('ShutdownQL') TRPTYPE(TCP) CONTROL(QMGR) PORT(1414)

      START LISTENER ('ShutdownQL')

    6. Authorize Eclipse Amlen to connect to the queue manager:
      1. Create a user ID on the IBM MQ system. In this scenario, the user ID is called MSGUSER.
      2. Create a channel authentication record that allows only the Eclipse Amlen IP address to use the server-connection channel that you created in step 1d. From the MQSC prompt, enter the following command:

        SET CHLAUTH(MQ.MSG.SVRCONN) TYPE(ADDRESSMAP) ADDRESS(IPAddress) MCAUSER('MSGUSER')

        Where:
        IPAddress
        Specifies the IP address of the Eclipse Amlen server.
      3. Grant general IBM MQ access to MSGUSER. From the MQSC prompt, enter the following commands:

        SET AUTHREC OBJTYPE(QMGR) PRINCIPAL('MSGUSER') AUTHADD(CONNECT, INQ, DSP)

      4. Grant authority for the user MSGUSER to issue requests to IBM MQ:

        SET AUTHREC PROFILE('SYSTEM.DEFAULT.MODEL.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('MSGUSER') AUTHADD(DSP, GET)

        SET AUTHREC PROFILE('SYSTEM.ADMIN.COMMAND.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('MSGUSER') AUTHADD(DSP, PUT)

      5. Grant authority for the user MSGUSER to create a queue for Eclipse Amlen synchronization records:

        SET AUTHREC PROFILE('SYSTEM.IMA.*') OBJTYPE(QUEUE) PRINCIPAL('MSGUSER') AUTHADD(CRT, PUT, GET, BROWSE)

        SET AUTHREC PROFILE('SYSTEM.DEFAULT.LOCAL.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('MSGUSER') AUTHADD(DSP)

    7. Create the IBM MQ topic objects, and grant specific authorities to allow Eclipse Amlen to access the topics. In this scenario, the request topic object is called ShutdownRequest and requires PUB, DSP authority. The response topic object is called ShutdownResponse and requires SUB, CTRL authority. From the MQSC prompt, enter the following commands:

      DEFINE TOPIC('ShutdownRequest') TOPICSTR('Shutdown/Request')

      SET AUTHREC PROFILE('ShutdownRequest') OBJTYPE(TOPIC) PRINCIPAL('MSGUSER') AUTHADD(PUB, DSP)

      DEFINE TOPIC('ShutdownResponse') TOPICSTR('Shutdown/Response')

      SET AUTHREC PROFILE('ShutdownResponse') OBJTYPE(TOPIC) PRINCIPAL('MSGUSER') AUTHADD(SUB, CTRL)

  2. Set up Eclipse Amlen:
    1. Create a queue manager connection so that Eclipse Amlen can connect to the queue manager. In this scenario, Eclipse Amlen must connect to the ShutdownQM queue manager. From the Amlen WebUI:
      1. Go to the MQ Connectivity page by clicking Messaging > MQ Connectivity.
      2. Under the Queue Manager Connection Properties pane, click the Add icon.
      3. Enter the details for a queue manager connection, and click Save. In this scenario, the following values are used:
        • Name: ShutdownQMC
        • Queue Manager: ShutdownQM
        • Connection Name: The IP address or host name of the IBM MQ system on which the queue manager was configured.
        • Channel Name: MQ.MSG.SVRCONN
    2. Create destination mapping rules to map from the message sources to the message destinations. In this scenario, the first destination mapping rule must map from the IBM MQ topic subtree Shutdown/Request to the Eclipse Amlen topic subtree Shutdown/Request. With this rule, a message that is published on the IBM MQ topic Shutdown/Request/123 is forwarded to the Eclipse Amlen topic Shutdown/Request/123. The second destination mapping rule must map from the Eclipse Amlen topic subtree Shutdown/Response to the IBM MQ topic subtree Shutdown/Response. From the Amlen WebUI:
      1. Go to the MQ Connectivity page by clicking Messaging > MQ Connectivity.
      2. Under the Destination Mapping Rules pane, click the Add icon.
      3. Enter the details for the first destination mapping rule, and click Save. In this scenario, the following values are used:
        • Name: RequestDMR
        • Rule Type: MQ topic subtree to Amlen topic subtree
        • Source: Shutdown/Request
        • Destination: Shutdown/Request
        • Maximum Messages: 5000
        • Associated queue manager connections: ShutdownQMC
        • Enabled: True
      4. Create the second destination mapping rule in the same way. In this scenario, the following values are used:
        • Name: ResponseDMR
        • Rule Type: Amlen topic subtree to MQ topic subtree
        • Source: Shutdown/Response
        • Destination: Shutdown/Reseponse
        • Maximum Messages: 5000
        • Associated queue manager connections: ShutdownQMC
        • Enabled: True
  3. Optionally, delete the messaging policies Shutdown Request Backend MsgPol, and Shutdown Response Backend MsgPol. TheMQ Connectivity process uses the information that is contained in the destination mapping rules to restrict messaging activities, and therefore does not need messaging policies.
Test your solution
Use your applications to send test messages through the system and check that the solution works. Use the Troubleshooting section to help you resolve any problems that you encounter.
Monitor your solution
Use the monitoring tools from the basic scenario to monitor the solution.
Strengthen your security
Beyond the security enhancements that can be completed in the basic scenario, you can use SSL to secure the connection between Eclipse Amlen and IBM MQ. To use SSL to secure the connection, you must configure key repository databases and password stash files. For more information, see Configuring MQ Connectivity security by using CA certificates and Configuring MQ Connectivity security by using self-signed certificates.