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.
blog-checking-capabilities-1

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.
blog-checking-capabilities-2

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.

CapabilityPossible Use Cases for Applications
Guaranteed Publishing FlowCheck this if the application is publishing messages using the Persistent Delivery mode. If disabled the published message will be rejected and discarded by the Solace Message Router.
Guaranteed Subscription FlowCheck this if the application is consuming messages from Endpoints such as Queue or a Topic Endpoint. If disabled the application won’t be able to bind to Endpoints.
Endpoint ManagementCheck this if the application creates and deletes Endpoints, such as Queues, dynamically. For example, a management application provisioning queues dynamically for other business applications should do this check.
Queue BrowserCheck this if the application uses a Queue Browser to browse messages on Queue Endpoints.
Transacted SessionCheck this is the application is using local transaction to publish and consume persistent messages. Only available in the Solace C & .NET APIs. Currently the Solace Java API does not have this capability detection but does support local transactions.
SolOS VersionRetrieve and check this if the application is sending SEMP queries to the Solace Message Router. SEMP queries require a version no and are not necessarily forward compatible. So for example, your application is using SEMP to configure and monitor multiple Solace Routers, where each router maybe on a different SolOS version, then the application can use this capability and dynamically adjust the SEMP query based on the SolOS version.
On-Behalf-Of (OBO) Subscription ManagerCheck this if the application is an OBO Subscription Manager that adds and removes topic subscriptions on behalf of other clients.

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.

DIshant Langayan

Dishant joined Solace in 2011 as Senior Professional Services Consultant and since then has helped several customers with making the most of their Solace products. Since then he has worked with stock exchanges and several investment banks playing a key role in helping accelerate the customer's moving to a Solace messaging platform, delivering innovative solutions while still leveraging the their legacy system investments. Dishant holds a Master of Computer Science degree from University of Ottawa (Canada), and Bachelor of Computer Science and Engineering degree from University of Solapur (India).