跳到主要内容

编码和编译指南

当您开始创建和更新应用程序代码时，请考虑以下您所使用的消息 API 的指南：

JCSMP​

  • 要开始使用 JCSMP，请导入所需的包：com.solacesystems.jcsmp.*

Solace JCSMP 需要使用标准 Java 分发版 1.8 或更高版本。

Java RTO API​

  • 要开始使用 Java RTO API，请导入所需的包：com.solacesystems.solclientj.*

Solace Java RTO API 需要使用标准 Java 分发版 1.8 或更高版本。

C API​

  • 确保您包含了所有相关的 SolClient 头文件。有关所有必需头文件的列表，请参阅 PubSub+ 消息 API C 参考。 Windows 开发者应在“include solClient.h”语句之前包含 windows.h。如果未包含 windows.h，则必须在 solClient.h 之前包含 winsock2.h。

  • 查看 ex 目录中提供的示例应用程序代码，以确保您使用正确的编译和链接标志来构建您的应用程序。

  • Windows 发行版包括 Visual Studio 2015 解决方案和项目文件，以便轻松编译示例代码。虽然提供了对其他版本 Visual Studio 的支持，但仅支持 C API 7.15.0+ 的 Visual Studio 2015 及更高版本。有关更多信息，请联系 Solace。

  • 示例 Makefile 和 Visual Studio 2015 解决方案定义了宏 SOLCLIENT_CONST_PROPERTIES。推荐使用此宏，以便对传递给所有 solClient_xxx_create() 方法的属性数组进行准确的类型检查。

  • 对于 UNIX 或 Linux 系统，确保您的应用程序链接器（通常是‘ld’）指向 libsolclient.so 库文件，而不是 lib 目录中找到的任何版本化的 *.so 文件。

  • iOS 发行版在 ex 目录中包含一个 Xcode 项目。必须从该项目编译示例应用程序。建议查看此示例项目，以了解如何将 C API 与您的应用程序链接。

  • Windows 和 macOS 的 C API 发行版附带了 OpenSSL。这些 OpenSSL 二进制文件仅供开发者使用，不应在生产环境中使用。Linux 的 C API 发行版不附带 OpenSSL。

.NET API​

  • 要开始使用 .NET API，请使用您选择的包管理器导入 Solace .NET API NuGet 包，并在您的应用程序中包含以下命名空间：
using SolaceSystems.Solclient.Messaging;

JavaScript 消息 API​

您可以使用 JavaScript 消息 API 的几种不同变体。每个变体之间的差异包括可用的日志级别以及 API 是否经过压缩。

压缩变体更小且经过性能优化。但是，由于可用的日志级别减少，调试这些变体可能更具挑战性。有关日志级别的更多信息，请参阅配置日志记录。

下表总结了可用的 JavaScript 消息 API 变体。

变体压缩可用日志级别
生产是INFO, WARN, ERROR, FATAL
完整否INFO, WARN, ERROR, FATAL
调试否全部

JavaScript 消息 API 变体

要加载 JavaScript 消息 API 变体，请在应用程序的入口点（通常在 <head> 部分）添加以下语句之一：

  • <script src="solclient.js"></script> 用于生产变体。
  • <script src="solclient-full.js"></script> 用于完整变体。
  • <script src="solclient-debug.js"></script> 用于调试变体。

JavaScript 消息 API 通过全局 solace 对象导出其所有功能。

第三方库 core-js 用于为浏览器和 Node.js 提供 polyfill。

此外，JavaScript 消息 API 使用计时器定期向事件代理发送保持活动消息。如果客户端应用程序仅接收消息，则事件代理依赖于这些保持活动消息来确定该客户端的健康状况。然而，Internet Explorer 在模态对话框窗口打开时会暂停其 JavaScript 计时器，这会阻止 API 向事件代理发送保持活动消息。因此，如果 Internet Explorer 中的模态对话框窗口打开时间超过配置的非活动期，事件代理将不会收到所需的保持活动消息，它将断开客户端连接。

