Code and Compile Guidelines

As you start creating and updating your application code, consider the following guidelines:

  • To begin working with the Solace 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.

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.

The Solace Java RTO API supports 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 API in .a and .so versions (Linux), .lib and .dll versions (Windows), and in .a and .dylib versions (macOS). 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 API.

To successfully link TLS/SSL security libraries or Kerberos security libraries when building your application, 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 and Linux applications.

Dynamically Linking TLS/SSL Libraries
Applications Using. Description

Windows
(Solace Java RTO API)
  • The Solace Java RTO API 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), 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 Solace Java RTO API distribution 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.
  • The latest Windows libraries for OpenSSL can be found at https://wiki.openssl.org/index.php/Binaries.

Linux
(Solace Java RTO API)
  • The Solace Java RTO API can only use dynamically linked libraries.
  • Applications are dynamically linked against libsolclient.so and 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.

Dynamically Linking Kerberos Libraries
Applications Using. Description

Windows
(Solace Java RTO API)
  • The Solace Java RTO API can only use dynamically linked libraries.
  • Applications are dynamically linked against libsolclient.lib and 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.

Linux (Solace Java RTO API)
  • The Solace Java RTO API can only use dynamically linked libraries.
  • Applications are dynamically linked against libsolclient.so and 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.

Alternate Method to Dynamically Link Linux 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.

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) 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.