Code and Compile Guidelines

As you start creating and updating your application code, consider the following guidelines for the messaging API that you are using:

JCSMP 

  • To begin working with JCSMP , import the required packages: com.solacesystems.jcsmp.*

The Solace JCSMP  requires the use of standard Java distribution 1.8 or greater.

Java RTO API

  • To begin working with the Java RTO API, import the required packages: com.solacesystems.solclientj.*

The Solace Java RTO API requires the use of standard Java distribution 1.8 or greater.

C API

  • Ensure that you include all relevant SolClient header files. For a list of all required header files, refer to Products.

    Windows developers should include windows.h before the “include solClient.h” statement. If windows.h is not included, then winsock2.h MUST be included before solClient.h.

  • Examine the sample application code provided in the ex directory to ensure that you use the correct compile and link flags to build your application.
  • The Windows distribution includes Visual Studio 2015 Solution and project files to make it easy to compile the sample codes. Support for other versions of Visual Studio is provided, though only Visual Studio 2015 and above is supported for C API 7.15.0+. For more information, contact Solace.
  • The sample Makefile and Visual Studio 2015 Solution define the macro SOLCLIENT_CONST_PROPERTIES. The use of this macro is recommended for accurate type checking on property arrays passed to all solClient_xxx_create() methods.
  • For UNIX or Linux systems, ensure that your application linker (typically ‘ld’) points to the libsolclient.so library file and not any versioned *.so files found in the lib directory.
  • The iOS distribution includes an Xcode project in the ex directory. The sample application must be compiled from this project. It is recommended to look at this sample project to understand how to link the C API with your application.

.NET API

  • lib/SolaceSystems.Solclient.Messaging.dll
    • The platform target for this assembly is x86
    • At runtime, it requires libsolclient.dll (x86 native dll) to be in the path
    • It has the same strong name as lib/64/SolaceSystems.Solclient.Messaging.dll
  • lib/64/SolaceSystems.Solclient.Messaging.dll
    • The platform target for this assembly is x64.
    • At runtime it requires libsolclient_64.dll (x64 native dll) to be in the path.
    • It has the same strong name as lib/SolaceSystems.Solclient.Messaging.dll.
  • lib/SolaceSystems.Solclient.Messaging_64.dll.
    • The platform target for this assembly is x64.
    • At runtime, it requires libsolclient_64.dll (x86 native dll) to be in the path.
    • It has a different strong name than the rest of the bundled assemblies.
    • When compiling/building against this assembly: the Target Platform of the executable must be x64 (in this case the executable will only run on a 64-bit machine); setting the executable’s Target Platform to Any CPU will produce an executable that can only run on a 64-bit machine.

    To build one executable that is able to run as a 32-bit process on a 32-bit machine and as a 64-bit process on a 64-bit machine (without WOW64), do the following:

    • Select Any CPU as a Target Platform for the executable.
    • Reference lib/64/SolaceSystems.Solclient.Messaging.dll or lib/SolaceSystems.Solclient.Messaging.dll.
    • When deploying the executable on a 32-bit machine, make sure to bundle with it lib/SolaceSystems.Solclient.Messaging.dll and lib/libsolclient.dll.
    • When deploying the executable on a 64-bit machine, make sure to bundle with it lib/64/SolaceSystems.Solclient.Messaging.dll and lib/libsolclient_64.dll.

JavaScript Messaging API

You can use several different variations of the JavaScript Messaging API. The differences between each variation include the available log levels and whether the API is minified.

Minified variations are both smaller and optimized for performance. However, because the available log levels are reduced, debugging these variations can be more difficult. For more information about log levels, see Configuring Logging.

The following table summarizes the available JavaScript Messaging API variations.

JavaScript Messaging API Variations
Variation Minified Available Log Levels
Production Yes INFO, WARN, ERROR, FATAL
Full No INFO, WARN, ERROR, FATAL
Debug No All

To load a JavaScript Messaging API variation, add one of the following statements to the entry point of your application (usually in the <head> section):

  • <script src="solclient.js"></script> for the production variation.
  • <script src="solclient-full.js"></script> for the full variation.
  • <script src="solclient-debug.js"></script> for the debug variation.

The JavaScript Messaging API exports all its functionality through the global solace object.

3rd party library core-js is used is for polyfill browsers and Node.js.

In addition, the JavaScript Messaging API uses timers to send keep alive messages at regular intervals to the event broker. If a client application is only receiving messages, the event broker then relies on the receipt of these keep alive messages to determine the health of that client. However, Internet Explorer suspends its JavaScript timers when a modal dialog window is open, which prevents the API from sending the keep alive messages to the event broker. Therefore, if a modal dialog window in Internet Explorer remains open for longer than the configured inactivity period, the event broker will not receive the required keep alive message, and it will disconnect the client.

To prevent this scenario, avoid using modal dialog boxes in Internet Explorer, or, when their use is necessary, you may configure longer Web transport client inactivity timeouts (refer to Configuring Inactivity Timeouts).

Node.js API

You can use several different variations of the Node.js API. The differences between each variation include the available log levels and whether the API is minified.

