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, thenwinsock2.h
MUST be included beforesolClient.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 allsolClient_xxx_create()
methods. - For UNIX or Linux systems, ensure that your application linker (typically ‘
ld
’) points to thelibsolclient.so
library file and not any versioned*.so
files found in thelib
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.
- Select Any CPU as a Target Platform for the executable.
- Reference
lib/64/SolaceSystems.Solclient.Messaging.dll
orlib/SolaceSystems.Solclient.Messaging.dll
. - When deploying the executable on a 32-bit machine, make sure to bundle with it
lib/SolaceSystems.Solclient.Messaging.dll
andlib/libsolclient.dll
. - When deploying the executable on a 64-bit machine, make sure to bundle with it
lib/64/SolaceSystems.Solclient.Messaging.dll
andlib/libsolclient_64.dll
.
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:
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.
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.
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
- Alternate Method to Dynamically Link Linux/SunOS/Solaris Applications
- Static Linking with Security Libraries
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.
Applications Using... | Description |
---|---|
Windows |
|
Linux |
|
SunOS/Solaris |
|
Applications Using... | Description |
---|---|
Windows |
|
Linux (Java RTO and C APIs) |
|
SunOS/Solaris |
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.
Applications Using... | Description |
---|---|
Windows |
|
Linux (C API only) |
|
iOS (C API only) |
|
SunOS/Solaris |
|