为防止这种情况，请避免在 Internet Explorer 中使用模态对话框，或者在必须使用时，您可以配置更长的 Web 传输客户端非活动超时（参阅配置非活动超时）。

Node.js API​

您可以使用 Node.js API 的几种不同变体。每个变体之间的差异包括可用的日志级别以及 API 是否经过压缩。

压缩变体更小且经过性能优化。但是，由于可用的日志级别减少，调试这些变体可能更具挑战性。有关日志级别的更多信息，请参阅配置日志记录。

下表总结了可用的 Node.js API 变体。

变体压缩可用日志级别
生产是INFO, WARN, ERROR, FATAL
完整否INFO, WARN, ERROR, FATAL
调试否全部

Node.js API 变体

要加载 Node.js API 变体，请在应用程序的入口点添加以下语句之一：

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

安全连接和身份验证的指南​

要成功编码和编译将使用 TLS/SSL 客户端连接、客户端证书身份验证或 Kerberos 身份验证方案的应用程序，还必须满足以下要求。

JCSMP 消息 API​

JCSMP 消息 API 需要使用标准 Java 分发版 1.8 或更高版本，其中包含 Java 安全套接字扩展（JSSE）API。

Kerberos 库​

如果您的应用程序将使用 Kerberos 客户端身份验证方案，默认情况下将使用 JVM 中的 Kerberos 库。但是，如果您想使用除 JVM 提供的 Kerberos 库之外的库，请添加以下系统属性。在这种情况下，将使用默认操作系统库目录中的 Kerberos 库。

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

您还可以添加以下系统属性，以提供位于默认操作系统库目录之外的 Kerberos 库的路径：

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

Java RTO、C 和 .NET 消息 API​

Java RTO、C 和 .NET API 支持 TLS/SSL 安全库和 Kerberos 安全库。（这些包的名称取决于操作系统。）

TLS/SSL 库​

为了使程序员能够快速开发创建到事件代理的安全连接的客户端应用程序，API 中捆绑了 OpenSSL 库（包括加密库），分别以 .a 和 .so 版本（Linux）、.lib 和 .dll 版本（Windows）以及 .a 和 .dylib 版本（macOS）提供。这些库允许开发人员原型设计和测试 TLS/SSL 加密的客户端连接。

提供的库是为了开发者方便而分发的，并不推荐在生产网络中分发。请咨询您的网络运营中心，以获取您组织的最新安全 TLS/SSL 包。OpenSSL 发行版可在 www.openssl.org 找到。

Kerberos 库​

要开发使用 Kerberos 身份验证的客户端应用程序，必须在开发系统以及将运行应用程序的系统上安装适当的通用安全服务应用程序编程接口（GSSAPI）库文件。GSSAPI 库不与 API 捆绑。

注意，当使用 C API 时，运行在 Linux 或 Solaris 系统上时使用的 GSSAPI 库通过 SOLCLIENT_GLOBAL_PROP_GSS_KRB_LIB 属性设置。如果您不想使用定义的默认库，您可以更改此全局属性指定的库。

要成功链接 TLS/SSL 安全库或 Kerberos 安全库，当使用 Java RTO、C 和 .NET API 构建您的应用程序时，请参阅以下部分：

  • 推荐的链接安全库的方法
  • Linux/SunOS/Solaris 应用程序的动态链接替代方法
  • 与安全库的静态链接

推荐的链接安全库的方法​

下表提供了有关如何将 TLS/SSL 库和 Kerberos 库与 Windows、Linux 和 SunOS/Solaris 应用程序动态链接的信息。

