Checking Solace Message Router Capabilities

Each Solace Message Router can support both direct messaging and guaranteed messaging, with the latter providing more capabilities and features to applications, such as dynamic queue provisioning, queue browsing, etc. Moreover, administrators can configure an appliance to prevent an application from, for example, creating queues on one Message VPN while granting permissions on another. If you’re new to Solace messaging, refer to the Solace Core Concepts for some background on Solace messaging in general and direct vs guaranteed messaging in particular.

In this post I will show how applications can query a Solace Message Router to discover some of these capabilities so applications can make intelligent decisions dynamically, and take appropriate action when a capability is not available on the Message VPN or Solace Message Router they are connecting to. I will also explain how to detect these capabilities using the Solace Java API. Detecting capabilities also allows applications to be more portable when moving from one environment to another, for example moving the application from development to QA to production. Similar features are also available in other Solace APIs, and I will make references to the Solace documentation when necessary for other programming languages.

Understanding Router Capability Detection

When an application connects to a Solace Message Router, the Solace APIs exchange information with the Solace Message Router to understand its capabilities, which are available to the application via the connected Session, as illustrated in the sequence diagram below. These capabilities are determined by factors such as the router hardware, the SolOS version running on the router, and by the feature configuration an administrator has applied to the router.

Once a session is successfully established, applications can use Solace API methods to retrieve the Solace message router capabilities as a set of properties. This can include system level capabilities such as the maximum guaranteed and direct message sizes, the SolOS version used, and the software release date.

The sequence diagram below illustrates the interaction between the Application, the Solace API, and the Solace Message Router when detecting router capabilities.

It is important to note here that configuration changes which affect router capabilities, made after an application has successfully connected to the router, are not communicated to the application. The application will only learn of the new capabilities if it disconnects and reconnects. For example, in the below sequence diagram, an admin allows an application to publish messages using Persistent Delivery Mode after it has established a session to the Solace Message Router. The application can only learn of the change after it has reconnected.

Available Capabilities

The section “Detecting Router Capabilities” in the Solace Messaging API Developer Guide lists the possible router capabilities available from Solace APIs. The complete list of router features can also be found in the Solace API Java documentation.

In the table below I have summarized a subset of important capabilities and the possible uses cases when you might want to check them from your applications. Most of the capabilities in the table below are determined by the client-profile assigned to the application’s connection username, and can be enabled/disabled administratively for each client-profile in a VPN.

How to Detect Router Capabilities

Here I will show you how to retrieve and check capabilities from a connected session using the Solace Java API. The following two methods are available to either check if a feature is enabled, or get the value of a specific capability:

• getCapability(...)
• isCapable(...)

The isCapable() method returns a true or false indicating whether the feature is enabled or not, whereas the getCapability() methods returns the value as an Object.

The following code snippet shows an example if I want my application to check if it can send Guaranteed Messages or not.

final JCSMPProperties properties = new JCSMPProperties();
/* Setting connection properties omitted here */
final JCSMPSession session = JCSMPFactory.onlyInstance().createSession(properties);
session.connect();

if (session.isCapable(CapabilityType.PUB_GUARANTEED)) {
    System.out.println("Allowed - Guaranteed Publish");
} else {
    System.out.println("Not Allowed - Guaranteed Publish");
}

If the return type of the capability cannot be converted to a Boolean data type then the Solace Java API will throw an IllegalArgumentException exception. Therefore, developers should ensure when using the isCapable() method, that the return type of the capability can be converted to a Boolean. Refer to the Solace Java API documentation here for the specific return type of all the capabilities available.

The following code snippet shows an example if I want my application to retrieve a capability value such as the SolOS Version.

final JCSMPProperties properties = new JCSMPProperties();
/* Setting connection properties omitted here */
final JCSMPSession session = JCSMPFactory.onlyInstance().createSession(properties);
session.connect();

try {
    String version = 
        (String)session.getCapability(CapabilityType.PEER_SOFTWARE_VERSION);
} catch (JCSMPOperationException ex)
{
    // Error Handling - Session may not be connected
}

If the Session has never been connected, requesting a capability using the above method will throw JCSMPOperationException. Application should handle this exception whenever using this method.

For the method name in other Solace APIs refer to the section “Detecting Router Capabilities” in the Solace Messaging API Developer Guide.

Putting It All Together

The complete source code, with detection for the capabilities listed in the table previously in this post, can be downloaded here. This sample builds on the source code provided with the Getting Started Publish/Subscribe (Java) tutorial.

Building this example is simple. The following provides an example using Linux. These instructions assume you have unpacked the Solace Java API into a directory next to the getting started samples that you just downloaded. There are many suitable ways to build and execute these samples in Java. Adapt these instructions to suit your needs depending on your environment.

In the following example replace VERSION with the Solace API version you downloaded.

javac -cp sol-jcsmp-VERSION/lib/*:. CapabilityDetection.java

Run the example from the command line as follows.

java -cp sol-jcsmp-VERSION/lib/*:. CapabilityDetection HOST

Summary

Detecting the Solace Message Router capabilities dynamically from an application can be very useful, especially when using a Guaranteed Messaging Platform, as it makes the application more portable when moving from one environment to another. Application developers may not necessarily know the Solace Message Router hardware or capabilities available in an environment as the application progresses from one team to another through development lifecycle. By implementing capability detection, applications can make intelligent decisions, such as raising an alert to notify operations, or dynamically choosing the correct SEMP query version to send to the Solace Message Router. I also explained how to perform such detection using the Solace Java API and the proper exceptions to handle.