Using the AMQ JavaScript Client

AMQ JavaScript supports the following industry-recognized standards and network protocols:

AMQ JavaScript supports the OS and language versions listed below. For more information, see Red Hat AMQ 7 Supported Configurations.

AMQ JavaScript is supported in combination with the following AMQ components and versions:

This section introduces the core API entities and describes how they operate together.

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.

The sudo command

In this document, sudo is used for any command that requires root privileges. Exercise caution when using sudo because any changes can affect the entire system. For more information about sudo, see Using the sudo command.

File paths

In this document, all file paths are valid for Linux, UNIX, and similar operating systems (for example, /home/andrea). On Microsoft Windows, you must use the equivalent Windows paths (for example, C:\Users\andrea).

Variable text

This document contains code blocks with variables that you must replace with values specific to your environment. Variable text is enclosed in arrow braces and styled as italic monospace. For example, in the following command, replace <project-dir> with the value for your environment:

$ cd <project-dir>

When you extract the contents of the .zip file, a directory named amq-clients-2.9.0-javascript is created. This is the top-level directory of the installation and is referred to as <install-dir> throughout this document.

To configure your environment to use the installed library, add the node_modules directory to the NODE_PATH environment variable.

$ cd amq-clients-2.9.0-javascript
$ 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.

To test your installation, use the following command. It prints OK to the console if it successfully imports the installed library.

$ node -e 'require("rhea")' && echo OK
OK

When you extract the contents of the .zip file, a directory named amq-clients-2.9.0-javascript is created. This is the top-level directory of the installation and is referred to as <install-dir> throughout this document.

To configure your environment to use the installed library, add the node_modules directory to the NODE_PATH environment variable.

$ cd amq-clients-2.9.0-javascript
$ set NODE_PATH=%cd%\node_modules;%NODE_PATH%

AMQ JavaScript can run inside a web browser. To create a browser-compatible version of the library, use the npm run browserify command.

$ cd amq-clients-2.9.0-javascript/node_modules/rhea
$ npm install
$ npm run browserify

This produces a file named rhea.js that can be used in browser-based applications.

The Hello World example creates a connection to the broker, sends a message containing a greeting to the examples queue, and receives it back. On success, it prints the received message to the console.

Change to the examples directory and run the helloworld.js example.

$ cd <install-dir>/node_modules/rhea/examples
$ node helloworld.js
Hello World!

The Hello World example creates a connection to the broker, sends a message containing a greeting to the examples queue, and receives it back. On success, it prints the received message to the console.

Change to the examples directory and run the helloworld.js example.

> cd <install-dir>/node_modules/rhea/examples
> node helloworld.js
Hello World!

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.

"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,
    // To connect with a user and password:
    // username: "<username>",
    // password: "<password>",
};

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. For more information, see Chapter 3, Getting started.

$ node send.js amqp://localhost queue1 hello

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.

"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,
    // To connect with a user and password:
    // username: "<username>",
    // password: "<password>",
};

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. For more information, see Chapter 3, Getting started.

$ node receive.js amqp://localhost queue1

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.

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 AMQ JavaScript API reference.

The event argument has attributes for accessing the object the event is regarding. For example, the connection_open event sets the event connection attribute.

In addition to the primary object for the event, all objects that form the context for the event are set as well. Attributes with no relevance to a particular event are null.

event.container
event.connection
event.session
event.sender
event.receiver
event.delivery
event.message

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.

var rhea = require("rhea");
var container = rhea.create_container();

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.

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.

To connect to a remote server, pass connection options containing the host and port to the container.connect() method.

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.

For information about creating secure connections, Chapter 7, Security.

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.

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.

var opts = {
    host: "example.com",
    initial_reconnect_delay: 100,
    max_reconnect_delay: 60 * 1000,
    reconnect_limit: 10
};

container.connect(opts);

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.

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.

AMQ JavaScript can accept inbound network connections, enabling you to build custom messaging servers.

To start listening for connections, use the container.listen() method with options containing the local host address and port to listen on.

container.on("connection_open", function (event) {
    console.log("New incoming connection " + event.connection);
});

var opts = {
    host: "0.0.0.0",
    port: 5672
};

