MQ Connectivity scenario 1: Fan out broadcast

In this scenario, one IBM® MQ queue is mapped to an Eclipse Amlen topic. Messages that are put on the IBM MQ queue are broadcast to a number of MQTT application subscribers.

Background to this scenario

This MQ Connectivity scenario extends the basic Eclipse Amlen fan-out broadcast end-to-end scenario.

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

You must complete the steps in Scenario: Fan-out broadcast 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, the following rule is required: IBM MQ queue to Eclipse Amlen topic.

  • 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 application is set up, and subscribes to the topic string Retailer/Update.
For the IBM MQ application, use the sample IBM MQ application amqsput.
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 send the messages. In this scenario, the queue manager is called StockUpdateQM. From the command line of the IBM MQ system, enter the following commands:

      crtmqm StockUpdateQM

      strmqm StockUpdateQM

    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 StockUpdateQM

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

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

      START LISTENER ('StockUpdateQListener')

    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 queue from which the messages are sent, and grant specific authorities to allow Eclipse Amlen to access the queue. In this scenario, the queue is called StockUpdateQ and requires GET authority. From the MQSC prompt, enter the following commands:

      DEFINE QLOCAL('StockUpdateQ')

      SET AUTHREC PROFILE('StockUpdateQ') OBJTYPE(QUEUE) PRINCIPAL('MSGUSER') AUTHADD(GET)

  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 StockUpdateQM 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: StockUpdateQMC
        • Queue Manager: StockUpdateQM
        • 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 queue StockUpdateQ to the Eclipse Amlen topic Retailer/Update. 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: StockUpdateDMR
        • Rule Type: MQ queue to Amlen topic
        • Source: StockUpdateQ
        • Destination: Retailer/Update
        • Maximum Messages: 5000
        • Associated queue manager connections: StockUpdateQMC
        • Enabled: True
  3. Optionally, delete the connection policy Stock update Intranet ConPol and messaging policy Stock Update Intranet MsgPol. The MQ Connectivity process does not need a connection policy to connect to Eclipse Amlen. The MQ 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.