HP Integrity NonStop H-Series User Manual

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.

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. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Export of the information contained in this publication may require authorization from the U.S. Department of Commerce.

Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation.

Intel, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Java is a registered trademark of Oracle and/or its affiliates.

Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks, and IT DialTone and The Open Group are trademarks of The Open Group in the U.S. and other countries.

Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. OSF shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material.

JBoss and Hibernate are registered trademarks and servicemarks of Red Hat, Inc.

Spring Framework is an open source project and is a trademark of Interface 21.

© 1990, 1991, 1992, 1993 Open Software Foundation, Inc. The OSF documentation and the OSF software to which it relates are derived in part from materials supplied by the following:© 1987, 1988, 1989 Carnegie-Mellon University. © 1989, 1990, 1991 Digital Equipment Corporation. © 1985, 1988, 1989, 1990 Encore Computer Corporation. © 1988 Free Software Foundation, Inc. © 1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. © 1985, 1987, 1988, 1989, 1990, 1991, 1992 International Business Machines Corporation. © 1988, 1989 Massachusetts Institute of Technology. © 1988, 1989, 1990 Mentat Inc. © 1988 Microsoft Corporation. © 1987, 1988, 1989, 1990, 1991, 1992 SecureWare, Inc. © 1990, 1991 Siemens Nixdorf Informationssysteme AG. © 1986, 1989, 1996, 1997 Sun Microsystems, Inc. © 1989, 1990, 1991 Transarc Corporation.OSF software and documentation are based in part on the Fourth Berkeley Software Distribution under license from The Regents of the University of California. OSF acknowledges the following individuals and institutions for their role in its development: Kenneth C.R.C. Arnold, Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. © 1980, 1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California.

About This Document.....................................................................................5

Supported Release Version Updates (RVUs)..................................................................................5

Intended Audience....................................................................................................................5

New and Changed Information..................................................................................................5

Changes to the 698926-002 edition......................................................................................5

Document Organization............................................................................................................5

Notation Conventions................................................................................................................6

Related Information...................................................................................................................7

Publishing History.....................................................................................................................7

HP Encourages Your Comments..................................................................................................7

1 Introduction to NSMQ.................................................................................8

JMS and ActiveMQ...................................................................................................................8

NonStop products used by NSMQ.............................................................................................8

Features of NSMQ....................................................................................................................9

Architecture.............................................................................................................................9

High availability.....................................................................................................................11

Scalability using cluster of brokers............................................................................................11

Fault tolerance........................................................................................................................12

Message flow in a cluster........................................................................................................12

2 Installation and configuration.....................................................................14

Pre-requisites..........................................................................................................................14

Installing NSMQ from the CD..................................................................................................14

Running the IPSetup program...............................................................................................14

Running the setup script......................................................................................................24

Customizing NSMQ installation...........................................................................................26

Uninstalling NSMQ............................................................................................................27

Configuring NSMQ................................................................................................................28

Creating a cluster..............................................................................................................28

Adding a broker to a cluster................................................................................................29

Removing a broker.............................................................................................................29

Removing a cluster.............................................................................................................30

3 Managing NSMQ....................................................................................31

Starting/Stopping a cluster/broker...........................................................................................31

Monitoring activities................................................................................................................31

Checking the cluster status..................................................................................................31

Management operations.....................................................................................................32

4 Security...................................................................................................42

Authentication........................................................................................................................42

Authorization.........................................................................................................................43

Secure Socket Layer................................................................................................................44

5 Integration...............................................................................................46

Integrating NSMQ with NSASJ.................................................................................................46

Integrating NSMQ with JTA-TMF application..............................................................................47

Pre-requisites.....................................................................................................................47

JTA-TMF settings.................................................................................................................47

Configuring the JTA-TMF application.....................................................................................48

Running the JTA-TMF application..........................................................................................48

How do local transactions work?..............................................................................................48

Contents 3

A Sample applications.................................................................................50

Pre-requisites..........................................................................................................................50

Dependent libraries for the sample applications..........................................................................50

Building the sample applications..............................................................................................50

Running the sample applications...............................................................................................51

B Use cases................................................................................................52

Using JMS from servlets and JSPs..............................................................................................52

Pre-requisites.....................................................................................................................52

Building the application Web Archive (WAR) file...................................................................52

Running the application......................................................................................................53

Using JMS from Pathway Server Classes....................................................................................56

Pre-requisites.....................................................................................................................56

Building the Java Archive (JAR) file.......................................................................................57

Executing the standalone server and client............................................................................57

Executing the TS/MP server and client..................................................................................57

C Configurable elements in NSMQ...............................................................59

D FAQ/Common problems and error conditions..............................................61

E References...............................................................................................64

Glossary....................................................................................................65

4 Contents

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.

Intended Audience