Minified variations are both smaller and optimized for performance. However, because the available log levels are reduced, debugging these variations can be more difficult. For more information about log levels, see Configuring Logging.

The following table summarizes the available Node.js API variations.

Node.js API Variations
Variation Minified Available Log Levels
Production Yes INFO, WARN, ERROR, FATAL
Full No INFO, WARN, ERROR, FATAL
Debug No All

To load a Node.js API variation, add one of the following statements to the entry point of your application:

  • var solace = require ("solclientjs").production;.
  • var solace = require ("solclientjs").full;.
  • var solace = require ("solclientjs").debug;.

Guidelines for Secure Connections and Authentication

The following requirements must also be met to successfully code and compile an application that will use TLS/SSL client connections, client certificate authentication, or Kerberos authentication schemes.

JCSMP Messaging API

The JCSMP messaging API requires the use of standard Java distribution 1.8 or greater, which includes Java Secure Socket Extension (JSSE) APIs.

Kerberos Libraries

If your application will use a Kerberos client authentication scheme, the Kerberos libraries in the JVM are used by default. However, if you want to use Kerberos libraries other than those provided by the JVM, add the following system properties. In this case, the Kerberos libraries in the default OS library directory will be used.

-Dsun.security.jgss.native=true
-Djavax.security.auth.useSubjectCredsOnly=false

You can also add the following system property to provide the path to Kerberos libraries located in a location other than the default OS library directory:

-Dsun.security.jgss.lib=<file path to Kerberos library>

Java RTO, C, and .NET Messaging APIs

The Java RTO, C, and .NET APIs support both TLS/SSL security libraries and Kerberos security libraries. (The names of these packages are operating system dependent.)

TLS/SSL Libraries

To allow programmers to quickly develop client applications that create secure connections to event brokers, OpenSSL libraries (including the crypto library) are bundled with the APIs in .a and .so versions (Linux) and .lib and .dll versions (Windows). These libraries allow developers to prototype and test TLS/SSL-encrypted client connections.

The provided libraries are distributed for developers’ convenience and are not endorsed for distribution in a production network. Consult with your Network Operations Center to obtain your organization’s latest secure TLS/SSL packages. OpenSSL distributions can be found at www.openssl.org.

Kerberos Libraries

To develop client applications to use Kerberos authentication, the appropriate Generic Security Service Application Program Interface (GSSAPI) library files must be installed on the development system and on systems that will run the applications. GSSAPI libraries are not bundled with the APIs.

Note that when using the C API, the GSSAPI libraries to use when running on Linux or Solaris systems are set through the SOLCLIENT_GLOBAL_PROP_GSS_KRB_LIB property. If you do not want to use the defined default library, you can change the library specified for this global property.

To successfully link TLS/SSL security libraries or Kerberos security libraries when building your application using the Java RTO, C, and .NET APIs, refer to the following sections:

Recommended Methods for Linking with Security Libraries

The following tables provide information for dynamically linking TLS/SSL libraries and Kerberos libraries with Windows, Linux, and SunOS/Solaris applications.

Dynamically Linking TLS/SSL Libraries
Applications Using... Description

Windows
(Java RTO, C, and .NET APIs)
  • The Java RTO can only use dynamically linked libraries.
  • Whether applications are dynamically linked against libsolclient.dll (the 32‑bit library) or libsolclient_64.dll (the 64-bit library), or they are statically linked against libsolclientStatic.lib (the 32‑bit library) or libsolclient_64Static.lib (the 64-bit library), they must have libeay32.dll and ssleay32.dll available at runtime. Both 32-bit and 64-bit Windows versions of these libraries are included with the C and .NET API distributions to make testing and development easier. When developing your application, ensure that the correct 32-bit versions or 64‑bit versions of libeay32.dll and ssleay32.dll are used when you are testing and deploying.
  • When using Visual Studio, it is not necessary to modify your Visual Studio project because libsolclient dynamically loads the libraries as needed. Applications that do not use TLS/SSL features of libsolclient do not need to deploy the OpenSSL libraries.
  • The latest Windows libraries for OpenSSL can be found at https://wiki.openssl.org/index.php/Binaries.

Linux
(Java RTO and C APIs)
  • The Java RTO API can only use dynamically linked libraries.
  • Whether applications are dynamically linked against libsolclient.so or statically linked against libsolclient.a, they should be built against the TLS/SSL dynamic libraries libssl.so and libcrypto.so to create an application with a dynamic dependency on libssl.so and libcrypto.so. To create this dependency, in the link-edit command (/usr/bin/ld) of your build process, add -lssl -lcrypto to the command line. Your system’s run-time linker will ensure the proper library is linked with your application at run-time. To verify the run-time dependency, execute the command /usr/bin/ldd <application-executable-name>.
  • When your run your application, the TLS/SSL dynamic libraries libssl.so and libcrypto.so must be found in the path defined by the environment variable LD_LIBRARY_PATH.

SunOS/Solaris
(C API only)
  • TLS/SSL is not supported by libsolclient on SunOS or Solaris.

Dynamically Linking Kerberos Libraries
Applications Using... Description