container.listen(opts);

The special IP address 0.0.0.0 listens on all available IPv4 interfaces. To listen on all IPv6 interfaces, use [::0].

For more information, see the server receive.js example.

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.

var opts = {
    host: "example.com",
    port: 5671,
    transport: "tls"
};

container.connect(opts);

AMQ JavaScript can authenticate connections with a user and password.

To specify the credentials used for authentication, set the username and password connection options.

var opts = {
    host: "example.com",
    username: "alice",
    password: "secret"
};

container.connect(opts);

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.

Some message servers support on-demand creation of queues and topics. When a sender or receiver is attached, the server uses the sender target address or the receiver source address to create a queue or topic with a name matching the address.

The message server typically defaults to creating either a queue (for one-to-one message delivery) or a topic (for one-to-many message delivery). The client can indicate which it prefers by setting the queue or topic capability on the source or target.

To select queue or topic semantics, follow these steps:

var conn = container.connect({host: "example.com"});

var sender_opts = {
    target: {
        address: "jobs",
        capabilities: ["queue"]
    }
}

conn.open_sender(sender_opts);

var conn = container.connect({host: "example.com"});

var receiver_opts = {
    source: {
        address: "notifications",
        capabilities: ["topic"]
    }
}

conn.open_receiver(receiver_opts);

For more details, see the following examples:

A durable subscription is a piece of state on the remote server representing a message receiver. Ordinarily, message receivers are discarded when a client closes. However, because durable subscriptions are persistent, clients can detach from them and then re-attach later. Any messages received while detached are available when the client re-attaches.

Durable subscriptions are uniquely identified by combining the client container ID and receiver name to form a subscription ID. These must have stable values so that the subscription can be recovered.

To detach from a subscription, use the receiver.detach() method. To terminate the subscription, use the receiver.close() method.

For more information, see the durable-subscribe.js example.

A shared subscription is a piece of state on the remote server representing one or more message receivers. Because it is shared, multiple clients can consume from the same stream of messages.

The client configures a shared subscription by setting the shared capability on the receiver source.

Shared subscriptions are uniquely identified by combining the client container ID and receiver name to form a subscription ID. These must have stable values so that multiple client processes can locate the same subscription. If the global capability is set in addition to shared, the receiver name alone is used to identify the subscription.

To create a durable subscription, follow these steps:

To detach from a subscription, use the receiver.detach() method. To terminate the subscription, use the receiver.close() method.

For more information, see the shared-subscribe.js example.

AMQ JavaScript uses the JavaScript debug module to implement logging.

For example, to enable detailed client logging, set the DEBUG environment variable to rhea*:

$ export DEBUG=rhea*
$ <your-client-program>

The client can log AMQP protocol frames to the console. This data is often critical when diagnosing problems.

To enable protocol logging, set the DEBUG environment variable to rhea:frames:

$ export DEBUG=rhea:frames
$ <your-client-program>

If set, AMQ JavaScript uses the value of the MESSAGING_CONNECT_FILE environment variable to locate the configuration file.

If MESSAGING_CONNECT_FILE is not set, AMQ JavaScript searches for a file named connect.json at the following locations and in the order shown. It stops at the first match it encounters.

If no connect.json file is found, the library uses default values for all options.

The connect.json file contains JSON data, with additional support for JavaScript comments.

All of the configuration attributes are optional or have default values, so a simple example need only provide a few details:

{
    "host": "example.com",
    "user": "alice",
    "password": "secret"
}

SASL and SSL/TLS options are nested under "sasl" and "tls" namespaces:

{
    "host": "example.com",
    "user": "ortega",
    "password": "secret",
    "sasl": {
        "mechanisms": ["SCRAM-SHA-1", "SCRAM-SHA-256"]
    },
    "tls": {
        "cert": "/home/ortega/cert.pem",
        "key": "/home/ortega/key.pem"
    }
}

The option keys containing a dot (.) represent attributes nested inside a namespace.

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.

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 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 Broker is designed to interoperate with AMQP 1.0 clients. Check the following to ensure the broker is configured for AMQP messaging:

AMQ Interconnect works with any AMQP 1.0 client. Check the following to ensure the components are configured correctly: