Using the AMQ JavaScript Client
For Use with AMQ Clients 2.3
Abstract
Chapter 1. Overview
AMQ JavaScript is a library for developing messaging applications. It enables you to write JavaScript applications that send and receive AMQP messages.
AMQ JavaScript is part of AMQ Clients, a suite of messaging libraries supporting multiple languages and platforms. For an overview of the clients, see AMQ Clients Overview. For information about this release, see AMQ Clients 2.3 Release Notes.
AMQ JavaScript is based on the Rhea messaging library.
1.1. Key features
- An event-driven API that simplifies integration with existing applications
- SSL/TLS for secure communication
- Flexible SASL authentication
- Automatic reconnect and failover
- Seamless conversion between AMQP and language-native data types
- Access to all the features and capabilities of AMQP 1.0
1.2. Supported standards and protocols
AMQ JavaScript supports the following industry-recognized standards and network protocols:
- Version 1.0 of the Advanced Message Queueing Protocol (AMQP)
- Versions 1.0, 1.1, and 1.2 of the Transport Layer Security (TLS) protocol, the successor to SSL
- Simple Authentication and Security Layer (SASL) mechanisms ANONYMOUS, PLAIN, and EXTERNAL
- Modern TCP with IPv6
1.3. Supported configurations
AMQ JavaScript supports the following OS and language versions:
- Red Hat Enterprise Linux 6 with Node.js 4, 6, and 8 from Software Collections
- Red Hat Enterprise Linux 7 with Node.js 4, 6, and 8 from Software Collections
- Microsoft Windows 10 Pro with Node.js 4, 6, and 8
- Microsoft Windows Server 2012 R2 with Node.js 4, 6, and 8
- Microsoft Windows Server 2016 with Node.js 4, 6, and 8
For more information, see Red Hat AMQ 7 Supported Configurations.
1.4. Terms and concepts
This section introduces the core API entities and describes how they operate together.
Entity | Description |
---|---|
Container | A top-level container of connections |
Connection | A channel for communication between two peers on a network |
Session | A context for sending and receiving messages |
Sender | A channel for sending messages to a target |
Receiver | A channel for receiving messages from a source |
Source | A named point of origin for messages |
Target | A named destination for messages |
Message | A mutable holder of application data |
Delivery | A message transfer |
AMQ JavaScript sends and receives messages. Messages are transferred between connected peers over senders and receivers. Senders and receivers are established over sessions. Sessions are established over connections. Connections are established between two uniquely identified containers. Though a connection can have multiple sessions, often this is not needed. The API allows you to ignore sessions unless you require them.
A sending peer creates a sender to send messages. The sender has a target that identifies a queue or topic at the remote peer. A receiving peer creates a receiver to receive messages. The receiver has a source that identifies a queue or topic at the remote peer.
The sending of a message is called a delivery. The message is the content sent, including all metadata such as headers and annotations. The delivery is the protocol exchange associated with the transfer of that content.
To indicate that a delivery is complete, either the sender or the receiver settles it. When the other side learns that it has been settled, it will no longer communicate about that delivery. The receiver can also indicate whether it accepts or rejects the message.
1.5. Document conventions
In this document, sudo
is used for any command that requires root privileges. You should always exercise caution when using sudo
, as any changes can affect the entire system.
For more information about using sudo
, see The sudo
Command.
Chapter 2. Installation
This chapter guides you through the steps to install AMQ JavaScript in your environment.
2.1. Prerequisites
To begin installation, use your subscription to access AMQ distribution files and repositories.
To use AMQ JavaScript, you must also install and configure Node.js for your environment. See the Node.js website for more information.
AMQ JavaScript depends on the Node.js debug
module. See the npm page for installation instructions.
2.2. Installing on Red Hat Enterprise Linux
AMQ JavaScript is distributed as a zip archive. Follow these steps to install it in your environment.
- Open a browser and log in to the Red Hat Customer Portal Product Downloads page at access.redhat.com/downloads.
- Locate the Red Hat AMQ Clients entry in the JBOSS INTEGRATION AND AUTOMATION category.
- Click Red Hat AMQ Clients. The Software Downloads page opens.
- Download the AMQ JavaScript Client zip file.
Use the
unzip
command to extract the file contents into a directory of your choosing. This creates a new subdirectory namednodejs-rhea-<version>
.$ unzip nodejs-rhea-<version>.zip Archive: nodejs-rhea-<version>.zip creating: nodejs-rhea-<version>/ creating: nodejs-rhea-<version>/node_modules/ creating: nodejs-rhea-<version>/node_modules/rhea/ [...]
Configure your environment to use the installed library. Add the
node_modules
directory to theNODE_PATH
environment variable.$ cd nodejs-rhea-<version> $ export NODE_PATH=$PWD/node_modules:$NODE_PATH
To make this configuration take effect for all new console sessions, set
NODE_PATH
in your$HOME/.bashrc
file.Test your installation. The following command returns zero if it can successfully import the installed library.
$ node -e 'require("rhea")'; echo $? 0
2.3. Installing on Microsoft Windows
- Open a browser and log in to the Red Hat Customer Portal Product Downloads page at access.redhat.com/downloads.
- Locate the Red Hat AMQ Clients entry in the JBOSS INTEGRATION AND AUTOMATION category.
- Click Red Hat AMQ Clients. The Software Downloads page opens.
- Download the AMQ JavaScript Client zip file.
-
Extract the file contents into a directory of your choosing by right-clicking on the zip file and selecting Extract All. This creates a new subdirectory named
nodejs-rhea-<version>
. Configure your environment to use the installed library. Add the
node_modules
directory to theNODE_PATH
environment variable.$ cd nodejs-rhea-<version> $ set NODE_PATH=%cd%\node_modules;%NODE_PATH%
2.4. Preparing the library for use in browsers
AMQ JavaScript can run inside a web browser. To create a browser-compatible version of the library, use the npm run browserify
command.
$ cd nodejs-rhea-<version>/node_modules/rhea $ npm install $ npm run browserify
This produces a file named rhea.js
that can be used in browser-based applications.
Chapter 3. Getting started
This chapter guides you through a simple exercise to help you get started using AMQ JavaScript.
3.1. Preparing the broker
The example programs require a running broker with a queue named examples
. Follow these steps to define the queue and start the broker:
Procedure
- Install the broker.
- Create a broker instance. Enable anonymous access.
Start the broker instance and check the console for any critical errors logged during startup.
$ <broker-instance-dir>/bin/artemis run ... 14:43:20,158 INFO [org.apache.activemq.artemis.integration.bootstrap] AMQ101000: Starting ActiveMQ Artemis Server ... 15:01:39,686 INFO [org.apache.activemq.artemis.core.server] AMQ221020: Started Acceptor at 0.0.0.0:5672 for protocols [AMQP] ... 15:01:39,691 INFO [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live
Use the
artemis queue
command to create a queue calledexamples
.<broker-instance-dir>/bin/artemis queue create --name examples --auto-create-address --anycast
You are prompted to answer a series of questions. For yes or no questions, type
N
. Otherwise, press Enter to accept the default value.
3.2. Running Hello World
The Hello World example sends a message to the examples
queue on the broker and then fetches it back. On success it prints Hello World!
to the console.
Using your configured installation environment, run the helloworld.js
example.
$ cd nodejs-rhea-<version>/node_modules/rhea/examples $ node helloworld.js Hello World!
Chapter 4. Examples
This chapter demonstrates the use of AMQ JavaScript through example programs.
See the Rhea examples for more sample programs. Note that some of the sample programs there require the minimist package in order to parse command-line options.
4.1. Sending messages
This client program connects to a server using <connection-url>
, creates a sender for target <address>
, sends a message containing <message-body>
, closes the connection, and exits.
Example: Sending messages
"use strict"; var rhea = require("rhea"); var url = require("url"); if (process.argv.length !== 5) { console.error("Usage: send.js <connection-url> <address> <message-body>"); process.exit(1); } var conn_url = url.parse(process.argv[2]); var address = process.argv[3]; var message_body = process.argv[4]; var container = rhea.create_container(); container.on("sender_open", function (event) { console.log("SEND: Opened sender for target address '" + event.sender.target.address + "'"); }); container.on("sendable", function (event) { var message = { "body": message_body }; event.sender.send(message); console.log("SEND: Sent message '" + message.body + "'"); event.sender.close(); event.connection.close(); }); var opts = { host: conn_url.hostname, port: conn_url.port || 5672 }; var conn = container.connect(opts); conn.open_sender(address);
Running the example
To run the example program, copy it to a local file and invoke it using the node
command.
$ node send.js amqp://localhost queue1 hello
4.2. Receiving messages
This client program connects to a server using <connection-url>
, creates a receiver for source <address>
, and receives messages until it is terminated or it reaches <count>
messages.
Example: Receiving messages
"use strict"; var rhea = require("rhea"); var url = require("url"); if (process.argv.length !== 4 && process.argv.length !== 5) { console.error("Usage: receive.js <connection-url> <address> [<message-count>]"); process.exit(1); } var conn_url = url.parse(process.argv[2]); var address = process.argv[3]; var desired = 0; var received = 0; if (process.argv.length === 5) { desired = parseInt(process.argv[4]); } var container = rhea.create_container(); container.on("receiver_open", function (event) { console.log("RECEIVE: Opened receiver for source address '" + event.receiver.source.address + "'"); }); container.on("message", function (event) { var message = event.message; console.log("RECEIVE: Received message '" + message.body + "'"); received++; if (received == desired) { event.receiver.close(); event.connection.close(); } }); var opts = { host: conn_url.hostname, port: conn_url.port || 5672 }; var conn = container.connect(opts); conn.open_receiver(address);
Running the example
To run the example program, copy it to a local file and invoke it using the python
command.
$ node receive.js amqp://localhost queue1
Chapter 5. Using the API
This chapter explains how to use the AMQ JavaScript API to perform common messaging tasks.
5.1. Basic operation
5.1.1. Handling messaging events
AMQ JavaScript is an asynchronous event-driven API. To define how the application handles events, the user registers event-handling functions on the container
object. These functions are then called as network activity or timers trigger new events.
Example: Handling messaging events
var rhea = require("rhea"); var container = rhea.create_container(); container.on("sendable", function (event) { console.log("A message can be sent"); }); container.on("message", function (event) { console.log("A message is received"); });
These are only a few common-case events. The full set is documented in the API reference.
5.1.2. Creating a container
The container is the top-level API object. It is the entry point for creating connections, and it is responsible for running the main event loop. It is often constructed with a global event handler.
Example: Creating a container
var rhea = require("rhea");
var container = rhea.create_container();
Setting the container identity
Each container instance has a unique identity called the container ID. When AMQ JavaScript makes a network connection, it sends the container ID to the remote peer. To set the container ID, pass the id
option to the create_container
method.
Example: Setting the container identity
var container = rhea.create_container({"id": "job-processor-3"});
If the user does not set the ID, the library will generate a UUID when the container is constucted.
5.2. Network connections
5.2.1. Creating outgoing connections
To connect to a remote server, pass connection options containing the host and port to the container.connect()
method.
Example: Creating outgoing connections
container.on("connection_open", function (event) {
console.log("Connection " + event.connection + " is open");
});
var opts = {
"host": "example.com",
"port": 5672
};
container.connect(opts);
The default host is localhost
. The default port is 5672.
See the Section 5.3, “Security” section for information about creating secure connections.
5.2.2. Configuring reconnect
Reconnect allows a client to recover from lost connections. It is used to ensure that the components in a distributed system reestablish communication after temporary network or component failures.
AMQ JavaScript enables reconnect by default. If a connection attempt fails, the client will try again after a brief delay. The delay increases exponentially for each new attempt, up to a default maximum of 60 seconds.
To disable reconnect, set the reconnect
connection option to false
.
Example: Disabling reconnect
var opts = {
"host": "example.com",
"reconnect": false
};
container.connect(opts);
To control the delays between connection attempts, set the initial_reconnect_delay
and max_reconnect_delay
connection options. Delay options are specified in milliseconds.
To limit the number of reconnect attempts, set the reconnect_limit
option.
Example: Configuring reconnect
var opts = { "host": "example.com", "initial_reconnect_delay": 100, "max_reconnect_delay": 60 * 1000, "reconnect_limit": 10 }; container.connect(opts);
5.2.3. Configuring failover
AMQ JavaScript allows you to configure alternate connection endpoints programatically.
To specify multiple connection endpoints, define a function that returns new connection options and pass the function in the connection_details
option. The function is called once for each connection attempt.
Example: Configuring failover
var hosts = ["alpha.example.com", "beta.example.com"]; var index = -1; function failover_fn() { index += 1; if (index == hosts.length) index = 0; return {"host": hosts[index].hostname}; }; var opts = { "host": "example.com", "connection_details": failover_fn } container.connect(opts);
This example implements repeating round-robin failover for a list of hosts. You can use this interface to implement your own failover behavior.
5.3. Security
5.3.1. Securing connections with SSL/TLS
AMQ JavaScript uses SSL/TLS to encrypt communication between clients and servers.
To connect to a remote server with SSL/TLS, set the transport
connection option to tls
.
Example: Enabling SSL/TLS
var opts = {
"host": "example.com",
"port": 5671,
"transport": "tls"
};
container.connect(opts);
By default, the client will reject connections to servers with untrusted certificates. This is sometimes the case in test environments. To bypass certificate authorization, set the rejectUnauthorized
connection option to false
. Be aware that this compromises the security of your connection.
5.3.2. Connecting with a user and password
AMQ JavaScript can authenticate connections with a user and password.
To specify the credentials used for authentication, set the username
and password
connection options.
Example: Connecting with a user and password
var opts = { "host": "example.com", "username": "alice", "password": "secret" }; container.connect(opts);
5.3.3. Configuring SASL authentication
AMQ JavaScript uses the SASL protocol to perform authentication. SASL can use a number of different authentication mechanisms. When two network peers connect, they exchange their allowed mechanisms, and the strongest mechanism allowed by both is selected.
AMQ JavaScript enables SASL mechanisms based on the presence of user and password information. If the user and password are both specified, PLAIN
is used. If only a user is specified, ANONYMOUS
is used. If neither is specified, SASL is disabled.
5.4. More information
For more information, see the API reference.
Chapter 6. Interoperability
This chapter discusses how to use AMQ JavaScript in combination with other AMQ components. For an overview of the compatibility of AMQ components, see the product introduction.
6.1. Interoperating with other AMQP clients
AMQP messages are composed using the AMQP type system. This common format is one of the reasons AMQP clients in different languages are able to interoperate with each other.
When sending messages, AMQ JavaScript automatically converts language-native types to AMQP-encoded data. When receiving messages, the reverse conversion takes place.
More information about AMQP types is available at the interactive type reference maintained by the Apache Qpid project.
AMQP type | Description |
---|---|
An empty value | |
A true or false value | |
A single Unicode character | |
A sequence of Unicode characters | |
A sequence of bytes | |
A signed 8-bit integer | |
A signed 16-bit integer | |
A signed 32-bit integer | |
A signed 64-bit integer | |
An unsigned 8-bit integer | |
An unsigned 16-bit integer | |
An unsigned 32-bit integer | |
An unsigned 64-bit integer | |
A 32-bit floating point number | |
A 64-bit floating point number | |
A sequence of values of a single type | |
A sequence of values of variable type | |
A mapping from distinct keys to values | |
A universally unique identifier | |
A 7-bit ASCII string from a constrained domain | |
An absolute point in time |
JavaScript has fewer native types than AMQP can encode. To send messages containing specific AMQP types, use the wrap_
functions from the rhea/types.js
module.
AMQP type | AMQ JavaScript type before encoding | AMQ JavaScript type after decoding |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
AMQ JavaScript type before encoding | AMQ C++ type | AMQ .NET type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| - | - |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
AMQ JavaScript type before encoding | AMQ Python type | AMQ Ruby type |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| - | - |
|
|
|
|
|
|
6.2. Interoperating with AMQ JMS
AMQP defines a standard mapping to the JMS messaging model. This section discusses the various aspects of that mapping. For more information, see the AMQ JMS Interoperability chapter.
JMS message types
AMQ JavaScript provides a single message type whose body type can vary. By contrast, the JMS API uses different message types to represent different kinds of data. The table below indicates how particular body types map to JMS message types.
For more explicit control of the resulting JMS message type, you can set the x-opt-jms-msg-type
message annotation. See the AMQ JMS Interoperability chapter for more information.
AMQ JavaScript body type | JMS message type |
---|---|
| |
| |
| |
Any other type |
6.3. Connecting to AMQ Broker
AMQ Broker is designed to interoperate with AMQP 1.0 clients. Check the following to ensure the broker is configured for AMQP messaging.
- Port 5672 in the network firewall is open.
- The AMQ Broker AMQP acceptor is enabled. See Default acceptor settings.
- The necessary addresses are configured on the broker. See Addresses, Queues, and Topics.
- The broker is configured to permit access from your client, and the client is configured to send the required credentials. See Broker Security.
6.4. Connecting to AMQ Interconnect
AMQ Interconnect works with any AMQP 1.0 client. Check the following to ensure the components are configured correctly.
- Port 5672 in the network firewall is open.
- The router is configured to permit access from your client, and the client is configured to send the required credentials. See Interconnect Security.
Appendix A. Using your subscription
AMQ is provided through a software subscription. To manage your subscriptions, access your account at the Red Hat Customer Portal.
Accessing your account
- Go to access.redhat.com.
- If you do not already have an account, create one.
- Log in to your account.
Activating a subscription
- Go to access.redhat.com.
- Navigate to My Subscriptions.
- Navigate to Activate a subscription and enter your 16-digit activation number.
Downloading zip and tar files
To access zip or tar files, use the customer portal to find the relevant files for download. If you are using RPM packages, this step is not required.
- Open a browser and log in to the Red Hat Customer Portal Product Downloads page at access.redhat.com/downloads.
- Locate the Red Hat AMQ entries in the JBOSS INTEGRATION AND AUTOMATION category.
- Select the desired AMQ product. The Software Downloads page opens.
- Click the Download link for your component.
Registering your system for packages
To install RPM packages on Red Hat Enterprise Linux, your system must be registered. If you are using zip or tar files, this step is not required.
- Go to access.redhat.com.
- Navigate to Registration Assistant.
- Select your OS version and continue to the next page.
- Use the listed command in your system terminal to complete the registration.
To learn more see How to Register and Subscribe a System to the Red Hat Customer Portal.
Revised on 2019-03-18 15:32:36 UTC