Windows
(Java RTO, C, and .NET APIs)
  • The Java RTO API can only use dynamically linked libraries.
  • Whether applications are dynamically or statically linked against libsolclient.lib, they must have secur32.dll available at runtime. This library is included as part of your operating system distribution and there is no action required to add it.
  • It is not necessary to modify your Visual Studio project because libsolclient dynamically loads the libraries as needed.

Linux (Java RTO and C APIs)
  • The Java RTO API can only use dynamically linked libraries.
  • Whether applications are dynamically linked against libsolclient.so, or statically linked against libsolclient.a, they should be built against the Kerberos/GSS dynamic library libgssapi_krb5.so to create an application with a dynamic dependency on libgssapi_krb5.so. To create this dependency, in the link-edit command (/usr/bin/ld) of your build process, add -lgssapi_krb5 to the command line. Your system’s run-time linker will ensure the proper library is linked with your application at run-time. To verify the run-time dependency, execute the command /usr/bin/ldd <application-executable-name>.
  • When your run your application, the Kerberos dynamic library libgssapi_krb5.so must be found in the path defined by the environment variable LD_LIBRARY_PATH.

SunOS/Solaris
(C API only)
  • Whether applications are dynamically linked against libsolclient.so or statically linked against libsolclient.a, they should be built against the Kerberos/GSS dynamic library mech_krb5.so to create an application with a dynamic dependency on mech_krb5.so. To create this dependency, in the link-edit command (/usr/bin/ld) of your build process, add -lmech_krb5 to the command line. Your system's run-time linker will ensure the proper library is linked with your application at run-time. To verify the run-time dependency, execute the command /usr/bin/ldd <application-executable-name>.
  • When your run your application, the Kerberos dynamic library mech_krb5.so must be found in the path defined by the environment variable LD_LIBRARY_PATH.

Support for Solaris/SunOS is now deprecated and the last release was v7.23.0 (September 2022). For more details, see the Deprecated Features list on the Product Lifecycle Policy page.

Alternate Method to Dynamically Link Linux/SunOS/Solaris Applications

When you build an application as recommended above, it will have a run-time dependency on the required security libraries. If you are using TLS/SSL, this can be verified with /usr/bin/ldd. If you are using Kerberos, the library pointed to the SOLCLIENT_GLOBAL_PROP_GSS_KRB_LIB property will be dynamically loaded at runtime.

When you build an application as recommended above, it also means that the applications will not run on systems where the required libraries are not present. This is not typically an issue because all of the libraries used are automatically deployed in operating system installations.

However, in some cases, you may want to build one binary application that can run when the security libraries are not present as long as features that require these libraries are not used. This is possible and may be simpler for upgrading customers as you do not need to modify your existing build procedure.

If you do not include any extra libraries (other than libsolclient.so or libsolclient.a) in your link-edit step, your application will not have any run-time dependencies. However, libsolclient itself will still attempt to dynamically load the required libraries at run-time if session properties indicates TLS/SSL or GSS is necessary.

Support for Solaris/SunOS is now deprecated and the last release was v7.23.0 (September 2022). For more details, see the Deprecated Features list on the Product Lifecycle Policy page.

Static Linking with Security Libraries

On all operating systems, security libraries may be statically linked with your application when it is built. This is not recommended, as it requires rebuilding or redeploying your Solace application whenever you need to update the security subsystem. It may be useful to deploy an application on target platforms that do not have the required libraries, or the desired versions of the libraries are not present.

The Windows Kerberos interface, which is included in secur32.dll, does not have static library equivalent, and the Kerberos library may not be statically linked into Linux or SunOS/Solaris applications.

The following table provides information for statically linking TLS/SSL libraries with Windows, Linux, and SunOS/Solaris applications.

Statically Linking TLS/SSL Libraries
Applications Using... Description

Windows
(C and .NET APIs)
  • Applications that are dynamically linked against libsolclient.dll or libsolclient_64.dll cannot be statically linked against the TLS/SSL libraries.
  • Applications that are statically linked against libsolclientStatic.lib or libsolclient_64Static.lib may be also statically linked against the TLS/SSL libraries. You must also include the static versions of the TLS/SSL libraries, libeay32.lib and ssleay32.lib. Be sure to find and link against the static versions of these libraries, not the import libraries that have the same name.

Linux (C API only)
  • Whether applications are dynamically linked against libsolclient.so or statically linked against libsolclient.a they may also be built against the TLS/SSL static libraries libssl.a and libcrypto.a. However, to do so you must also include the provided static link enabler object solClientSSLStaticLinkEnable.o.
  • In the link-edit command (/usr/bin/ld) of your build process, you must add ‘solClientSSLStaticLinkEnable.o libcrypto.a libssl.a’ to the command line. These objects must occur after libsolclient.a (or libsolclient.so), and solclientSSLStaticLinkEnable.o must occur before the TLS/SSL libraries.

iOS (C API only)
  • Always statically link against libsolclient.so. libsolclient includes libssl.a and libcrypto.a, so an iOS application does not need any extra steps to create secure connections.

SunOS/Solaris
(C API only)
  • TLS/SSL is not supported by libsolclient on SunOS or Solaris.