ballerinax/nats

Package Overview

This package provides the capability to connect with NATS server and performs the below functionalities.

  • Point to point communication (Queues)
  • Pub/Sub (Topics)
  • Request/Reply

Basic Usage

Setting up the connection

First step is setting up the connection with the NATS Basic server. The following ways can be used to connect to a NATS Basic server.

  1. Connect to a server using the default URL
1nats:Client natsClient = new(nats:DEFAULT_URL);
  1. Connect to a server using the URL
1nats:Client natsClient = new("nats://serverone:4222");
  1. Connect to one or more servers with custom configurations
1nats:ConnectionConfiguration config = {
2 connectionName: "my-nats",
3 noEcho: true
4};
5nats:Client natsClient = new(["nats://serverone:4222", "nats://servertwo:4222"], config);

Publishing messages

Publishing messages to the NATS basic server

Once connected, publishing is accomplished via one of the below two methods.

  1. Publish with the subject and the message content.
1string message = "hello world";
2nats:Error? result =
3 natsClient->publishMessage({ content: message.toBytes(), subject: "demo.nats.basic"});
  1. Publish as a request that expects a reply.
1string message = "hello world";
2nats:Message|nats:Error reqReply =
3 natsClient->requestMessage({ content: message.toBytes(), subject: "demo.nats.basic"}, 5);
  1. Publish messages with a replyTo subject
1string message = "hello world";
2nats:Error? result = natsClient->publish({ content: message.toBytes(), subject: "demo.nats.basic",
3 replyTo: "demo.reply" });

Listening to incoming messages

Listening to messages from a NATS server
1// Binds the consumer to listen to the messages published to the 'demo.example.*' subject.
2@nats:ServiceConfig {
3 subject: "demo.example.*"
4}
5service nats:Service on new nats:Listener(nats:DEFAULT_URL) {
6
7 remote function onMessage(nats:Message message) {
8 }
9}

Note: The default thread pool size used in Ballerina is the number of processors available * 2. You can configure the thread pool size by using the BALLERINA_MAX_POOL_SIZE environment variable.

For information on the operations, which you can perform with this package, see the below Functions.

For examples on the usage of the connector, see the following.

Listeners

[1]

Listener

Represents the NATS server connection to which a subscription service should be bound in order to receive messages of the corresponding subscription.

Clients

[1]

Client

The client provides the capability to publish messages to the NATS server.

Object types

[1]

Service

The NATS service type

Records

[9]

ConnectionConfiguration

Configurations related to creating a NATS streaming subscription.

Credentials

Configurations related to basic authentication.

Message

Represents the message, which a NATS server sends to its subscribed services.

PendingLimits

The configurations to set limits on the maximum number of messages or maximum size of messages this consumer will hold before it starts to drop new messages waiting for the resource functions to drain the queue.

Ping

Configurations related to pinging the server

RetryConfig

Configurations related to connection reconnect attempts.

SecureSocket

Configurations related to facilitating a secure communication.

ServiceConfigData

The configurations for the NATS basic subscription.

Tokens

Configurations related to token based authentication.

Constants

[1]

DEFAULT_URL

Default URL for NATS connections.

Enums

[1]

Protocol

Represents protocol options.

Annotations

[1]

ServiceConfig

The annotation, which is used to configure the basic subscription.

Errors

[1]

Error

Represents the NATS module related errors.