MQ Connectivity scenario 3: Fan out per device notification

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

Background to this scenario

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

In this scenario, the publisher application is replaced by IBM MQ. Messages are published to IBM MQ topics, and Eclipse Amlen forwards the messages on to the equivalent Eclipse Amlen topics. The subscriber applications subscribe to the topics, and receive messages in the same way as the basic scenario.

You must complete the steps in Scenario: Fan-out per device notification 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, as messages are being sent to many topics within a subtree, and the subtree must be preserved in Eclipse Amlen, the following rule is required: IBM MQ topic subtree to Eclipse Amlen 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 car/clientID, where clientID specifies the client ID of the application.
For the IBM MQ applications, use the sample IBM MQ application amqspub.
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 CarHireQM. From the command line of the IBM MQ system, enter the following commands:

      crtmqm CarHireQM

      strmqm CarHireQM

    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 CarHireQM

    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 CarHireQL, and listens on port 1414. From the MQSC prompt, enter the following commands:

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

      START LISTENER ('CarHireQL')

    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 topic object is called CarHire and requires PUB, DSP authority. From the MQSC prompt, enter the following commands:

      DEFINE TOPIC('CarHire') TOPICSTR('car')

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

  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 CarHireQM 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: CarHireQMC
        • Queue Manager: CarHireQM
        • 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 a destination mapping rule to map from the message source to the message destination. In this scenario, the destination mapping rule must map from the IBM MQ topic subtree car to the Eclipse Amlen topic subtree car. With this rule, a message that is published on the IBM MQ topic car/123 is forwarded to the Eclipse Amlen topic car/123. 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 a destination mapping rule, and click Save. In this scenario, the following values are used:
        • Name: CarHireDMR
        • Rule Type: MQ topic subtree to Amlen topic subtree
        • Source: Car
        • Destination: Car
        • Maximum Messages: 5000
        • Associated queue manager connections: CarHireQMC
        • Enabled: True
  3. Optionally, delete the connection policy Car Messaging Intranet ConPol and messaging policy Car Messaging Intranet MsgPol. The MQ Connectivity process does not need a connection policy to connect to Eclipse Amlen. TheMQ Connectivity process uses the information that is contained in the destination mapping rules to restrict messaging activities, and therefore does not need a messaging policy.
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.