Integration with enterprise systems
This chapter contains information about how the IBM MessageSight appliance can be integrated with other IBM Messaging products, such as IBM WebSphere MQ and the IBM Integration Bus (formerly known as WebSphere Message Broker) to provide an important front edge feature for your existing messaging infrastructure.
For the purposes of this book, we assume a general working knowledge of WebSphere MQ, WebSphere Message Broker, and IBM Integration Bus. The book does not provide details about the installation and configuration of those products. It provides information about how to implement IBM MessageSight with those products to achieve the following connectivity options:
•WebSphere MQ connectivity and destination mapping
•Java Message Service (JMS) integration from WebSphere Message Broker to IBM MessageSight using WebSphere MQ as a JMS provider
•IBM MessageSight connectivity to IBM Integration Bus using JMS nodes that use the IBM MessageSight implementation of JMS
•Back-end enterprise applications direct connection to the IBM MessageSight appliance using the C or Java MQTT application programming interfaces (APIs), or the IBM MessageSight implementation of JMS
3.1 WebSphere MQ connectivity and destination mapping
You can configure the IBM MessageSight appliance to link with new or existing WebSphere queue managers with the MQ Connectivity feature. You can use the MQ Connectivity feature with WebSphere MQ Version 7.1 onwards.
The MQ Connectivity feature of the IBM MessageSight provides the bidirectional exchange of messages between the IBM MessageSight appliance and one or more WebSphere MQ queue managers. The MQ Connectivity feature works with messages that are both point-to-point (queue-based) and publish/subscribe.
The connection from the IBM MessageSight appliance to the queue manager uses a WebSphere MQ client channel that can be secured using Secure Sockets Layer (SSL) or Transport Layer Security (TLS). A single user ID is defined on the queue manager for IBM MessageSight authentication.
|
Important: When connecting to WebSphere MQ queue managers, the MQ Connectivity feature automatically creates queues on the queue manager. These queues have names that start with SYSTEM.IMA. Do not edit or delete these queues, because the MQ Connectivity feature requires them to function.
|
For the purposes of this book, we assume that you have already installed and created a WebSphere MQ queue manager. You learn about the steps necessary to connect the IBM MessageSight appliance to the queue manager, enable connectivity, and achieve integration that enables messages to flow between topics and queues from one product to the other.
To connect IBM MessageSight to WebSphere MQ, you create a SVRCONN channel between the IBM MessageSight appliance and the queue manager, and then you configure destination mapping rules. To define a SVRCONN channel on the queue manager, run the runmqsc command on the server where the queue manager is running, as shown in Example 3-1.
Example 3-1 Creating a connection
$ runmqsc MQTT_QMGR
5724-H72 (C) Copyright IBM Corp. 1994, 2011. ALL RIGHTS RESERVED.
Starting MQSC for queue manager MQTT_QMGR.
define chl(IMA.SVRCONN) chltype(SVRCONN)
1 : define chl(IMA.SVRCONN) chltype(SVRCONN)
AMQ8014: WebSphere MQ channel created.
After the channel is created on the queue manager, complete the following steps to configure the IBM MessageSight MQ Connectivity feature:
1. Log in to the IBM MessageSight appliance with a supported browser using an HTTPS IP address and port number. Sign in as an administrator (Figure 3-1).
Figure 3-1 IBM MessageSight login window
2. After you are signed in, click MQ Connectivity at the bottom of the Home tab, or you can choose Messaging → MQ Connectivity, as shown in Figure 3-2.
Figure 3-2 Select MQ Connectivity from the Messaging drop-down list
3. The Queue Manager Connection Properties (Figure 3-3) list is displayed. This is where you specify the connection details for a WebSphere MQ queue manager. Queue manager connections are used in destination mapping rules to specify the location of the WebSphere MQ topic or queue.
Click the green plus (+) sign to add a queue manager connection.
Figure 3-3 WebSphere Queue Manager Connection Properties list
4. In the Add Queue Manager Connection window, complete the Name of the connection, the Queue Manager name, the Connection Name, and the SVRCONN Channel Name.
You must supply the name of the SVRCONN channel that was defined on the queue manager to use for your IBM MessageSight connection. In this example, we use the IMA.SVRCONN channel, as shown in Figure 3-4.
Figure 3-4 Adding queue manager connection information
5. Note that the ID you are using on IBM MessageSight must have proper authority to access the WebSphere MQ objects, or you see errors in the queue manager logs, as shown in Example 3-2.
Example 3-2 Invalid ID error message
AMQ5653: The user 'admin' is not defined.
EXPLANATION: The system call getpwnam("admin") failed with errno -1.
ACTION: Create the user 'admin' and retry the operation.
To prevent these types of errors, be sure you have granted WebSphere MQ authorities, as shown in Example 3-3.
Example 3-3 WebSphere MQ authorities
setmqaut -m MQTT_QMGR -t qmgr -g msadmin +connect +dsp +inq
setmqaut -m MQTT_QMGR -t queue -n SYSTEM.DEFAULT.MODEL.QUEUE -g msadmin +dsp +get
setmqaut -m MQTT_QMGR -t queue -n SYSTEM.ADMIN.COMMAND.QUEUE -g msadmin +dsp +put
setmqaut -m MQTT_QMGR -t queue -n SYSTEM.IMA.* -g msadmin +crt +put +get +browse
setmqaut -m MQTT_QMGR -t queue -n SYSTEM.DEFAULT.LOCAL.QUEUE -g msadmin +dsp
For more information about how to manage WebSphere MQ security and authorities, see the WebSphere MQ Information Center:
6. Next, create destination mapping rules. While still on the MQ Connectivity tab of the web user interface (web UI), click the green plus (+) sign under The Destination Mapping Rules. The Add Destination Mapping Rule displays, and you can enter the rule information.
The drop-down list for Rule Type (Figure 3-5) enables you to select how you want to map between topics and queues.
Figure 3-5 Selecting a rule type for mapping objects
7. Figure 3-6 shows adding a rule to map an IBM MessageSight topic to a WebSphere MQ queue.
Figure 3-6 Adding destination mapping rules
You must also select the Associated check box under Associated queue manager connections to associate the Destination Mapping rule with the appropriate queue manager connection.
After a rule is created and enabled (select the Enabled check box), messages are routed as configured. Be aware that a destination mapping rule cannot be edited or deleted when it is enabled. If you want to edit or delete a rule, you must first disable the rule using the Other Actions menu located near the plus (+), x, and pencil icons under the Destination Mapping Rules heading.
The IBM MessageSight appliance can handle a higher volume of messages than WebSphere MQ. To deal with the higher volume of messages, you can maximize message throughput by using multiple WebSphere MQ queue managers to handle the load.
However, using multiple queue managers does not preserve the order of the messages. If your application design requires that you preserve the order of the messages, you must use only a single queue manager connection to send or receive messages.
If WebSphere MQ cannot keep up with the volume of messages that the IBM MessageSight appliance forwards, a backlog of messages forms on the IBM MessageSight appliance. For a destination mapping rule from an IBM MessageSight topic or topic subtree, the maximum messages parameter applies.
You define the number of messages that can be in this backlog in the Max Message field in the Add Destination Mapping Rule window.
The release of IBM MessageSight V1.1 includes new features, such as a resource adapter and shared subscriptions, which can help spread the workload and prevent message backlog from occurring.
Shared subscriptions allow multiple consumers to help process published messages, and is useful in situations where a single consumer cannot keep up with the rate of messages being published.
The combination of the resource adapter and shared subscriptions available in IBM MessageSight V1.1 is really powerful, because it enables a stream of messages to be distributed among a set of application servers, such as a WebSphere Application Server cluster.
3.2 JMS connectivity with IBM Integration Bus
Integration between remote clients and enterprise applications can be facilitated using IBM MessageSight and IBM Integration Bus (or the earlier WebSphere Message Broker). The JMS nodes in IBM Integration Bus V9 (and WebSphere Message Broker V8) can be configured to use the IBM MessageSight JMS classes. This enables IBM Integration Bus (and WebSphere Message Broker) message flows to interact directly with the appliance.
IBM Integration Bus also provides patterns that can be used to develop interactions between mobile devices and enterprise applications. Enterprise applications can connect directly to the IBM MessageSight appliance through the use of any of the following protocol APIs:
•JMS (using the IBM MessageSight JMS classes)
•MQTT (Java API)
•MQTT (C API)
An enterprise application can also use any of the WebSphere MQ APIs to communicate with the appliance through a queue manager. This requires appropriate configuration of the MQ Connectivity facility on the appliance.
3.2.1 JMS integration with WebSphere MQ as the JMS provider
This section describes a mechanism to integrate IBM MessageSight with WebSphere MQ as the JMS provider. This approach can also be used in an WebSphere Message Broker Version 8 environment. With IBM Integration Bus Version 9, IBM MessageSight is also available as a JMS provider.
This type of integration is most suitable in certain installations that are configured to communicate with IBM WebSphere MQ only. For example, existing systems might communicate with IBM WebSphere MQ over traditional WebSphere MQ API calls only. In such cases, the integration can only be through message queues between IBM MessageSight and IBM WebSphere Message Broker.
You can also implement an integration between IBM MessageSight and WebSphere MQ using message queues rather than JMS. To do this, a destination mapping rule exists on IBM MessageSight to map topics to queues, or topic subtrees to queues, and vice versa.
Figure 3-7 shows the integration of IBM MessageSight and WebSphere Message Broker V8.
Figure 3-7 End-to-end integration of IBM MessageSight and WebSphere Message Broker V8
An MQTT client (for example, a digital temperature sensor) connects to the IBM MessageSight appliance to publish messages /a/b/c. You must use a destination mapping rule in WebSphere MQ Connectivity to map the topic string /a/b/c published on the IBM MessageSight appliance to WebSphere MQ topic string /p/q/r. You can develop a message flow to read this topic string using the JMSInput node.
After the message flow reads the message on the topic, it transforms the message and forwards it to a JMSOutput node for a different topic on WebSphere MQ. Another destination mapping rule on IBM MessageSight maps this topic to a topic on IBM MessageSight. An MQTT client (for example, a hand-held device monitoring the temperature) that subscribes to this topic receives the publication as a response.
For more information about setting destination mapping rules, see the Configuring destination mapping rules topic in the IBM MessageSight Information Center:
Integration procedure
The following section describes a high-level procedure to implement an integration between IBM MessageSight and WebSphere Message Broker Version 8 using JMS:
1. Create an IBM MessageSight topic to WebSphere MQ topic destination mapping rule in IBM MessageSight. This rule takes publications from the MQTT client to IBM MessageSight and forwards them to IBM WebSphere MQ.
2. Create a WebSphere MQ topic to IBM MessageSight topic destination mapping rule in IBM MessageSight. This rule takes publications from the message broker (on IBM MessageSight) and forwards them to IBM MessageSight.
3. Create a bindings file for the JMS nodes in WebSphere Message Broker message flow.
Destination mapping rule from IBM MessageSight to WebSphere MQ
You can use the IBM MessageSight web UI or command-line interface (CLI) to create a destination mapping rule between IBM MessageSight and WebSphere MQ. The following list includes elements of a destination mapping rule. As an example, consider a mapping between an IBM MessageSight topic (/root/publication/temperature) and a WebSphere MQ queue (QLOCAL.TEMPERATURE):
•Destination mapping rule name
This is the name of the destination mapping rule that you want to create.
•Destination mapping rule type
The destination mapping rule type includes topic strings, topic subtrees, and queues.
•Source
Depending on the destination mapping rule type, the source can be set to the name of a queue, a topic string, or a topic subtree. In this example, the source is set to /root/publication/temperature.
•Destination
Depending on the destination mapping rule type, the destination can be set to the name of a queue, a topic string, or a topic subtree. In this example, the destination is set to QLOCAL.TEMPERATURE.
•Maximum messages
This is the maximum number of messages that can be buffered for a given destination mapping rule. This limit applies to destination mapping rules whose source is an IBM MessageSight topic or topic subtree. When this limit is exceeded, no more publications can happen to the topic on IBM MessageSight.
•Queue manager connection
This is the name of the queue manager connection that was created when you set up connectivity with WebSphere MQ queue manager. At least one such connection name must be provided.
If multiple connections are associated in the destination mapping rule, two consecutive messages can be sent to two different queue managers. However, in this case, the order of arrival of the messages is not guaranteed.
|
Tip: If better throughput is a requirement and message order is not strict, a destination mapping rule can be associated with multiple queue manager connections.
|
To set up this rule, you can either use the web UI or the CLI.
Creating a destination mapping rule using the web UI
To set up the destination mapping rule from the web UI, follow these steps:
1. Go to Messaging → MQ Connectivity.
2. Click the green plus (+) icon to add a new rule.
3. In the Edit Destination Mapping Rule window, enter details, as shown in Figure 3-8.
Figure 3-8 Destination mapping rule between IBM MessageSight and WebSphere MQ topic subtrees
4. The Rule Type field determines the type of mapping that you want to perform. In this example, we want the publications on IBM MessageSight to map to WebSphere MQ topic strings. Therefore, select MessageSight topic to MQ queue as the rule type.
Creating a destination mapping rule using CLI options
To set up a destination mapping rule using the command-line option, follow these steps:
1. Log in to the appliance using the ssh command.
Example 3-4 Creating a destination mapping rule with the CLI
Welcome to IBM MessageSight
5725-F96
Copyright 2012, 2013 IBM Corp. Licensed Materials - Property of IBM.
IBM and MessageSight are trademarks or registered trademarks of IBM, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies.
Console> imaserver create DestinationMappingRule "Name=ITSO_IMA_QM_MAP_01" "QueueManagerConnection=ITSO_IMA_CONN"
"RuleType=1" "Source=/root/publication/temperature" "Destination=QLOCAL.TEMPERATURE"
The requested configuration change has completed successfully.
3. The value of 1 for RuleType indicates that this is a mapping between the topic string on IBM MessageSight and the message queue on WebSphere MQ. Note that the command must be entered in a single line.
For a complete description with examples of command-line options for WebSphere MQ connectivity, see the MQ Connectivity commands topic on the IBM MessageSight Information Center:
For a complete description with examples of mapping, see the Configuring destination mapping rules topic on the IBM MessageSight Information Center:
Destination mapping rule from WebSphere MQ to IBM MessageSight
You can use the IBM MessageSight web UI or CLI to create a destination mapping rule between WebSphere MQ and IBM MessageSight.
Creating destination mapping rule with web UI
To set up the destination mapping rule between WebSphere MQ and IBM MessageSight, follow these steps:
1. From the web UI, go to Messaging → MQ Connectivity.
2. Click the plus (+) icon to add a new rule.
3. In the Edit Destination Mapping Rule window, enter details, as shown in Figure 3-9.
Figure 3-9 Destination mapping rule between WebSphere MQ and IBM MessageSight topic subtrees
Create a destination mapping rule using command-line options
The same rule can be set using the command-line option:
2. Issue the imaserver create command.
Example 3-5 Create destination mapping rule, WebSphere MQ to IBM MessageSight
Welcome to IBM MessageSight
5725-F96
Copyright 2012, 2013 IBM Corp. Licensed Materials - Property of IBM.
IBM and MessageSight are trademarks or registered trademarks of IBM, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies.
Console> imaserver create DestinationMappingRule "Name=ITSO_IMA_QM_MAP_02" "QueueManagerConnection=ITSO_IMA_CONN"
"RuleType=3" "Source=QLOCAL.TEMPERATURE.MONITOR" "Destination=/root/publication/temperatureMonitor"
The requested configuration change has completed successfully.
3. The value of 3 for RuleType indicates that this is a mapping between a message queue on WebSphere MQ and an IBM MessageSight topic. Note that the command must be entered in a single line.
For a complete description with examples of command-line options for MQ Connectivity, see the MQ Connectivity command topic on the IBM MessageSight Information Center:
For a complete description with examples of mapping, see the Configuring destination mapping rules topic on the IBM MessageSight Information Center:
Listing and showing destination mapping rules
After creating the destination mapping rules, you can list them and show details about individual mappings, using command-line options, as shown in Example 3-6. The type of the rules is highlighted to denote the type of mapping.
Example 3-6 Command-line option to list and show the destination mapping rules
Console> imaserver list DestinationMappingRule
ITSO_IMA_QM_MAP_01
ITSO_IMA_QM_MAP_02
Console> imaserver show DestinationMappingRule "Name=ITSO_IMA_QM_MAP_01"
Name = ITSO_IMA_QM_MAP_01
QueueManagerConnection = ITSO_IMA_CONN
RuleType = 1
Source = /root/publication/temperature
Destination = QLOCAL.TEMPERATURE
MaxMessages = 5000
Enabled = True
RetainedMessages = None
Console> imaserver show DestinationMappingRule "Name=ITSO_IMA_QM_MAP_02"
Name = ITSO_IMA_QM_MAP_02
QueueManagerConnection = ITSO_IMA_CONN
RuleType = 3
Source = QLOCAL.TEMPERATURE.MONITOR
Destination = /root/publication/temperature/monitor
MaxMessages = 5000
Enabled = True
RetainedMessages = None
Bindings file for JMS nodes
To create the bindings file for JMS nodes, use WebSphere MQ Explorer. When creating the bindings file, it is important to have the values in the JMSInput and JMSOutput nodes correspond to values in the bindings file.
Testing the integration
To test the integration, complete the following steps:
1. Connect an MQTT device to the IBM MessageSight appliance as the publishing device.
2. Connect another MQTT device as the subscribing device.
3. Set up a subscription to your topic string (for example, /root/publication/temperature/monitor) from the subscriber MQTT device.
4. Publish a message from your publishing MQTT device to the topic string (for example, /root/publication/temperature).
The destination mapping rule forwards the publication from the publishing MQTT device to WebSphere MQ. This publication is used by the WebSphere Message Broker Version 8 message flow as a JMS message. The message flow publishes its response back to WebSphere MQ, where another destination mapping rule forwards it to IBM MessageSight. This message is finally used by the MQTT subscribing device.
3.2.2 JMS integration with IBM MessageSight as the JMS provider
This section explains how back-end applications can interface to the “mobile world” using a combination of IBM Integration Bus V9 and the IBM MessageSight appliance. The IBM Integration Bus JMS nodes are configured to use the IBM MessageSight JMS classes.
The key differences between this approach and the approach described in 3.2.1, “JMS integration with WebSphere MQ as the JMS provider” on page 47, are shown in the following list:
•The IBM Integration Bus component connects directly to the IBM MessageSight appliance. Transiting a WebSphere MQ queue manager is not required. This is relevant where higher message loads must be supported, or a lower latency per transaction is required.
•The JMS provider is different (one uses the WebSphere MQ implementation of JMS, the other uses the IBM MessageSight JMS implementation).
Overview of the integration
IBM Integration Bus uses the JMSInput and JMSOutput nodes to receive JMS messages, and to produce messages. The two nodes support both the queuing and the publish/subscribe paradigms.
For example, an IBM Integration Bus message flow can receive a JMS message intended for a queue destination, process the message (such as store in a database and transform), and then publish the transformed message to a specified topic destination. Other JMS clients can subscribe to this published topic.
Figure 3-10 shows a high-level overview of the mobile applications communicating with the IBM Integration Bus. The mobile applications use MQTT to publish requests and subscribe to responses. The IBM Integration Bus message flows are using JMS to subscribe to requests and to publish responses. IBM MessageSight does the required protocol bridging between MQTT and JMS.
In this scenario, the mobile applications publish on the request topics and subscribe to the related response topics. The JMS nodes in the IBM Integration Bus message flows subscribe to the request topics and publish on the response topics.
Figure 3-10 High-level overview of mobile applications, IBM MessageSight, and IBM Integration Bus
For more information about message delivery and the mapping between MQTT and JMS, see the IBM MessageSight Information Center:
Integration details
The following steps are necessary to implement the integration between IBM MessageSight and the IBM Integration Bus:
1. A .bindings file is required by the IBM Integration Bus JMSInput and JMSOutput nodes. This bindings file must be created and saved in a directory to which the IBM Integration Bus message flows have access.
2. Configure the two IBM Integration Bus JMS nodes to use the bindings file (created in step 1), and point the JMS nodes at the IBM MessageSight JMS classes.
Creating a bindings file
No utilities are currently available to create this bindings file. There is no IBM MessageSight equivalent to the WebSphere MQ Explorer with the JMS Administered Objects feature. A sample of a bindings file is provided with the JMS SDK. You can edit this file with a suitable text editor.
For more information about using JMS applications with IBM MessageSight, see Creating administered objects in the IBM MessageSight Information Center:
|
Important: The name of the bindings file must be .bindings. Note the leading period in the name.
|
Example 3-7 depicts an example of a .bindings file. In this scenario, the .bindings file is saved in the C:JNDIJIMA-Sample Windows directory. The contents of this example .bindings file configure the following JMS-administered objects:
•A JMS Connection Factory named connFactory1. The attributes for this connection factory include the IP address of the JMS Server (the IBM MessageSight appliance) and the associated port (IBM MessageSight endpoint).
•A JMS topic for the request topic named testRequestTopic.
•A JMS topic for the response topic named testResponseTopic.
Example 3-7 JNDI .bindings example
connFactory1/ClassName=com.ibm.ima.jms.impl.ImaConnectionFactory
connFactory1/FactoryName=com.ibm.ima.jms.impl.ImaConnectionFactory
connFactory1/RefAddr/0/Encoding=String
connFactory1/RefAddr/0/Type=Port
connFactory1/RefAddr/0/Content=16105
connFactory1/RefAddr/1/Encoding=String
connFactory1/RefAddr/1/Type=Server
connFactory1/RefAddr/1/Content=9.12.5.184
connFactory1/RefAddr/2/Encoding=String
connFactory1/RefAddr/1/Type=ObjectType
connFactory1/RefAddr/2/Content=common
RequestTopic/ClassName=com.ibm.ima.jms.impl.ImaTopic
RequestTopic/FactoryName=com.ibm.ima.jms.impl.ImaTopic
RequestTopic/RefAddr/0/Encoding=String
RequestTopic/RefAddr/0/Type=Name
RequestTopic/RefAddr/0/Content=testRequestTopic
ResponseTopic/ClassName=com.ibm.ima.jms.impl.ImaTopic
ResponseTopic/FactoryName=com.ibm.ima.jms.impl.ImaTopic
ResponseTopic/RefAddr/0/Encoding=String
ResponseTopic/RefAddr/0/Type=Name
ResponseTopic/RefAddr/0/Content=testResponseTopic
Configuration for the use of IBM MessageSight JMS classes
Ensure that the JMS nodes in the IBM Integration Bus are using the JMS classes implemented for IBM MessageSight. This is done through the use of the mqsichangeproperties administration command.
Example 3-8 shows an example of the mqsichangeproperties command to configure the JMS nodes to use IBM MessageSight JMS classes. The shell variable $MQSI_INSTALL_PATH (used in the -v option in the example) points at the base installation directory for IBM Integration Bus. For example, this can point at /opt/ibm/mqsi on a Linux system.
You can place these Java archive (JAR) files in any suitable directory. They do not have to be in the IBM Integration Bus installation directory hierarchy.
Example 3-8 The mqsichangeproperties command
mqsichangeproperties ITSOBK2
-c JMSProviders
-o IBM_MessageSight
-n jarsURL
-v $MQSI_INSTALL_PATH/ImaClient/jms/lib
Verify that the response from the mqsichangeproperties command is:
BIP8071I: Successful command completion.
Verify that the JMS configuration of the integration node is changed appropriately.
Example 3-9 shows an example of the mqsireportproperties command to report on the configuration of JMS providers.
Example 3-9 mqsireportproperties command
mqsireportproperties ITSOBK2
-c JMSProviders
-o IBM_MessageSight
-r
The response returned should look similar to the following response:
JMSProviders
IBM_MessageSight
clientAckBatchSize=’0’
clientAckBatchTime=’0’
connectionFactoryName=’’
initialContextFactory=’’
jarsURL=’/opt/ibm/mqsi/ImaClient/jms/lib’
jmsAsyncExceptionHandling=’false’
jmsProviderXASupport=’true’
jndiBindingsLocation=’’
jndiEnvironmentParms=’default_none’
nativeLibs=’default_Path’
proprietaryAPIAttr1=’default_none’
proprietaryAPIAttr2=’default_none’
proprietaryAPIAttr3=’default_none’
proprietaryAPIAttr4=’default_none’
proprietaryAPIhandler=’default_none’
BIP8071I: Successful command completion
Configuring the IBM Integration Bus JMS nodes
This section explains the configuration of the JMSInput node and JMSOutput node used in the message flows.
Figure 3-11 on page 59 shows the overall IBM Integration Bus message flow, and where the JMS nodes are used in the flow.
Figure 3-11 JMS node usage in the IBM Integration Bus message flow
Figure 3-12 shows the Basic configuration of a JMSInput node. This input node is used in a publish/subscribe scenario. Therefore, the Subscription topic is selected. Note that the value, RequestTopic, is one of the administered objects created in the bindings file.
Figure 3-12 JMSInput node Basic configuration
Figure 3-13 shows the configuration of the JMS Connection tab for the JMSInput node. The following list shows the parameters included in this tab:
•The name of the JMS provider, IBM MessageSight
•The fact that the node is using a file system context
•The location of the .bindings file
•The name of the JMS Connection Factory administered object, connFactory1, that was created earlier in the .bindings file
Figure 3-13 JMSInput node properties showing configuration of the JMS connection
Figure 3-14 shows the Basic configuration of a JMSOutput node. This output node is used in a publish/subscribe scenario. Therefore, the Publication topic is selected. Note that the value, ResponseTopic, is one of the administered objects created in the bindings file.
The JMS Connection tab for the JMSOutput node is similar to the tab described for the JMSInput node in Figure 3-13.
Figure 3-14 JMSOutput node Basic configuration
3.3 Developing stand-alone applications using the IBM MessageSight JMS classes
This section describes the development of JMS publisher and subscriber applications using IBM MessageSight JMS.
Before commencing development of JMS applications for IBM MessageSight, ensure that you have access to the IBM MessageSight JMS Client Pack.
It is assumed that the reader is familiar with, and comfortable with, JMS concepts and terminology. It is important to remember that the IBM MessageSight appliance provides the functionality of a JMS broker (or middle-man).
|
Important: This section does not contain the complete code for the sample applications. In the following sections, the code snippets illustrate the relevant methods used for connecting, publishing messages to, and subscribing from, the IBM MessageSight appliance. You can download the complete code from the IBM Redbooks website. See Appendix D, “Additional material” on page 341 for the download instructions.
|
3.3.1 IBM MessageSight JMS Client Pack
You can download the JMS Client pack from the IBM developerWorks website:
The JAR files required for IBM MessageSight JMS are in the jms/lib directory. This directory must be included in your CLASSPATH.
For IBM MessageSight V1.0.0.1, there are five JARs in this directory:
•fscontext.jar
•imaclientjms.jar
•jms.jar
•jmssamples.jar
•providerutil.jar
The Javadoc for the IBM MessageSight JMS classes can be found in the jms/doc directory.
Additional sample codes are in the jms/samples directory.
3.3.2 IBM MessageSight JMS and JNDI
WebSphere MQ provides facilities by which Java Naming and Directory Interface (JNDI)-administered objects can be configured for the WebSphere MQ implementation of JMS. These facilities include:
•Use of the WebSphere MQ Explorer, specifically, the JMS Administered Objects folder. WebSphere MQ Explorer provides a user-friendly graphical approach to JNDI configuration.
•Use of the command-line utility, JMSAdmin.
The current release of IBM MessageSight JMS does not provide a tool or utility for configuring JNDI.
A sample .bindings file is supplied with the JMS Client Pack. This file shows the expected formats for the JNDI object configurations. Any text editor can be used to view and edit this file.
Additionally, a Java sample named JMSSampleAdmin.java is provided in the jms/samples directory. This sample program takes a configuration file as input and produces a required .bindings file. This sample application can also take a .bindings file as input, and produces a legible configuration file as output.
For more information about using JMS applications with IBM MessageSight, see Creating administered objects in the IBM MessageSight Information Center:
3.3.3 Message delivery in IBM MessageSight
This section provides information about how IBM MessageSight handles message delivery, and compares and explains message reliability and delivery performance when using JMS and MQTT.
IBM MessageSight enables JMS message acknowledgement to be disabled with the use of the DisableACK ConnectionFactory property. This type of publication is the fastest, but is also the least reliable. Use it only when occasional message loss can be tolerated. Message loss can occur if the publisher is disconnected, the server fails, or transient network issues occur.
For more information about message delivery in IBM MessageSight, see the IBM MessageSight Information Center:
3.3.4 A sample JMS publisher
This section describes the implementation of a sample message publisher using IBM MessageSight JMS. This sample application uses a properties file for configuration information.
One key aspect that this sample illustrates is the ability to reconnect to an alternative IBM MessageSight appliance if one fails. IBM MessageSight can be configured in a high availability (HA) configuration using a pair of appliances. However, the individual appliances in the HA configuration use unique network addresses. Therefore, a JMS client must be aware of both addresses to use this HA capability.
The application does not use a .bindings file, but creates the required administered objects internally within the sample application. It uses the provided configuration properties to perform this object creation.
The sample publisher application carries out the following steps:
1. Parse the command-line arguments and process the properties file.
2. Create a connection to the JMS server (the IBM MessageSight appliance).
3. Set the Client identifier for the connection. If a user name and password are supplied, these are used to establish the connection.
4. Create a session.
5. Create a publisher for the required topic.
6. Publish the required number of messages.
7. If the connection to the JMS server is broken while sending the messages, the application attempts to reconnect to any specified alternative addresses (for example, the second appliance in an HA pair).
8. The application stops when the required number of messages are published.
Example 3-10 shows the required Java imports for this publisher sample.
Example 3-10 Publisher Java imports
import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.DeliveryMode;
import javax.jms.JMSException;
import javax.jms.MessageProducer;
import javax.jms.Topic;
import javax.jms.Session;
import javax.jms.TextMessage;
import java.io.*;
import java.util.Properties;
import com.ibm.ima.jms.ImaJmsException;
import com.ibm.ima.jms.ImaJmsFactory;
import com.ibm.ima.jms.ImaJmsObject;
import com.ibm.ima.jms.ImaProperties;
Example 3-11 shows the configuration file used by the JMS Publisher application.
Example 3-11 JMS publisher configuration file
#
# IBM MessageSight sample JMS Publisher
# Configuration file
#
ima.servers=192.168.121.135, 192.168.121.227
ima.port=16102
client.id=ITSOPUB01
topic=ITSO/Sample/Topic01
msg.count=10000
msg.body="This is an IMA JMS test message"
msg.rate=500
msg.pers=false
#
disable.ack=false
#
# Username and Password are used for additional security
#
#user.name=testuser
#user.passwd=testpassword
Example 3-12 shows the creation of the JNDI-administered objects required by the publisher application.
Example 3-12 Create administered objects
/**
* Get connection factory administered object.
*
* @return ConnectionFactory object.
*
* Note: In production applications, this method would retrieve a
* ConnectionFactory object from a JNDI repository.
*/
public static ConnectionFactory getCF() throws JMSException
{
ConnectionFactory cf = ImaJmsFactory.createConnectionFactory();
/*
* NOTE: For high availability configurations, the serverList
* must contain the list of IBM MessageSight server host names or
* IP addresses so that the client
* can attempt to connect to alternative hosts if connection
* (or reconnection) to the primary fails.
*/
((ImaProperties) cf).put("Server", serverList);
((ImaProperties) cf).put("Port", serverPort);
if (disableACK) {
((ImaProperties) cf).put("DisableACK", true);
System.err.println("ACKs disabled in ConnectionFactory!");
}
/*
* After setting properties on an administered object, it is a
* best practice to run the validate() method to assure all
* specified properties are recognized by the IBM MessageSight
* JMS client.
*/
ImaJmsException errors[] = ((ImaProperties) cf).validate(true);
if (errors != null)
throw new RuntimeException("Invalid properties provided for the connection factory.");
return cf;
}
/**
* Create topic administered object.
*
* @return Topic object.
*
* Note: In production applications, this method would retrieve a
* Topic object from a JNDI repository.
*/
public static Topic getTopic() throws JMSException
{
Topic dest = ImaJmsFactory.createTopic(topicName);
return dest;
}
}
Example 3-13 shows the connection being established to the JMS server (the IBM MessageSight appliance).
Example 3-13 Establish connection
/**
* Establish a connection to the server. Connection attempts
* are retried until successful or until the
* specified timeout for retries is exceeded.
*/
public static boolean doConnect() {
int connattempts = 1;
boolean connected = false;
long starttime = System.currentTimeMillis();
long currenttime = starttime;
/*
* Try for up to connectTimeout milliseconds to connect.
*/
while (!connected && ((currenttime - starttime) < connectTimeout)) {
try { Thread.sleep(5000); } catch (InterruptedException iex) {}
if (debug) System.out.println("Attempting to connect to server (attempt " + connattempts + ").");
connected = connect();
connattempts++;
currenttime = System.currentTimeMillis();
}
return connected;
}
/**
* Connect to the server
*
* @return Success (true) or failure (false) of the attempt to connect.
*/
public static boolean connect()
{
/*
* Create connection factory and connection
*/
try {
fact = getCF();
if (userPass != null)
conn = fact.createConnection(userName, userPass);
else
conn = fact.createConnection();
conn.setClientID(clientID);
/*
* Check that we are using IBM MessageSight JMS
* administered objects before calling
* provider specific check on property values.
*/
if (fact instanceof ImaProperties)
{
/*
* For high availability, the connection factory stores the
* list of IBM MessageSight server host names or
* IP addresses. Once connected, the connection object
* contains only the host name or IP address
* to which the connection is established.
*/
System.out.println("Connected to " +
((ImaProperties)conn).getString("Server"));
}
/*
* Connection has succeeded. Return true.
*/
return true;
} catch (JMSException jmse) {
System.err.println(jmse.getMessage());
/*
* Connection has failed. Return false.
*/
return false;
}
}
Example 3-14 shows the publication of the messages. Each message is appended with a sequence number. Appropriate delays are calculated to maintain the requested message rate, messages per second. If the connection is broken during message publication, attempts are made to re-establish the connection to a specified JMS server (appliance) and continue publishing messages until all requested messages are sent.
Example 3-14 Publish messages
/**
* Publish messages to specified Topic.
*/
public static void doSend() throws JMSException
{
Session sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
System.out.println("Client ID is: " + conn.getClientID());
Topic haTopic = getTopic();
// Create the message producer
MessageProducer prod = sess.createProducer(haTopic);
// Set the required message persistence.
if (msgPers) {
prod.setDeliveryMode(DeliveryMode.PERSISTENT);
System.out.println("Using PERSISTENT messages");
} else {
prod.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
System.out.println("Using NON-PERSISTENT messages");
}
conn.start();
long startTime = System.currentTimeMillis();
TextMessage tmsg;
int msgcnt = 0;
while ((sendcount < count) && !senddone) {
try {
tmsg = sess.createTextMessage(msgtext+" - "+sendcount);
if (debug)
System.out.println("Sending message: " + sendcount + " " + ImaJmsObject.toString(tmsg, "b"));
prod.send(tmsg);
sendcount++;
msgcnt++;
if (sendcount == count)
senddone = true;
} catch (Exception ex) {
ex.printStackTrace(System.err);
/*
* If an exception is thrown while messages are sent, check to see whether the connection
* has closed. If it has closed, then attempt to reconnect and continue sending.
*/
if (!senddone && isConnClosed()) {
reconnectAndContinueSending();
} else {
/*
* If all messages have already been sent or if the connection remains active despite
* the exception, the error should not be addressed with an attempt to reconnect.
* Set senddone to true in order to exit this sample application.
*/
senddone = true;
}
break;
}
// Calculate required delay (sleep) to achieve the
// requested message rate.
long currTime = System.currentTimeMillis();
double elapsed = (double) (currTime - startTime);
double projected = ((double) msgcnt / (double) msgsPerSecond) * 1000.0;
if (elapsed < projected) {
double sleepInterval = projected - elapsed;
try {
Thread.sleep((long) sleepInterval);
} catch (InterruptedException e) {
}
}
}
}
Example 3-15 shows code to detect that the connection is lost, and to attempt to re-establish the connection.
Example 3-15 Broken connection detection and connection re-establishment
/**
* Check to see if connection is closed.
*
* When the IBM MessageSight JMS client detects that the connection
* to the server has been broken, it marks the connection object closed.
*
* @return True if connection is closed or if the connection object is null, false otherwise.
*/
public static boolean isConnClosed() {
if (conn != null) {
/*
* Check the IBM MessageSight JMS isClosed connection property
* to determine whether the connection state is closed.
* This mechanism for checking whether the connection is closed
* is a provider-specific feature of the IBM MessageSight
* JMS client. So check first that the IBM MessageSight JMS
* client is being used.
*/
if (conn instanceof ImaProperties) {
return ((ImaProperties) conn).getBoolean("isClosed", false);
} else {
/*
* We cannot determine whether the connection is closed so return false.
*/
return false;
}
} else {
return true;
}
}
/**
* Reconnect and continue sending messages.
*/
public static void reconnectAndContinueSending() throws JMSException {
System.out.println("Connection is closed. Attempting to reconnect and continue sending.");
boolean reconnected = doConnect();
if (reconnected) {
doSend();
} else {
/*
* If we fail to reconnect in a timely manner, then set senddone
* to true in order to exit from this sample application.
*/
System.err.println("Timed out while attempting to reconnect to the server.");
senddone = true;
}
}
3.3.5 A sample JMS subscriber
This section describes the implementation of a sample message subscriber using IBM MessageSight JMS. This sample application uses a properties file for configuration information.
As for the publisher application, this sample illustrates the ability to reconnect to an alternative IBM MessageSight appliance if one fails. IBM MessageSight can be configured in an HA configuration using a pair of appliances. However, the individual appliances in the HA configuration use unique network addresses. Therefore, a JMS client must be aware of both addresses to use this HA capability.
The application does not use a .bindings file, but creates the required administered objects internally within the sample application. It uses the provided configuration properties for object creation.
The sample subscriber application carries out the following sequence of steps:
1. Parse the command-line arguments and process the properties file.
2. Create a connection to the JMS server (the IBM MessageSight appliance).
3. Set the Client identifier for the connection. If a user name and password are supplied, these are used to establish the connection.
4. Create a session.
5. Create a subscriber for the required topic.
6. Receive the required number of messages.
7. If the connection to the JMS server is broken while receiving the messages, the application attempts to reconnect to any specified alternative addresses (for example, the second appliance in an HA pair).
8. The application stops when the required number of messages are received.
|
Tip: This subscriber application uses synchronous message reception. Asynchronous message reception can also be implemented with the use of a message listener.
|
Example 3-16 shows the required Java imports for this subscriber sample.
Example 3-16 Subscriber Java imports
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.Properties;
import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageConsumer;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.jms.Topic;
import com.ibm.ima.jms.ImaJmsException;
import com.ibm.ima.jms.ImaJmsFactory;
import com.ibm.ima.jms.ImaProperties;
The steps to create the required administered objects (connectionFactory and Topic), and to establish a connection to the JMS server (IBM MessageSight appliance), are identical to the sample code snippets shown for the publisher sample in 3.3.4, “A sample JMS publisher” on page 63.
Example 3-17 shows the configuration file used by the JMS subscriber application.
Example 3-17 JMS subscriber configuration file
# IBM MessageSight sample JMS Subscriber
# Configuration file
#
ima.servers=192.168.121.135, 192.168.121.227
ima.port=16102
client.id=ITSOSUBS01
topic=ITSO/Sample/Topic01
msg.count=5000
# Receive timeout is in seconds - wait to receive first message.
rcv.timeout=15
# Durable subscription name
durasubs.name=DURASUBS01
#
# Username and Password are used for additional security
#
#user.name=testuser
#user.passwd=testpassword
Example 3-18 shows the reception of the messages. This message subscriber sample application can, optionally, use a durable subscription. If the connection is broken during message reception, attempts are made to re-establish the connection to a specified JMS server (appliance) and continue receiving messages until all requested messages have been received.
Example 3-18 Message reception
/**
* Receive messages via durable subscription.
*/
public void doReceive() throws JMSException {
// Create a session
sess = conn.createSession(false, Session.AUTO_ACKNOWLEDGE);
Topic haTopic = getTopic();
if (duraSubsName != null) {
// Create a Durable Subscriber
cons = sess.createDurableSubscriber(haTopic, duraSubsName);
System.out.println("Created a Durable Subscription named "+duraSubsName);
} else {
// Create a standard message consumer
cons = sess.createConsumer(haTopic);
}
conn.start();
int i, firstmsg;
i = firstmsg = recvcount;
do {
int timeout = 10000;
if (i == firstmsg)
timeout = receiveTimeout;
try {
Message msg = cons.receive(timeout);
if (msg == null) {
throw new JMSException("Timeout in receive message: " + i);
} else {
synchronized (IMAJMSSubscriber.class) {
recvcount++;
lastrecvtime = System.currentTimeMillis();
}
if (msg instanceof TextMessage) {
TextMessage tmsg = (TextMessage) msg;
System.out.println("Received message " + i + ": " + tmsg.getText());
} else {
System.out.println("Received message " + i);
}
i++;
}
} catch (Exception ex) {
ex.printStackTrace(System.err);
/*
* If an exception is thrown while messages are received, check to
* see whether the connection has closed.
* If it has closed, then attempt to reconnect and continue receiving.
*/
if (!recvdone && isConnClosed()) {
this.reconnectAndContinueReceiving();
} else {
synchronized (IMAJMSSubscriber.class) {
/*
* If all messages have already been received or if the
* connection remains active despite the exception,
* the error should not be addressed with an attempt to reconnect.
* Set recvdone to true in order to exit this sample application.
*/
recvdone = true;
}
}
break;
}
} while (recvcount < count);
synchronized (IMAJMSSubscriber.class) {
recvdone = true;
if (recvcount < count)
System.err.println("doReceive: Not all messages were received: " + recvcount);
}
// Close off cleanly, especially if a DurableSubscriber was used.
cons.close();
if (duraSubsName != null)
sess.unsubscribe(duraSubsName);
}
Similar to the publisher sample application, the subscriber application detects a broken connection to the JMS server (appliance) and attempts to re-establish the connection.
3.4 IBM MessageSight resource adapter for Java Platform Enterprise Edition applications
The IBM MessageSight resource adapter is a new feature provided in version 1.1 that enables direct connection from IBM MessageSight to WebSphere Application Server. This simplified Java Platform, Enterprise Edition (Java EE) architecture supports faster configuration, easier monitoring, and easier scaling of Java EE solutions. The IBM MessageSight resource adapter supports inbound and outbound communication.
IBM MessageSight provides a resource adapter that enables Java EE applications to communicate directly with IBM MessageSight by using the
Java EE Connector Architecture (JCA) V1.6 interfaces. In addition to the benefits listed in the previous paragraph, this Java EE architecture lowers
operating costs.
Java EE Connector Architecture (JCA) V1.6 interfaces. In addition to the benefits listed in the previous paragraph, this Java EE architecture lowers
operating costs.
The IBM MessageSight resource adapter supports two types of communication between an application and IBM MessageSight:
•Inbound communication
A JMS message that arrives at a JMS destination is delivered to a message-driven bean (MDB), which processes the message asynchronously.
•Outbound communication
An application starts a connection to IBM MessageSight, and then sends JMS messages to JMS destinations, and receives JMS messages from JMS destinations in a synchronous manner.
The IBM MessageSight resource adapter is supported on WebSphere Application Server Version 8.0 or later. For more detail about IBM MessageSight resource adapters, see the IBM MessageSight Information Center:
In IBM MessageSight V1.1, you can configure durable and non-durable topic subscriptions to be shared by using the IBM MessageSight JMS client. In a non-shared subscription, each consumer of a particular topic receives a copy of all of the messages that are published to that topic string. In a shared subscription, each message is delivered to only one of the consumers for that subscription. This is similar to message sharing on a multi-consumer queue.
Unshared durable subscriptions must have a client ID specified. The client ID specifies the namespace for the subscription name. Unshared non-durable subscriptions do not require a client ID to be specified.
Shared subscriptions can be bound to a client ID, or can exist within a global namespace. If a client ID is specified, the subscription is bound to only that
client ID. If no client ID is specified, the global namespace is used. By using a global namespace, it is possible to share a subscription between multiple connections. This configuration can be used to allow load balancing in an application server cluster.
client ID. If no client ID is specified, the global namespace is used. By using a global namespace, it is possible to share a subscription between multiple connections. This configuration can be used to allow load balancing in an application server cluster.
For more detail about IBM MessageSight shared subscriptions, see the IBM MessageSight Information Center:
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.