HP NonStop Message Queue 1.0 User Guide HP Part Number: 698926-002 Published: March 2014 Edition: J06.15 and subsequent J-series RVUs and H06.26 and subsequent H-series RVUs.
© Copyright 2013, 2014 Hewlett-Packard Development Company, L.P. Legal Notice Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
Contents About This Document.....................................................................................5 Supported Release Version Updates (RVUs)..................................................................................5 Intended Audience....................................................................................................................5 New and Changed Information..................................................................................................
A Sample applications.................................................................................50 Pre-requisites..........................................................................................................................50 Dependent libraries for the sample applications..........................................................................50 Building the sample applications..............................................................................................
About This Document This manual provides information on NonStop Message Queue (NSMQ). It also contains: • Features of NSMQ • How to install and configure NSMQ • How to run the sample application • Integrating NSMQ with other products Supported Release Version Updates (RVUs) This manual supports J06.15 and all subsequent J-series RVUs, and H06.26 and all subsequent H-series RVUs, until otherwise indicated by its replacement publications.
“References” (page 64) General references provided for more useful information. “Glossary” (page 65) Glossary of terms used in this manual. Notation Conventions Bold Type Bold type within text indicates terms defined in the Glossary. For example: abstract class Computer Type Computer type letters within text indicate keywords, reserved words, command names, class names, and method names; enter these items exactly as shown. For example: myfile.
Punctuation Parentheses, commas, equal signs, and other symbols not previously described must be entered as shown. For example: -D propertyName=newValue Item Spacing Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or comma. If there is no space between two items, spaces are not permitted. In the following example, spaces are not permitted before or after the period: subvolume-name.
1 Introduction to NSMQ This chapter provides an introduction to NonStop Message Queue (NSMQ) 1.0 and discusses its architecture. It also gives an overview of Java Messaging Service (JMS), ActiveMQ, and the NonStop products used by NSMQ. To understand NSMQ, it is necessary to have a prior knowledge of these products. NonStop Message Queue (NSMQ) 1.0 is a JMS 1.1 compliant messaging system on NonStop.
For more information about CIP, see the Cluster I/O Protocols (CIP) Configuration and Management Manual. SQL/MX database NSMQ uses SQL/MX database for persisting messages and achieving fault tolerance. For more information, see “Fault tolerance” (page 12). For more information, see the NonStop SQL/MX documentation. Features of NSMQ The features of NSMQ are as follows: • Clustering — A mechanism where you configure multiple brokers to form a cluster.
Figure 1 Architecture of NSMQ Producer luster I/O Proto op C col t S n s No B1 Bn B2 SQL/MX Database B3 tcp :// < Ho stn a me IP Address>: o. N rt Consumer B1 ...... Bn : Brokers SQL/MX database: SQL/MX database is used as a data store for storing messages. The brokers connect to the database to store and retrieve messages. Cluster: The cluster is made up of network of brokers and is used for handling additional load.
is active and slave instance is on stand by. When the master instance fails, the slave instance takes over the responsibilities of the master (page 11). Cluster I/O Protocols (CIP) subsystem: Every broker in the cluster starts a transport connector configured for parallel I/O using the CIP subsystem to listen on the same IP address and port. All client applications connect to this port. This subsystem facilitates load balancing of the connections across all the brokers.
Figure 3 (page 12) represents a cluster of brokers. Figure 3 Cluster of brokers Cluster I/O Pr ot top S oc on B1 B1 Local Host: 6161 B1’ B2 Local Host: 6162 B2’ s ol N Producer Bn B2 SQL/MX Database os tn a B3 me I >: P A d dress N < :// o. > tc p H or
Let us consider two brokers, Broker1 and Broker2, set up to form a cluster. These brokers are connected locally by a network connector. The clients (producers and consumers) connect to the cluster via the CIP subsystem. Figure 4 Message flow in a cluster 1. Send Producer 5. Send Broker 1 3. Acknowledge 10. Send Broker 2 7. Acknowledge 4. Fetch 11. Acknowledge 9. Fetch 6. Store 2. Store Consumer 12. Update 8.
2 Installation and configuration This chapter describes the steps to install NSMQ, configure clusters and brokers, and uninstall NSMQ. Pre-requisites Before getting started, ensure that you have the following software installed: Table 1 Software to be installed on the NonStop system Software For more information: SQL/MX database 3.2.1 See the SQL/MX 3.2.1 Installation and Upgrade Guide. JDBC/MX Type 2 driver 3.2 or later See the JDBC Type 2 Driver Programmer's Reference for SQL/MX Release 3.2.
NOTE: HP strongly recommends that you exit all Windows applications before running the IPSetup program. You can click Cancel to exit the IPSetup program at anytime during the setup. 5. Click Next. The Software License Agreement screen appears.
6. Read the License Agreement, accept the terms of the agreement by selecting I agree to the above conditions, and click Next. The Placement Options screen appears.
7. Select one of the following as a target platform for your IP software: a. TNS/E for H-series and J-series. b. Workstation to install the IP on your workstation. c. If you want to launch the DSM/SCM planner interface after completing the IPSetup program, select the Use DSM/SCM to complete installation on the host check box. 8. Click Next. The Product Selection screen appears.
9. From the Available Products list, select NonStop Message Queue and click Add-> to move it to the Selected Products list. 10. Click Next. The Host Information screen appears.
11. Perform the following steps to log on to the host: a. In the Host name box, select from the list or type the IP address of the host where you want to place the selected product. b. Enter the user name and password. c. Select the communication mode. NOTE: Starting with T0316H01^AAK (version 4.1.00.0), IPSetup supports two modes of communication: Telnet and Secure SHell (SSH). To use the SSH mode of communication, ensure that the SSH server is configured correctly and is running on the NonStop server.
NOTE: • HP recommends that you do not change the default service value unless it is required. • The following are the default port numbers: ◦ SSH port — 22 ◦ Telnet port — 23 ◦ FTP port — 21 For additional port numbers, consult the system administrator. d. Click Next. The Host Target Settings screen appears. 12. Perform one of the following: a. Accept the default location for the work subvolume and the subvolume where the existing files will be backed up from the work subvolume. b.
13. Verify the location where the product files will be placed on the Host system and click Next. The Placement Manifest screen appears.
14. Verify the details displayed on the Placement Manifest screen and click Next. If you have selected the Back up existing host files to check box in the Host Target Settings screen, IPSetup backs up any existing files to the backup subvolume. If you do not select this check box, IPSetup purges any files in the work subvolume or in the distribution subvolume (DSV) (and installation subvolume (ISV) for IPs) with names identical to files that are about to be placed.
After the installation files are transferred, the Placement Complete screen appears.
15. Click Finish to complete the IPSetup program. NOTE: To view the readme on closing the program, select the View the Readme File check box. The IPSetup program completes and opens the readme.txt file. The T0975PAX file is located in the volume which is specified during the IPsetup. For example, the Host File Placement screen shot displays $AUDIT as the volume. So, the IPSetup places the T0975PAX file in the $AUDIT.E0975H01 location.
conf contents.txt versions.txt To run the setup script, perform the following steps: 1. Log on to the NonStop system. 2. Go to the location where the setup script is located and run the script. OSS> .
6. If you entered y to the Do you want to enable the SQL/MX persistence (n or [y]): question, the installation continues and you are prompted to enter the schema details. Enter the catalog name to be used : This is the catalog where you want to create the schema. Enter the schema name to be used : This is the schema to be created for the specified catalog. Do you want to create the catalog and schema?, Enter (y or [n]): Type y and press Enter if you want to create the new catalog and schema.
ALTER SERVER BRK1-M, PROGRAM /nssjava/jdk170_h70/bin/oss64/java ALTER SERVER BRK1-S, PROGRAM /nssjava/jdk170_h70/bin/oss64/java The above lines sets the JAVA program of the broker BRK1.
2. Run the command: OSS> ./uninstall 3. You are prompted with the following question: Do you want to proceed with the un-installation (n or [y]): 4. Enter y. You are prompted for the directory where NSMQ is installed. Enter the directory of NSMQ installation: NOTE: Before you uninstall NSMQ, stop all the running instances of NSMQ and remove all the clusters (page 30). The uninstall program may not remove all the files from the installation directory.
Adding a broker to a cluster After creating a cluster, you can add brokers to the cluster. You can configure any number of brokers within a cluster. 1. In the main menu, type 3 and press Enter. 2. You are prompted with the following questions. Enter the appropriate values. Enter the directory of NSMQ installation [/usr/tandem/nsmq] : This is the path where NSMQ is installed on your NonStop system. If there are any existing clusters, their names are displayed. Enter the name of the cluster [NSMQ].
3. Enter y. You are prompted with the following questions. Enter the appropriate values. Enter the directory of NSMQ installation [/usr/tandem/nsmq]: This is the path where NSMQ is installed on your NonStop system. If there are any existing clusters, their names are displayed. Enter the name of the cluster [NSMQ]. (Maximum 4 alpha-numeric characters) : This is the cluster from which you want to remove the broker. If there are any brokers existing within the cluster, the broker names are displayed.
3 Managing NSMQ This chapter describes how to manage NSMQ. The subsequent sections describe how to start, stop, check the status of a cluster or a broker, and the management operations and commands that can be performed in NSMQ. Starting/Stopping a cluster/broker You can start or stop a cluster or broker by using the scripts available in NSMQ. NSMQ provides two scripts in the form .sh and .sh.
1. 2. Log on to NSMQ. Go to //bin directory. The bin folder contains the script in the form of .sh. 3. Run the following command: .sh status This displays the status of the broker.
Table 2 Management operations (continued) NSMQ Management Object (Mbean) Operations Connection Connector Queue Description NSMQ Support addTopic(String name) Adds a topic destination to the broker. Yes addQueue(String name) Adds a queue destination to the broker. Yes removeTopic(String name) Removes a topic destination from the broker. Yes removeQueue(String name) Removes a queue destination from the broker.
Table 2 Management operations (continued) NSMQ Management Object (Mbean) Operations Description NSMQ Support copyMessageTo(String messageId, String destinationName) Copies a message, with the given JMS message ID, to the specified destination. Yes copyMatchingMessagesTo(String selector, String destinationName) Copies messages to the specified destination based on an SQL-92 selection on the message headers or XPATH on the body.
Table 2 Management operations (continued) NSMQ Management Object (Mbean) Operations Description NSMQ Support browseMessages(String p1) A list of all messages in the destination based on an SQL-92 selection on the message headers or XPATH on the body. No sendTextMessage(String body) Sends a text message to the destination. Yes sendTextMessage(String body, String user, Sends a text message to a String password) password-protected destination. Yes destroy() Destroys the specified subscription.
In addition to this, you can manage a single instance of broker through command line utility on NonStop systems for the following tasks: • Browse • Query • Purge NOTE: To use these commands, JMX must be enabled for the broker. By default, creating a broker in NSMQ enables JMX. If you have accidentally or intentionally disabled JMX, you must enable it before using these commands. Browsing a specified destination In NSMQ, queues and topics represent destinations.
Figure 5 Browse command The browse command can also be executed with various options. Each option filters the messages before displaying them. The options and their descriptions are shown in Table 3: Table 3 Browse options Usage: {broker-name}.sh browse Description {broker-name}.sh browse Prints the message header, custom message header, and message body of all messages in the specified queue or topic. {broker-name}.
Table 3 Browse options (continued) Usage: {broker-name}.sh browse Description {broker-name}.sh browse --user Prints the message header, custom message header, and message body of all messages in the queue or topic, using --password the user name and password queried. {broker-name}.sh browse --user --password --factory rg.apache.activemq.ActiveMQConnectionFactory --passwordFactory org.apache.activemq.
Figure 6 Query command The query command can also be executed with various options. Each option filters and displays the attributes based on the condition.
Table 4 Query options Usage: {broker-name}.sh query Description {broker-name}.sh query Prints all the attributes of all registered objects queues, topics, connections, and so on. {broker-name}.sh query -QQueue=QUEUE.IN Prints all the attributes of the queue whose destination name is QUEUE.IN. {broker-name}.sh query -QTopic=* Prints all the attributes of all registered topics. {broker-name}.
Figure 7 Purge command The purge command can also be executed with options to purge messages based on filters. The options and their descriptions are shown in Table 5: Table 5 Purge options Usage: {broker-name}.sh purge Description {broker-name}.sh purge FOO.BAR Deletes all the messages in queue FOO.BAR. {broker-name}.sh purge --msgsel "JMSMessageID='*:10',JMSPriority>5" QUEUE.* Deletes all the messages in the destinations that: • matches QUEUE.
4 Security This chapter describes the various security methods implemented in NSMQ. Security in NSMQ consists of: • Authentication • Authorization • Secure Socket Layer (SSL) Authentication The authentication between the brokers and producers and consumers is implemented with the combination of username and password while creating the connection.
CLASSPATH and uses it. The NSMQ default configuration provides user and group configuration using plain-text properties file. For more information on JAAS, see http://docs.oracle.com/javase/7/docs/technotes/guides/ security/jaas/JAASRefGuide.html. Perform the following steps to configure JAAS, considering you have a custom JAAS implementation for your Radius or LDAP server: 1. Change the activemqNonPersistent.template and activemqPersistent.
Secure Socket Layer NSMQ broker also provides security using Secure Socket Layer (SSL) protocol. Enabling SSL at the NSMQ broker level provides: • Privacy – Messages are encrypted using a secret key, thus preventing it from being hacked to read messages. • Message Integrity – Messages are digitally signed, ensuring that they cannot be tampered. • Authentication – The identity of the broker is authenticated.
Continue with NSMQ installation. • • • Note down the LISTEN_HOST and LISTEN_PORT properties' values from the .rsp in the /bin folder after cluster creation where, ◦ LISTEN_HOST is the value entered during cluster creation for the IP address on which NSMQ must listen for connections. ◦ LISTEN_PORT is the value entered during cluster creation for the port number on which NSMQ must listen for connections. Before starting the brokers, modify the activemq.
5 Integration This chapter describes how NSMQ can be integrated with NSASJ and JTA-TMF applications. Integrating NSMQ with NSASJ NSMQ integrates with NSASJ using resource adapters specified as RAR (Resource Adapter Archive file). This RAR file is located in the /lib directory. The integration includes inbound messages to be handled by Message Driven Beans (MDB) and outbound messages published by state less or state full Enterprise Java Beans (EJB).
7. Use the following annotations in MDB to use NSMQ as the messaging infrastructure for NSASJ: • @MessageDriven(name="QueueSampleServiceMDB", activationConfig = { @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.
• NSXARM debug can be initiated by setting the environment variable > export XARMDBG=yes • Audit option can be enabled by specifying the audit file location in the default.xarm.properties file. Configuring the JTA-TMF application Set the _RLD_LIB_PATH to point to the /lib/tmf/ directory where the libxarml.so file is present. Ensure that the file has execute permission. For example, export _RLD_LIB_PATH=:/usr/lib Running the JTA-TMF application 1. 2.
JTS or some other transaction monitor facility may be used to combine a session’s transaction with transactions on other resources (databases, other JMS sessions, and so on). Since Java distributed transactions are controlled via the JTA transaction demarcation API, use of the session’s commit and rollback methods in this context throw a JMS TransactionInProgressException.
A Sample applications The NSMQ package contains the following Spring sample applications for your reference and can help you get started with NSMQ. • jmsinvoker: This sample demonstrates the usage of Spring's feature of using JMS to host business logic services. • jmstemplate: This sample demonstrates the usage of the Spring class org.springframework.jms.core.JmsTemplate. • messagelistener: This sample demonstrates the usage of Spring's MessageListener container feature.
$ANT_HOME/bin/ant jar where $ANT_HOME is the location where Apache ANT is installed. This command compiles and create the jar file. Running the sample applications Before running the samples, modify the brokerURL property of the connectionFactory bean in the Spring Application Context configuration files to reference to a running NSMQ broker instance. Table 6 Configuration property for the samples Sample application jmsinvoker Configuration files to be modified clientApplicationContext.
B Use cases Being JMS compliant, NSMQ can be used from servlets and JSPs, Pathway server classes, and other Java products like NonStop Server for Java Server Pages (NSJSP). This section describes the following use case scenarios: • “Using JMS from servlets and JSPs” (page 52) • “Using JMS from Pathway Server Classes” (page 56) Using JMS from servlets and JSPs This section illustrates with a sample how JMS is used from servlets and JSPs.
4. Place the servlets-jsp.war file in the webapps folder of NSJSP or Tomcat installation directory. Running the application 1. 2. Start the NSJSP server or Tomcat server. Open the browser and enter the URL “http://localhost:8080/servlets-jsp/index.html”. The NSMQ servlet/JSP Examples page appears. 3. Click on "servlet samples for NSMQ" or "JSP samples for NSMQ" and follow the onscreen instructions to send and receive messages.
Figure 9 NSMQ JSP send messages 54 Use cases
Figure 10 NSMQ JSP message status Using JMS from servlets and JSPs 55
Figure 11 NSMQ JSP receive messages Using JMS from Pathway Server Classes This example demonstrates the usage of NSMQ in a Client-Server environment on NonStop in the following scenarios: • Standalone Java server and its client • TS/MP server class and its client NOTE: NSMQ is agnostic of TMF and only supports JTA transactions. Any JMS operation in the NonStop TS/MP server class or a NonStop standalone server is unaware of the TMF transaction context present during its execution.
• Environment variable JAVA_HOME must be set to NSJ installation directory • Modify the jndi.properties file to point the URL to a valid NSMQ broker. The key to modify is java.naming.provider.url. Building the Java Archive (JAR) file To generate the JAR file: 1. Edit the /samples/pway-samples/build.xml file. Change the jtoolkit.dir property to point to a valid JToolkit/lib directory. 2.
6. Modify the SERVERCLASS-SETUP file to change the values of CWD, ARGLIST, JAVA_HOME, PROGRAM, and VOLUME parameters. You must change the directory values to properly point to the nsmq-pway.jar directory, activemq-all-5.6.0.jar, JToolkit jar, jndi.properties, JAVA_HOME and java program files. 7. Copy and paste these contents to the PATHCOM session you opened in step 4. A server-class by name NSMQSAMPLE will be setup. Start the server-class using the following command: START SERVER NSMQSAMPLE 8. 9.
C Configurable elements in NSMQ The following table lists the configurable elements supported or unsupported by NSMQ: Table 7 NSMQ support for configurable elements Configuration Element Description NSMQ Support adminView Returns the administration view of the broker and used Yes to create and remove resources such as queues and topics.
Table 7 NSMQ support for configurable elements (continued) Configuration Element Description NSMQ Support plugins The broker plugins to install for security authentication and authorization.
D FAQ/Common problems and error conditions Listed below are some of the frequently asked questions or common problems and error conditions faced by users while using NSMQ. This list may contain some of the problems faced in ActiveMQ. For a complete list of commonly asked questions in ActiveMQ, see the ActiveMQ FAQ. 1.
9. What happens if a broker is removed from a cluster? If a broker is removed, some messages may not be dispatched and these may be lost. The other brokers, producers, consumers, lose communication with the removed broker. 10. I am having problems sending messages to clients in another time zone. Time zone between the client and the server must be in sync for proper message delivery. If there is no synchronization in time zone between client and server, you may face problems with message delivery. 11.
sufficient time for the connection by setting the wireFormat.maxInactivityDurationInitalDelay property to a longer duration. 16. How can I disable JMX? You can disable JMX either before or after installing NSMQ. However, HP does not recommended this as none of the administrative tools will work if JMX is disabled. To disable JMX prior to installation: a. Open the activemqNonPersistent.template and activemqPersistent.template files located at /nsmq/T0975H01. b.
E References The following references are useful for additional information: 64 • Open Source ActiveMQ - http://activemq.apache.org/ • JMS tutorial - http://docs.oracle.com/javaee/6/tutorial/doc/bncdq.html • SQL/MX database - NonStop SQL/MX documentation set • JDBC Type 2 Driver Programmer's Reference for SQL/MX • NonStop Server for Java 6.0 Programmer's Reference • NonStop Application Server for Java 1.0 User Guide • TS/MP 2.
Glossary CIP Cluster I/O Protocols EJB Enterprise Java Beans JCA Java Connector Architecture JDBC Java Database Connectivity JMS Java Messaging System JMX Java Management Extension JTA Java Transaction API JTS Java Transaction Service JVM Java Virtual Machine MDB Message Driven Beans MOM Message Oriented Middleware NSASJ NonStop Application Server For Java NSJ NonStop Server for Java NSMQ NonStop Message Queue. The port of Apache ActiveMQ 5.6 on NonStop.