使用...的应用程序描述
Windows（Java RTO、C 和 .NET API）- Java RTO 只能使用动态链接库。
  • 无论应用程序是动态链接到 libsolclient.dll（32 位库）还是 libsolclient_64.dll（64 位库），还是静态链接到 libsolclientStatic.lib（32 位库）或 libsolclient_64Static.lib（64 位库），它们在运行时都必须有 libeay32.dll 和 ssleay32.dll 可用。这些库的 32 位和 64 位 Windows 版本都包含在 C 和 .NET API 发行版中，以便于测试和开发。在开发您的应用程序时，确保在测试和部署时使用正确的 32 位版本或 64 位版本的 libeay32.dll 和 ssleay32.dll。
  • 当使用 Visual Studio 时，无需修改您的 Visual Studio 项目，因为 libsolclient 会根据需要动态加载库。不使用 libsolclient TLS/SSL 功能的应用程序不需要部署 OpenSSL 库。
  • 最新的 Windows OpenSSL 库可在 https://wiki.openssl.org/index.php/Binaries 找到。 | | Linux（Java RTO 和 C API） | - Java RTO API 只能使用动态链接库。
  • 无论应用程序是动态链接到 libsolclient.so 还是静态链接到 libsolclient.a，它们都应该针对 TLS/SSL 动态库 libssl.so 和 libcrypto.so 进行构建，以创建对 libssl.so 和 libcrypto.so 有动态依赖的应用程序。要创建此依赖，在构建过程的链接编辑命令（/usr/bin/ld）中，将 -lssl -lcrypto 添加到命令行。您的系统运行时链接器将确保在运行时将正确的库与您的应用程序链接。要验证运行时依赖，执行命令 /usr/bin/ldd <application-executable-name>。
  • 当您运行应用程序时，TLS/SSL 动态库 libssl.so 和 libcrypto.so 必须在环境变量 LD_LIBRARY_PATH 定义的路径中找到。 | | SunOS/Solaris（仅 C API） | - libsolclient 在 SunOS 或 Solaris 上不支持 TLS/SSL。 |

动态链接 TLS/SSL 库

使用...的应用程序描述
Windows
（Java RTO、C 和 .NET API）- Java RTO API 只能使用动态链接库。
  • 无论应用程序是动态链接还是静态链接到 libsolclient.lib，它们在运行时都必须有 secur32.dll 可用。此库作为您的操作系统发行版的一部分包含在内，无需采取任何操作即可添加它。
  • 无需修改您的 Visual Studio 项目，因为 libsolclient 会根据需要动态加载库。 | | Linux
    （Java RTO 和 C API） | - Java RTO API 只能使用动态链接库。
  • 无论应用程序是动态链接到 libsolclient.so，还是静态链接到 libsolclient.a，它们都应该针对 Kerberos/GSS 动态库 libgssapi_krb5.so 进行构建，以创建对 libgssapi_krb5.so 有动态依赖的应用程序。要创建此依赖，在构建过程的链接编辑命令（/usr/bin/ld）中，将 -lgssapi_krb5 添加到命令行。您的系统运行时链接器将确保在运行时将正确的库与您的应用程序链接。要验证运行时依赖，执行命令 /usr/bin/ldd <application-executable-name>。
  • 当您运行应用程序时，Kerberos 动态库 libgssapi_krb5.so 必须在环境变量 LD_LIBRARY_PATH 定义的路径中找到。 | | SunOS/Solaris
    （仅 C API） | - 无论应用程序是动态链接到 libsolclient.so 还是静态链接到 libsolclient.a，它们都应该针对 Kerberos/GSS 动态库 mech_krb5.so 进行构建，以创建对 mech_krb5.so 有动态依赖的应用程序。要创建此依赖，在构建过程的链接编辑命令（/usr/bin/ld）中，将 -lmech_krb5 添加到命令行。您的系统运行时链接器将确保在运行时将正确的库与您的应用程序链接。要验证运行时依赖，执行命令 /usr/bin/ldd <application-executable-name>。
  • 当您运行应用程序时，Kerberos 动态库 mech_krb5.so 必须在环境变量 LD_LIBRARY_PATH 定义的路径中找到。
    对 Solaris/SunOS 的支持现已弃用，最后一个版本是 v7.23.0（2022 年 9 月）。有关更多详细信息，请参阅产品生命周期政策页面上的已弃用功能列表。 |

