-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat AMQ
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.