This manual is intended for users developing message oriented middleware to manage sending and receiving messages on NonStop.

To understand NSMQ, it is recommended to have a prior knowledge of the following:

• JMS and ActiveMQ

• NonStop products used by NSMQ — TS/MP, Cluster I/O protocols (CIP), and SQL/MX

database

New and Changed Information

Changes to the 698926-002 edition

• Updated “FAQ/Common problems and error conditions” (page 61)

Document Organization

This manual is organized as follows:

“Introduction to NSMQ” (page 8)

“Managing NSMQ” (page 31)

“Security” (page 42)

“Integration” (page 46)

“Sample applications” (page 50)

This chapter describes the overview and architectural details of NSMQ.

This chapter describes how to install and configure NSMQ.“Installation and configuration” (page 14)

This chapter describes how to manage NSMQ and setup and run sample applications.

This chapter describes about the Security methods provided by NSMQ.

This chapter describes how to integrate NSMQ with NSASJ and other use case examples.

This appendix describes how to build and run the Spring sample applications provided with NSMQ for your reference.

“Use cases” (page 52)

“FAQ/Common problems and error conditions” (page 61)

This appendix describes use case examples of how JMS is used from servlets and JSPs, and usage of NSMQ in a Client-Server environment on NonStop from Pathway Server Classes.

This appendix lists the frequently asked questions and the common problems and errors faced by users in NSMQ.

Supported Release Version Updates (RVUs) 5

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.jar

Italic Computer Type

Italic computer type letters in syntax descriptions or text indicate variable items that you supply. For example:

pathname

General references provided for more useful information.“References” (page 64)

Glossary of terms used in this manual.“Glossary” (page 65)

[ ] Brackets

Brackets enclose optional syntax items. For example:

jdb [options]

A group of items enclosed in brackets is a list from which you can choose one item or none. Items are separated by vertical lines. For example:

where [threadID|all]

{ } Braces

A group of items enclosed in braces is a list from which you must choose one item. For example:

-c identity {true|false}

| Vertical Line

A vertical line separates alternatives in a list that is enclosed in brackets or braces. For example:

where [threadID|all]

... Ellipsis

An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example:

print {objectID|objectName} ...

An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example:

dump objectID ...

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.filename

Line Spacing

If the syntax of a command is too long to fit on a single line, each line that is to be continued on the next line ends with a back slash ( \ ) and each continuation line begins with a greater-than symbol ( > ). For example:

/usr/bin/c89 -c -g -I /usr/tandem/java/include \ > -I /usr/tandem/java/include/oss -I . \ > -Wextensions -D_XOPEN_SOURCE_EXTENDED=1 jnative01.jar

Related Information

For a better understanding of NonStop Message Queue, see the following web sites:

• http://docs.oracle.com/javaee/6/tutorial/doc/bncdq.html

• http://activemq.apache.org/

Publishing History

HP Encourages Your Comments

HP encourages your comments concerning this document. We are committed to providing documentation that meets your needs. Send any errors found, suggestions for improvement, or compliments to docsfeedback@hp.com.

Include the document title, part number, and any comment, error found, or suggestion for improvement you have concerning this document.

Publication DateProduct VersionPart Number

June 20131.0698926-001

March 20141.0698926-002

Related Information 7

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. An NSMQ broker is a messaging agent that manages the exchange of messages between messaging clients or communication with other brokers. Messaging clients are the applications that send or receive messages. The broker listens on an IP address and accommodates to the requests of message producers (that creates and send messages) and consumers (that receive and process messages).

NSMQ is a port of Apache ActiveMQ 5.6 on NonStop platform. It is implemented using NonStop platform technologies such as TS/MP, Cluster I/O Protocols (CIP), and SQL/MX database. It can also be integrated with other Java products like NonStop Application Server for Java (NSASJ).

JMS and ActiveMQ

Enterprise applications provide the business logic for enterprises which are generally centrally managed and interact with other enterprise software. With Java Enterprise Edition (Java EE) providing a set of specifications, development of Java enterprise applications are easier and reduces the development time, application complexity, and improves the overall application runtime. JMS is one such specification.

The JMS defines a set of Java Application Programming Interfaces (APIs) for sending or receiving messages between two or more clients. It is a messaging standard that allows application components based on the Java EE to create, send, receive, and process messages asynchronously.

For more information about JMS, see http://docs.oracle.com/javaee/6/tutorial/doc/bncdq.html. ActiveMQ is an open source message oriented middleware (MOM) system, and is an implementation

of JMS 1.1 specification. For more information about ActiveMQ, see http://activemq.apache.org/.

NonStop products used by NSMQ

The following products are used by NSMQ:

• NonStop TS/MP products

• NonStop Cluster I/O Protocols

• SQL/MX database

NonStop TS/MP products

NSMQ uses TS/MP for process management only. For example, auto restart of a process if it shuts down.

