Scenario 2: Request and response using MQTT
This chapter shows a scenario of request and response between an Android-based device, IBM MessageSight, and IBM Integration Bus. The device sends out a request by publishing a request message. This message is sent out as an MQTT message, and a response message is delivered to the Android-based device as an MQTT message.
This chapter covers the following topics:
•Scenario description
•Scenario setup
•Scenario execution
•Scenario testing
8.1 Scenario description
Consider an Android application running on a hand-held device as the MQTT client application. This hand-held device is onboard the trucks in the fleet of the ITSO Transport Corporation company. This hand-held device is expected to be used by a driver (when the truck is stopped) to request assistance in case
of difficulty.
of difficulty.
Chapter 6, “Scenarios overview” on page 175 describes the scenario application used in this book in more detail. This chapter describes the scenario for the request and response portion of the application.
From a user’s perspective, the hand-held device has options to send out a request for assistance when the driver faces a difficult situation. The response is delivered from the back-end system to address the driver's difficulty as soon as possible.
For example, the truck might carry perishable goods that are kept at a constant temperature by the air-conditioning onboard the truck. At some point, the driver might detect that the air-conditioning is unable to maintain the required temperature.
The driver then sends out a request for assistance with the malfunctioning air conditioner. The back-end system can then dispatch an air-conditioner mechanic to a location nearest to the location from where the request originated.
For the specific request, the back-end system (the enterprise system of ITSO Transport Corporation) delivers the response to the truck that requested assistance. This is different from the scenario where the back-end system broadcasts general information about routes, weather, goods delivery, and so on to all of the trucks in the fleet.
8.2 Scenario setup
We assume that the Android application is already up and running, either on an emulator or a real device. We also assume that a connection between IBM MessageSight and WebSphere MQ already exists. For more information about how to set up the WebSphere MQ connection, see 3.1, “WebSphere MQ connectivity and destination mapping” on page 40.
|
Tip: For more information about running an Android application on a real device or Eclipse IDE (with Android plug-ins), see the Running Your App topic at the following website:
|
Complete the following tasks to set up this scenario:
1. Define and save the Java Message Service (JMS) bindings file to a location to which the integration server has access.
2. Define the destination mapping rules on the IBM MessageSight appliance so that the publications on MQTT and JMS topic strings are exchanged automatically.
3. Deploy the IBM Integration Bus application to an integration node on an integration server.
8.2.1 JMS bindings file
The JMS bindings file can be developed using WebSphere MQ Explorer. Alternatively, you can use the bindings file that was developed for the application. In either option, the following conventions must be followed:
•Name of the connection factory
This is the name to be used in the JMS nodes of the message flow.
•Destination type
The type of destination will be the topic, because the destination mapping rule in the IBM MessageSight appliance maps MQTT and JMS topic subtrees.
•Destination name
The name of the destinations must match with the value used in the JMS nodes for input and output.
•Topic strings
The topic strings must match with the ones used in the destination mapping rule on the IBM MessageSight appliance. The destination mapping rule maps an IBM MessageSight topic subtree and a WebSphere MQ topic subtree, which is then subscribed using JMS in WebSphere Message Broker.
In this application, the JMS bindings file was developed using WebSphere MQ Explorer. Figure 8-1 shows a JMS-administered object, and the bottom half shows the connection factory and topic strings.
Figure 8-1 JMS-administered objects defined in WebSphere MQ Explorer
Figure 8-2 shows some of the details of the connection factory as defined in
the JMS object. The name of the connection factory shown here must match with the name of the connection factory provided in the JMS nodes in the message flow.
the JMS object. The name of the connection factory shown here must match with the name of the connection factory provided in the JMS nodes in the message flow.
Figure 8-2 Connection factory of the JMS-administered object
Figure 8-3 shows the topic definitions for the connection factory shown in Figure 8-2 on page 205. The name of the topics must match with the value entered in the JMS nodes. Similarly, the topic string shown in Figure 8-3 must match with the value of the topic string as provided in the IBM MessageSight destination mapping rule.
Figure 8-3 Definitions of topics name and strings
After all of the definitions are complete, this bindings file needs to be saved at a location that the integration server has access to. Note that this location
must match with the value set for the JMS nodes in the IBM Integration Bus message flow.
must match with the value set for the JMS nodes in the IBM Integration Bus message flow.
Figure 8-4 shows the values set for the JMS Connection tab for the JMSInput node. Note that the name of the connection factory matches with the one shown in Figure 8-2 on page 205. The location of the bindings file needs to be a location that the Integration server has access to.
Figure 8-4 Values set for the JMS Connection of the JMSInput node
Figure 8-5 shows the values for JMS Connection as set for the JMSOutput node.
Figure 8-5 Values set for the JMS Connection of the JMSOutput node
Figure 8-6 shows the values set on the Basic tab for the JMSInput node. Note that the name of the request topic matches with the one shown in Figure 8-3 on page 206.
Figure 8-6 Values set for Basic tab of the JMSInput node
Figure 8-7 shows the values set on the Basic tab for the JMSOutput node.
Figure 8-7 Values set for Basic tab of the JMSOutput node
8.2.2 Destination mapping rules between IBM MessageSight and WebSphere MQ
For this scenario, the destination mapping rule between IBM MessageSight and WebSphere MQ must be set with the following values, as shown in Table 8-1.
Table 8-1 Values for destination mapping rule to WebSphere MQ
|
Property name
|
Value
|
Remarks
|
|
Name
|
ITSO_IMA_QM_MAP_01
|
This is the name of the destination mapping rule.
|
|
Rule type
|
IBM MessageSight topic subtree to WebSphere MQ topic subtree
|
The source and destination are both topics because the MQTT client publishes onto topics on the IBM MessageSight appliance. Also, an application in the integration server subscribes to topics on WebSphere MQ.
This rule type uses topic subtrees because the complete topic string is not known well in advance. Therefore, all topic publications for all drivers of all assistance types on IBM MessageSight are mapped to WebSphere MQ topics.
|
|
Source
|
/itso/driver/assistance/request
|
The topic subtree onto which the MQTT client (Android application on hand-held) publishes.
|
|
Destination
|
/WMQ/driver/assistance/request
|
The topic subtree subscribed by the JMSInput node in the message flow.
|
|
Max messages
|
5000
|
This is the maximum number of messages in the buffer. It must be set to a value based on the expected volume and performance expectations.
|
|
Associated queue manager connection
|
ITSO_IMA_CONN
|
An WebSphere MQ connection name to which the IBM MessageSight appliance connects. Multiple connection names can be selected to allow for higher throughput.
|
For the exact mechanism to create the destination mapping rule, see 3.1, “WebSphere MQ connectivity and destination mapping” on page 40 and 3.2.1, “JMS integration with WebSphere MQ as the JMS provider” on page 47.
Figure 8-8 shows the destination mapping rule between IBM MessageSight and WebSphere MQ for this scenario. See Example 3-4 on page 50 for more information about how to create this destination mapping rule from the command-line interface (CLI).
Figure 8-8 Destination mapping rule from IBM MessageSight to the WebSphere MQ topic subtrees
For this scenario, the destination mapping rule between WebSphere MQ and IBM MessageSight must be set with the following values, as shown in Table 8-2 on page 211.
Table 8-2 Values for the destination mapping rule to IBM MessageSight
|
Property name
|
Value
|
Remarks
|
|
Name
|
ITSO_IMA_QM_MAP_02
|
This is the name of the destination mapping rule.
|
|
Rule type
|
WebSphere MQ topic subtree to IBM MessageSight topic subtree
|
The source and destination are both topics because the application in the integration server publishes to topics on WebSphere MQ and MQTT client subscribes to topics on IBM MessageSight appliance.
This rule type uses topic subtrees, because the complete topic string is not known well in advance. Therefore, all topic publications for responses to all drivers on WebSphere MQ topics will be mapped to IBM MessageSight topics.
|
|
Source
|
/WMQ/driver/assistance/
response |
The topic subtree onto which the application in the integration server publishes (through the JMSOutput node).
|
|
Destination
|
/itso/driver/assistance/response
|
The topic subtree subscribed by the MQTT client (the Android application on the hand-held device).
|
|
Max messages
|
5000
|
This is the maximum number of messages in the buffer. It must be set to a value based on the expected volume, and performance expectations. This value has no effect for a destination mapping rule from WebSphere MQ to MessageSight, only for a rule from MessageSight to WebSphere MQ. That is why it is disabled in Figure 8-9 on page 212.
|
|
Associated queue manager connection
|
ITSO_IMA_CONN
|
An WebSphere MQ connection name to which the IBM MessageSight appliance connects. Multiple connection names can be selected to allow for higher throughput.
|
For the exact mechanism to create the destination mapping rule, see 3.1, “WebSphere MQ connectivity and destination mapping” on page 40 and 3.2.1, “JMS integration with WebSphere MQ as the JMS provider” on page 47. Figure 8-9 shows the destination mapping rule between WebSphere MQ and IBM MessageSight for this scenario. See Example 3-5 on page 52 for information about how to create this destination mapping rule from the CLI.
Figure 8-9 Destination mapping rule from WebSphere MQ to IBM MessageSight topic subtrees
8.2.3 Creating and deploying an IBM Integration Bus application
Deploy the IBM Integration Bus application to an integration server on the integration node instance. You can download this application from the IBM Redbooks website, as described in Appendix D, “Additional material” on page 341.
Creating an IBM Integration Bus application
This section describes the ITSOAssistanceRequestResponse application to be deployed in IBM Integration Bus for this scenario. This application has a message flow that consists of four nodes, as shown in Figure 8-10 on page 213.
Figure 8-10 The ITSOAssistanceRequestResponse IBM Integration Bus application
Table 8-3 shows the nodes in the message flow of the ITSO Assistance Request Response application.
Table 8-3 Nodes in message flow of the ITSOAssistanceRequestResponse application
|
Node name
|
Node type
|
Description
|
|
ReceiveAssistanceRequest
|
JMSInput node
|
This node subscribes to a topic on WebSphere MQ, and receives roadside assistance request.
|
|
ParseRequest
|
Reset Content Descriptor node
|
This node converts the BLOB message into DFDL
|
|
FormulateResponse
|
Compute node
|
A response message is created for the roadside request received. Topic name for response is set.
|
|
SendAssistanceResponse
|
JMSOutput node
|
This node publishes the roadside assistance response on a topic on WebSphere MQ.
|
Table 8-4 Connection between nodes
|
Source node
|
Output terminal
|
Destination node
|
Input terminal
|
|
ReceiveAssistance
Request |
Out
|
ParseRequest
|
In
|
|
ParseRequest
|
Out
|
FormulateResponse
|
In
|
|
FormulateResponse
|
Out
|
SendAssistance
Response |
In
|
Table 8-5 shows the properties configured for the nodes in this message flow.
Table 8-5 Node properties
|
Node name
|
Property tab
|
Property name
|
Property value
|
|
ReceiveAssistance
Request |
Basic
|
Subscription Topic
|
RequestTopic
|
|
ReceiveAssistance
Request |
JMS Connection
|
Location JNDI bindings
|
file:///home/
wmbadmin/ itsoappjms/ |
|
ReceiveAssistance
Request |
JMS Connection
|
Connection factory name
|
ItsoConnFactory01
|
|
ParseRequest
|
Basic
|
Message Domain
|
DFDL (for binary or text messages with a Data Format Description Language (DFDL) schema model)
|
|
ParseRequest
|
Basic
|
Reset Message Domain
|
True
|
|
ParseRequest
|
Basic
|
Reset Message model
|
True
|
|
ParseRequest
|
Basic
|
Message
|
{urn:com.ibm.itso.samples}:itsoGeoLocationRequest
|
|
ParseRequest
|
Basic
|
Reset Message
|
True
|
|
FormulateResponse
|
Basic
|
Compute mode
|
LocalEnvironment and Message
|
|
SendAssistanceResponse
|
Basic
|
Send to destination list in local environment
|
True
|
|
SendAssistanceResponse
|
JMS Connection
|
Location Java Naming and Directory Interface (JNDI) bindings
|
file:///home/
wmbadmin/ itsoappjms/ |
|
SendAssistanceResponse
|
JMS Connection
|
Connection factory name
|
ItsoConnFactory01
|
Example 8-1 shows the extended SQL (ESQL) code in the FormulateResponse compute node.
Example 8-1 ESQL in FormulateResponse compute node
BROKER SCHEMA com.ibm.itso.samples
DECLARE ns NAMESPACE 'urn:com.ibm.itso.samples';
CREATE COMPUTE MODULE itsoFlow01_CMP01
CREATE FUNCTION Main() RETURNS BOOLEAN
BEGIN
Declare requestTopicString Character ;
Declare responseTopicString Character ;
Declare assistanceText Character ;
-- Set topic string for response
Set requestTopicString = InputRoot.JMSTransport.Transport_Folders.Header_Values.JMSDestination;
Set responseTopicString = getResponseTopicString(requestTopicString);
Set OutputLocalEnvironment.Destination.JMSDestinationList.DestinationData.DestinationName
= responseTopicString ;
Set OutputLocalEnvironment.Destination.JMSDestinationList.DestinationData.DestinationType
= 'Topic' ;
-- Set delivery mode appropriate for QoS=2 MQTT message from MessageSignt to subscriber
Set OutputRoot.JMSTransport.Transport_Folders.Header_Values.JMSDeliveryMode.(XML.Attribute)dt = 'i4';
Set OutputRoot.JMSTransport.Transport_Folders.Header_Values.JMSDeliveryMode = 2;
-- Set body of response
Set OutputRoot.DFDL.ns:itsoGeoLocationResponse.responseMessage.driverId =
InputRoot.DFDL.ns:itsoGeoLocationRequest.requestMessage.driverId;
Set assistanceText = getAssistanceText(requestTopicString);
Set OutputRoot.DFDL.ns:itsoGeoLocationResponse.responseMessage.assistanceText =
assistanceText;
RETURN TRUE;
END;
Create Function getResponseTopicString(In requestTopicString Char) Returns Char Begin
Declare responseTopicString Character;
-- Subject of assistance and Truck ID e.g. ACMalfunction/Truck1
Set responseTopicString = Substring(requestTopicString after 'topic:///WMQ/driver/assistance/request/'),
-- Truck ID for final response string.
Set responseTopicString = Substring(responseTopicString after '/'),
Set responseTopicString = 'topic:///WMQ/driver/assistance/response/' || responseTopicString ;
Return responseTopicString;
End ;
Create Function getAssistanceText(In requestTopicString Char) Returns Char Begin
Declare assistanceType Character ;
Declare assistanceText Character ;
-- Subject of assistance and Truck ID e.g. ACMalfunction/Truck1
Set assistanceType = Substring(requestTopicString after 'topic:///WMQ/driver/assistance/request/'),
-- Subject of assistance
Set assistanceType = Substring(assistanceType before '/'),
Case
When assistanceType = 'ACMalfunction' Then
Set assistanceText = ' AC Engineer dispatched to your nearest location.';
When assistanceType = 'FlatTire' Then
Set assistanceText = ' Vehicle mechanic dispatched to your nearest location.';
When assistanceType = 'Accident' Then
Set assistanceText = ' Emergency staff notified and dispatched to your nearest location.';
Else
Set assistanceText = 'Message not understood.';
End Case;
Return assistanceText;
End ;
END MODULE;
After the application is created, it is compiled and deployed on the integration server.
8.3 Scenario execution
We begin by introducing the components of the scenario. Then, we describe the connectivity between these components, both the flow of the messages and the protocols involved. Finally, we also describe the sample messages that are exchanged between the various components.
8.3.1 Components of the scenario
Figure 8-11 shows the components of a request/response scenario. The components include the Android application on the hand-held device that behaves as the MQTT client. The IBM MessageSight appliance has an endpoint that caters to the MQTT publications and subscriptions.
Through WebSphere MQ connection and destination mapping rules, the IBM MessageSight appliance communicates with an WebSphere MQ queue manager. Finally, the IBM Integration Bus communicates with the queue manager to process the request and deliver the response.
Figure 8-11 Components of the request/response scenario
The following steps describe the overall solution flow:
1. The Android application on the hand-held device sends out a request. This request is seeking assistance, such as for an air-conditioner malfunction, a flat tire, or an accident.
2. The request is published as an MQTT publication on a topic string on the IBM MessageSight appliance where one of the endpoints is configured to accept the MQTT publication. The IP address and the port number of this endpoint is configured in the application beforehand.
3. The IBM MessageSight appliance is configured with a WebSphere MQ connection so that IBM MessageSight can communicate with a WebSphere MQ queue manager instance. The appliance is also configured with a destination mapping rule so that the MQTT topic strings are mapped to JMS topic strings on WebSphere MQ.
4. The IBM Integration Bus has a message flow, with JMSInput and JMSOutput nodes, running. The JMSInput node subscribes to the JMS topic strings to which the destination mapping rule on the IBM MessageSight appliance mapped the MQTT publication.
5. This message flow parses the topic string and determines the truck number and the request type. With this parsed information, an appropriate business rule is started. In this scenario, the business rule is no more than returning with a favorable response corresponding to the request.
6. The message flow publishes the response through a JMSOutput node onto a topic string on the IBM MessageSight appliance.
7. The IBM MessageSight appliance maps this WebSphere MQ topic string to the IBM MessageSight topic string as defined in the destination mapping rule.
8. The Android application on the hand-held device subscribes to this topic string and receives the response.
8.3.2 Topic strings and protocols
Table 8-6 summarizes the applications, their actions, their topic strings, and the protocol involved. The Action column describes the action on the IBM MessageSight appliance.
Table 8-6 Topic strings and protocols on the IBM MessageSight appliance
|
From
|
Action
|
Topic string
|
Protocol
|
|
Android application
|
Publish
|
/itso/driver/assistance/request
|
MQTT
|
|
Android application
|
Subscribe
|
/itso/driver/assistance/response
|
MQTT
|
|
IBM Integration Bus message flow
|
Publish
|
/WMQ/driver/assistance/response
|
JMS
|
|
IBM Integration Bus message flow
|
Subscribe
|
/WMQ/driver/assistance/request
|
JMS
|
8.3.3 Sample messages
The messages, published as requests for assistance, conform to the following pattern:
yyyy-mm-dd hh:MM:ss,driverID,latitude,longitude
These request messages are published onto a topic string in the following pattern:
/itso/driver/assistance/request/requestType/TruckID
The requestType is one of ACMalfunction, FlatTire, or Accident, and the TruckID is the ID of the truck that also serves as the client ID of the MQTT client.
The response message received follows a pattern:
driverID,assistance message
This response message is published onto a topic string that follows a pattern:
/itso/driver/assistance/response/TruckID
For example, a sample request message (2013-08-09 15-10-29,driver01,-142.08409333333,23.422005) is published onto a topic string /itso/driver/assistance/request/ACMalfunction/CASJC01.
The corresponding response is received as (driver01, AC Engineer despatched to your nearest location) on the topic string /itso/driver/assistance/response/CASJC01.
Using this example, Table 8-6 on page 219 can be rewritten with complete topic strings, as shown in Table 8-7.
Table 8-7 Topic strings on the IBM MessageSight appliance
|
From
|
Action
|
Topic string
|
|
Android application
|
Publish
|
/itso/driver/assistance/request/ACMalfunction/
CASJC01 |
|
Android application
|
Subscribe
|
/itso/driver/assistance/response/CASJC01
|
|
IBM Integration Bus message flow
|
Publish
|
/WMQ/driver/assistance/response/CASJC01
|
|
IBM Integration Bus message flow
|
Subscribe
|
/WMQ/driver/assistance/request/ACMalfunction/
CASJC01 |
|
Note: The message flow in IBM Integration Bus parses the publication topic string to determine the nature of the request and the truck identifier. This enables the flow to formulate an appropriate response, and also the topic string to which the response must be delivered.
|
8.4 Scenario testing
Test this scenario:
1. Start the Android application.
2. Connect to the IBM MessageSight appliance.
3. Publish a request message.
The response is received on the Android application.
Authenticate with IBM MessageSight:
1. Enter the driver ID, password, and the Truck ID.
2. Click Login, as shown in Figure 8-12.
Figure 8-12 Log in to IBM MessageSight appliance
To send an assistance request, follow these steps:
1. Click the Assistance tab.
2. Click Air Condition Malfunction.
3. Enter the QoS value as 2.
4. Enter AC leaking coolant in the Assistance Request Text box.
5. Click Ask Assistance.
Figure 8-13 shows the Android application requesting assistance.
Figure 8-13 Requesting assistance (publish request message)
6. As a result of step 5, the Android application publishes the request message to a topic string determined by the truck identifier and the request type, as described in Table 8-7 on page 220.
7. The back-end system responds back with the message (its QoS is also set to 2). Figure 8-14 shows the response as received on the Android application.
Figure 8-14 Response received on Android application (subscription of response message)
|
Tip: This setup can be used with WebSphere Message Broker v8.0 to integrate with IBM MessageSight through WebSphere MQ as the JMS Service provider.
|
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.