动态链接 Kerberos 库

Linux/SunOS/Solaris 应用程序的动态链接替代方法​

当您按照上述推荐方式构建应用程序时，它将对所需的安全库有运行时依赖。如果您使用 TLS/SSL，可以通过 /usr/bin/ldd 进行验证。如果您使用 Kerberos，SOLCLIENT_GLOBAL_PROP_GSS_KRB_LIB 属性指向的库将在运行时动态加载。

当您按照上述推荐方式构建应用程序时，这也意味着应用程序将在没有所需库的系统上无法运行。这通常不是问题，因为所有使用的库都自动包含在操作系统安装中。

然而，在某些情况下，您可能希望构建一个二进制应用程序，该应用程序可以在安全库不存在时运行，只要不使用需要这些库的功能即可。这是可能的，而且对于升级客户来说可能更简单，因为您无需修改现有的构建过程。

如果您在链接编辑步骤中不包含任何额外的库（除了 libsolclient.so 或 libsolclient.a），您的应用程序将没有任何运行时依赖。然而，libsolclient 本身在运行时仍将尝试动态加载所需的库，如果会话属性表明需要 TLS/SSL 或 GSS。

对 Solaris/SunOS 的支持现已弃用，最后一个版本是 v7.23.0（2022 年 9 月）。有关更多详细信息，请参阅产品生命周期政策页面上的已弃用功能列表。

与安全库的静态链接​

在所有操作系统上，当构建应用程序时，可以将安全库静态链接到您的应用程序。这不推荐，因为每当需要更新安全子系统时，都需要重新构建或重新部署您的 Solace 应用程序。它可能有助于在目标平台上部署应用程序，这些平台没有所需的库，或者所需的库版本不存在。

Windows Kerberos 接口包含在 secur32.dll 中，没有静态库等价物，Kerberos 库不能静态链接到 Linux 或 SunOS/Solaris 应用程序。

下表提供了有关如何将 TLS/SSL 库与 Windows、Linux 和 SunOS/Solaris 应用程序静态链接的信息。

使用...的应用程序描述
Windows（C 和 .NET API）- 动态链接到 libsolclient.dll 或 libsolclient_64.dll 的应用程序不能静态链接到 TLS/SSL 库。
  • 静态链接到 libsolclientStatic.lib 或 libsolclient_64Static.lib 的应用程序也可以静态链接到 TLS/SSL 库。您还必须包括 TLS/SSL 库的静态版本，libeay32.lib 和 ssleay32.lib。确保找到并链接到这些库的静态版本，而不是具有相同名称的导入库。 | | Linux（仅 C API） | - 无论应用程序是动态链接到 libsolclient.so 还是静态链接到 libsolclient.a，它们也可以针对 TLS/SSL 静态库 libssl.a 和 libcrypto.a 进行构建。然而，要这样做，您还必须包括提供的静态链接启用对象 solClientSSLStaticLinkEnable.o。
  • 在构建过程的链接编辑命令（/usr/bin/ld）中，您必须将 ‘solClientSSLStaticLinkEnable.o libcrypto.a libssl.a’ 添加到命令行。这些对象必须出现在 libsolclient.a（或 libsolclient.so）之后，solclientSSLStaticLinkEnable.o 必须出现在 TLS/SSL 库之前。 | | iOS（仅 C API） | - 总是静态链接到 libsolclient.so。libsolclient 包含 libssl.a 和 libcrypto.a，因此 iOS 应用程序不需要额外步骤来创建安全连接。 | | SunOS/Solaris（仅 C API） | - libsolclient 在 SunOS 或 Solaris 上不支持 TLS/SSL。 |

静态链接 TLS/SSL 库