The NonStop TS/MP product consists of the PATHMON process, the application cluster services (ACS) subsystem processes, the PATHCOM process and interface.

A single cluster node of NSMQ is configured to run as two TS/MP server classes with one process each representing master and slave instances.

For more information about NonStop TS/MP, see the HP NonStop TS/MP 2.5 System Management Manual and the HP NonStop TS/MP 2.5 Management Programming Manual.

NonStop Cluster I/O Protocols

In NSMQ, the NonStop Cluster I/O Protocols (CIP) subsystem acts as a medium of interface between the brokers and JMS clients.

8 Introduction to NSMQ

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. In such an

environment, all brokers are networked and if a broker fails, the load is distributed among the remaining brokers in the cluster. In clustering, multicasting and dynamic discovery is not supported.

• Client API support — Only JMS clients are supported. C++, .NET clients are not supported.

• Persistence — Messages are stored in SQL/MX database.

• Destinations — Specifies the destinations that must be created when a broker starts. The

following destinations are supported:

◦ Queue — Queues are used for Point-To-Point messaging in first-in first-out order. Messages

are consumed from the queue in the order in which they are received. See http://

docs.oracle.com/javaee/6/tutorial/doc/bncdx.html#bnceb.

◦ Topic — Topics are used for Publish and Subscribe (Pub/Sub) messaging. The message

◦ Composite destinations — Composite destinations provide a mechanism for producers

◦ Virtual destinations — Virtual destinations provide a mechanism for publishers to broadcast

◦ Wildcards — Wildcards provide a mechanism for consumers to subscribe to multiple

Architecture

Although ActiveMQ supports various topologies to configure brokers, NSMQ supports the complete grid topology on a NonStop system.

In this architecture, you can have multiple brokers on a NonStop node. Multiple brokers can run on the same or different CPUs. However, HP recommends you to run brokers on different CPUs to achieve uninterrupted availability.

Figure 1 (page 10) illustrates the architecture of NSMQ.

producer is referred as Publisher and the message consumer is referred as Subscriber. See http://docs.oracle.com/javaee/6/tutorial/doc/bncdx.html#bnced.

However, the durable subscription of messages for topics is not supported in NSMQ.

to send the same message to multiple destinations at the same time. See http://

activemq.apache.org/composite-destinations.html.

messages through a topic to a pool of receivers subscribing through queues. See http://

activemq.apache.org/virtual-destinations.html.

destinations at the same time. See http://activemq.apache.org/wildcards.html.

Features of NSMQ 9

Figure 1 Architecture of NSMQ

SQL/MX Database

Producer

Consumer

: 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. All the brokers are connected to each other using a duplex network connector to exchange

information and states of each broker. These brokers listen on a local loopback address with different port numbers and are used exclusively for clustering.

In such a cluster, all the messages are accessible to all the brokers. A new broker can be introduced by adding the broker to the local grid without disturbing the existing cluster, thus achieving scalability

(page 11).

Every broker is a combination of master and slave broker and is configured to run as two TS/MP server classes — one process each for a master instance and a slave instance. The master instance

10 Introduction to NSMQ

is active and slave instance is on stand by. When the master instance fails, the slave instance takes

Producer

Consumer

SQL/MX

Database

B2 B2’

Master Slave

SQL/MX Database

: Brokers

......

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.

Producer:

Producers are the JMS clients that send messages.

Consumer:

Consumers are the JMS clients that receive messages.

High availability

In NSMQ, high availability is achieved using a master-slave configuration. All the brokers in the master-slave cluster have the same configuration and compete to acquire the

lock on a data file during startup. The broker acquiring the lock starts all the network and transport connectors and becomes the master, and the remaining instances become slave brokers. When the master broker fails or shuts down, one of the slaves acquire the exclusive lock on the data file and becomes the new master broker. The clients can use the failover protocol for automatic reconnection to the new master broker.

The auto restart feature of TS/MP ensures that the failed master process is restarted again. The auto restarted master process becomes the new slave, thus ensuring high availability is achieved.

Figure 2 (page 11) represents a master-slave configuration in NSMQ.

Figure 2 Master-slave configuration

Scalability using cluster of brokers

See also http://activemq.apache.org/jdbc-master-slave.html.

In NSMQ, scalability can be achieved by adding brokers to the cluster to handle additional load. Any number of brokers can be added or removed from the cluster without affecting the services. Proper removal of the broker requires the cluster to be brought down. When more brokers are added, the CIP subsystem facilitates load balancing across all brokers. Since every broker is connected to every other broker in the cluster, all the messages are accessible to all the brokers. If a broker shuts down or fails, the load is balanced among the remaining brokers in the cluster.

High availability 11

Figure 3 (page 12) represents a cluster of brokers.

Producer

Consumer

