ns-solace-utils

Utility library for Nu Skin to publish to and consume from the Solace Event Message Router.

CONTENTS

• ns-solace-utils
  • NPM and Github Repo
  • Installation
  • Usage
    • Solace Sessions
    • Queue Message Consumer
    • Topic Message Publisher

NPM and Github Repo

https://www.npmjs.com/package/@nuskin/ns-solace-utils https://code.tls.nuskin.io/nextgen-development/utility/ns-solace-utils

Installation

Using npm:

$ npm install @nuskin/ns-solace-utils

Usage

Solace Sessions

The session module creates and returns a solace session based on the properties you provide. It can also disconnect and exit from a session.

When you get a session you are required to pass in a callback that it will trigger when the session receives the SessionEventCode.UP_NOTICE event from Solace. You also have the option to override the other events that it is currently listening for if you would like. Subscribed Solace Events: SessionEventCode.ACKNOWLEDGED_MESSAGE, SessionEventCode.REJECTED_MESSAGE_ERROR, SessionEventCode.CONNECT_FAILED_ERROR, SessionEventCode.DISCONNECTED You are also given the session object itself if you want to just override it inside your own code by calling session.on()

To disconnect or exit your session you can just call those methods, pass it your session, and it will gracefully disconnect and dispose of your session for you. Example 1:

const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const properties = {};

getSolaceSession(properties, (session) => {
    // What you want to do once the session is up and connected goes here.
}).connect();

    

Example 2:

const { getSolaceSession, exitSolaceSession, disconnectSolaceSession } = require('@nuskin/ns-solace-utils').session;
const properties = {};

const solaceSession = getSolaceSession(properties, onUpCallback);
solaceSession.connect();

disconnectSolaceSession(solaceSession);
exitSolaceSession(solaceSession);

const onUpCallback = (session) => {
    // You could also split them up this way if you'd prefer
}
    

Example 3:

const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const properties = {};

const solaceSession = getSolaceSession(properties, onUpCallback, onAcknowledgedCallback);
solaceSession.connect();

const onUpCallback = (session) => {
    // You could also split them up this way if you'd prefer
}

const onAcknowledgedCallback = (session) => {
    // I'm overriding SessionEventCode.ACKNOWLEDGED_MESSAGE here.
}

Queue Message Consumer

The queueConsumer module the ability to begin consuming messages from a Solace Queue. The Solace MessageConsumer does require an active session so you'll need to pass that in once you have it. Like with the session module you will be required to pass in a callback. In this case the callback will listen for the MessageConsumerEventName.MESSAGE event. This is what is fired when your consumer receives a message from the queue. Also, just like the session module we allow you to override the other default callbacks. Subscribed Solace Events: MessageConsumerEventName.UP, MessageConsumerEventName.CONNECT_FAILED_ERROR, MessageConsumerEventName.DOWN, MessageConsumerEventName.DOWN_ERROR

The Solace Message Router doesn't allow us to easily nack messages so the default behavior of these other events is to disconnect from the queue without acknowledging the message which will place the message back on the queue. Then we try and reconnect after a brief wait at which point your consumer will receive the same message again.

You can also pass in a MessageConsumerAcknowledgeMode. It will default to CLIENT which means that it is up to you to acknowledge() your own messages when you're done with them. The other option is MessageConsumerAcknowledgeMode.AUTO which will acknowledge your messages the moment you pull them from the queue.

Important Note: There are a variety of ways the message could come down from Solace depending on how the client sent the message body to the router. You can use the getMessageBody() function in the util.js file.

Example 1:

const { createQueueConsumer } = require("@nuskin/ns-solace-utils").queueConsumer;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const queueName = 'MyQueueName';

getSolaceSession(properties, (session) => {
    const queueConsumer = createQueueConsumer(session, queueName, (message) => {
        // This is the callback that will be triggered when you receive a message
    })
    queueConsumer.connect();
}).connect();

Example 2:

const { createQueueConsumer } = require("@nuskin/ns-solace-utils").queueConsumer;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const queueName = 'MyQueueName';

getSolaceSession(properties, (session) => {
    const queueConsumer = createQueueConsumer(session, queueName, onMessageEventCallback)
    queueConsumer.connect();
}).connect();

const onMessageEventCallback = (session) => {
    // You could also split them up this way if you'd prefer
}

Example 3:

const { createQueueConsumer } = require("@nuskin/ns-solace-utils").queueConsumer;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const queueName = 'MyQueueName';

getSolaceSession(properties, (session) => {
    const queueConsumer = createQueueConsumer(session, queueName, onMessageCallback, onUpCallback)
    queueConsumer.connect();
}).connect();

const onMessageCallback = (session) => {
    // You could also split them up this way if you'd prefer
}


const onUpCallback = (session) => {
    // I'm overriding the MessageConsumerEventName.UP event
}

Topic Message Publisher

The publisher module allows you to either send a message in a "fire and forget" fashion or it allows you to subscribe to the events and listen for the consumer of your message to send you a SessionEventCode.ACKNOWLEDGED_MESSAGE or a SessionEventCode.REJECTED_MESSAGE_ERROR. Once again you can override these functions with whatever you want and you'll also need to pass in your session again. Your messages need to be passed in as a string or you will experience an error or potential issues with your consumers.

The default event listeners will log out whether or not your message was successful and then gracefully disconnect and dispose of your session. So, if you want to do anything based on the consumer's event you'll want to pass in some callbacks.

Example 1:

const { sendMessage } = require('@nuskin/ns-solace-utils').publisher;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const topicName = 'MyTopicName';
const message = { readmeMessage: `I'm JSON right now but make sure you stringify me!`}
const metadata = {}

getSolaceSession(properties, (session) =>
    sendMessage(session, topicName, JSON.stringify(message), metadata);
).connect();

Example 2:

const { sendMessageAndSubscribe } = require('@nuskin/ns-solace-utils').publisher;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const topicName = 'MyTopicName';
const message = { readmeMessage: `I'm JSON right now but make sure you stringify me!`}
const metadata = {}

getSolaceSession(properties, (session) =>
    sendMessageAndSubscribe(session, topicName, JSON.stringify(message), metadata, (evt) => {
        return 'acknowledged';
    }, (err) => {
        return 'rejected';
    });
).connect();

Example 3:

const { sendMessageAndSubscribe } = require('@nuskin/ns-solace-utils').publisher;
const { getSolaceSession } = require('@nuskin/ns-solace-utils').session;
const topicName = 'MyTopicName';
const message = { readmeMessage: `I'm JSON right now but make sure you stringify me!`}
const metadata = {}

getSolaceSession(properties, (session) =>
    sendMessageAndSubscribe(session, topicName, JSON.stringify(message), metadata, onAcknowledgedCallback, onRejectedCallback);
).connect();

const onAcknowledgedCallback = (session) => {
    // I'm overriding the SessionEventCode.ACKNOWLEDGED_MESSAGE event
}

const onRejectedCallback = (session) => {
    // I'm overriding the SessionEventCode.REJECTED_MESSAGE_ERROR event
}