SQL/MX

Database

Local Host: 6161

B1’

Local Host: 6162

B2’

Local Host: 616n

Bn’

Local Host: 6163

B3’

: Brokers

......

Figure 3 Cluster of brokers

Fault tolerance

Fault tolerance is the ability to prevent a system from failure when an unexpected problem occurs. In NSMQ, fault tolerance is achieved by enabling persistence.

Persistence is a feature used by applications to achieve fault tolerance irrespective of a cluster start, stop, or restart. NSMQ provides fault tolerance by persisting messages to the SQL/MX database. Messages are stored in a database before they are dispatched. If a broker fails, the undelivered messages are retrieved from the database and rerun when the broker restarts. The messages are deleted from the database after the message delivery is confirmed.

NSMQ communicates to the database using JDBC T2 driver version 3.2 or later (T1275R32) for persisting messages to the database. NSMQ requires SQL/MX 3.2 or later versions for providing this feature.

NOTE:

• By default, ActiveMQ uses a separate database for every broker in a cluster. Managing

multiple databases is complex as each broker has its own database. To overcome this, NSMQ persists messages from different brokers to a single database (that is, a single set of tables).

Message flow in a cluster

• If persistence is not enabled, then there is no master-slave configuration. Also, NSMQ will not

This section illustrates with an example how a message flows in a cluster of brokers. In a cluster of brokers, a message produced at any broker is available to any consumer connected

to any other broker.

12 Introduction to NSMQ

be fully JMS 1.1 compliant.

Let us consider two brokers, Broker1 and Broker2, set up to form a cluster. These brokers are

1. Send

3. Acknowledge

5. Send

7. Acknowledge 11. Acknowledge

10. Send

2. Store

4. Fetch

8. Update

6. Store

9. Fetch

12. Update

Producer Broker 1 Broker 2 Consumer

SQL/MX

Database

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

The message flow through the cluster can be explained as follows:

• A producer connects to a queue or topic in a cluster.

• The CIP subsystem forwards the connection to Broker1.

• A consumer connects to the cluster.

• The CIP subsystem forwards the connection to Broker2. The consumer is subscribed to the

same queue or topic to which the producer is connected.

• The producer sends a message (sequence 1 in Figure 4 (page 13)).

• Broker1 stores the message in the database and sends an acknowledgement to the producer

(2 and 3).

• Since Broker2 has a duplex connection with Broker1, Broker2 subscribes to the message.

• Broker1 fetches the message and sends it to Broker2 (4 and 5).

• Broker2 stores the message in the database and sends the acknowledgement to Broker1 (6

and 7).

• Broker1 marks the message as consumed and updates the database (8).

• Broker 2 fetches the message and dispatches it to the consumer through the CIP subsystem (9

and 10).

• Upon receiving the message, the consumer acknowledges the receipt of the message. Broker2

updates the database by marking the message as consumed and deletes it (11 and 12).

Message flow in a cluster 13

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

For more information:Software

See the SQL/MX 3.2.1 Installation and Upgrade Guide.SQL/MX database 3.2.1

See the JDBC Type 2 Driver Programmer's Reference for SQL/MX Release 3.2.JDBC/MX Type 2 driver 3.2 or later

See the NonStop Server for Java 6.0 Programmer's Reference manual.NSJ 6 or later

See the TS/MP 2.5 Management Programming Manual.TS/MP 2.5

Installing NSMQ from the CD

This section includes the following topics:

• Running the IPSetup program

• Running the setup script

Running the IPSetup program

The NSMQ software is available on the NSMQ product CD. Use the IPSetup program to move the NSMQ software from the product CD to a NonStop system.

To run the IPSetup program, perform the following steps:

1. Double-click the CD drive to open the product CD and then click the Setup.exe file.

The Independent Products Setup screen appears.

2. Click View the Readme File option.

The readme.txt file opens.

3. Review the information provided in the readme.txt file and go back to the Independent

Products Setup screen.

4. Click Run IPSetup option to launch IPSetup.

The Welcome screen appears.

14 Installation and configuration

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.

Installing NSMQ from the CD 15

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.

16 Installation and configuration

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.

Installing NSMQ from the CD 17

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.

18 Installation and configuration

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. If the SSH server is not configured or not running on the NonStop server, you will not be allowed to proceed with this mode of communication.

For a secure mode of communication, select SSH. Otherwise, accept the default Telnet, which sends data in an unsecure mode.

For Telnet mode, enter the logon service that will call the Safeguard prompt. The default service is TACL.

Installing NSMQ from the CD 19

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. Browse to select the location for a work subvolume and backup of your choice.

NOTE: If you want to back up the existing files in the work subvolume to another

subvolume, select the Back up existing host files to check box.

The Host File Placement screen appears.

20 Installation and configuration

+ 45 hidden pages