接收直接消息
直接消息可以在会话中传递给客户端，当事件代理为该客户端匹配到主题订阅时。为了接收消息，客户端必须使用适合所用编程语言的消息接收接口或回调/委托。
JCSMP
直接消息通过获取的 XMLMessageConsumer 接口接收。XMLMessageConsumer 可以在异步模式（指定监听器时）或同步模式（未指定消息监听器时）下运行。
| PubSub+ 消息 API | 使用方法 |
|---|---|
| JCSMP | JCSMPSession.getMessageConsumer(XMLMessageListener) |
- 要使用异步消息传递模式，请传入一个
XMLMessageListener回调接口。 - 要使用同步消息传递模式，请将消息监听器设置为
null。
调用 start() 方法后，使用以下方法接收消息：
receive()— 接收下一条可用消息，并等待消息可用。receive(int timeoutInMillis)— 接收下一条可用消息。如果没有消息可用，方法将阻塞，直到设置的时间到期。receiveNoWait()— 接收下一条可用消息，不等待。 |
获取 XMLMessageConsumer
为了使获取的 XMLMessageConsumer 能 够从底层连接读取消息并将消息传递给应用程序，需要调用 XMLMessageConsumer.start()。要停止向应用程序传递消息，请调用 XMLMessageConsumer.stop()。
XMLMessageConsumer 处于“打开”状态，直到调用 XMLMessageConsumer.close() 方法。
Java RTO API
直接消息通过在创建会话时设置的消息接收回调接收。此消息接收回调会针对每条接收到的直接消息被调用。
C API
直接消息通过在创建会话时设置的消息接收回调接收。此消息接收回调会针对每条接收到的直接消息被调用。
选择的消息接收回调决定了使用的消息接口：solClientMsg 接口或已废弃的 solClient_bufInfo_t 接口。未使用的接口需要设置为 NULL。
对于新部署，建议使用 solClientMsg 接口，因为它提供了对额外事件代理功能的访问，例如 SDT 和 PubSub+ 缓存。
.NET API
直接消息通过在创建会话时设置的消息接收委托接收。此消息接收委托会针对每条接收到的直接消息被调用。
JavaScript 和 Node.js API
直接消息通过为 会话定义的 solace.SessionEventCode.MESSAGE 事件的消息监听器接收。
| PubSub+ 消息 API | 设置方式 |
|---|---|
| JCSMP | 不适用 |
| Java RTO | MessageCallback |
| C | solClient_session_rxMsgCallbackFunc_t |
| .NET | EventHandler<MessageEventArgs> |
| JavaScript 和 Node.js | solace.Session.subscribe(...) |
消息接收回调/委托
消息丢弃指示
接收客户端可以使用消息丢弃指示方法或函数查询事件代理是否因任何原因丢弃了当前接收到的消息之前的消息。如果调用返回 true，则事件代理在当前消息之前丢弃了一条或多条消息；如果调用返回 false，则在当前消息之前没有丢失任何消息。
当客户端应用程序检测到消息丢弃发生时，应适当处理此事件。例如，它可以遵循其常规的会话重新初始化过程。
- 如果事件代理的每个客户端出站优先级队列被接收到的消息填满，可能会发生消息丢弃。在这种情况下，队列中最旧的消息可能会被丢弃，以便为新到达的消息腾出空间。在客户端消费消息速度不够快的情况下（即慢速订阅者），每个客户端的出站优先级队列可能会被填满。有关每个客户端出站优先级队列及其配置的更多信息，请参阅消息投递资源。
- 建议在使用消 息裁剪时，消费客户端不要使用丢弃指示。当事件代理的客户端出站优先级队列被接收到的消息填满时，队列中最旧的消息会被丢弃，以为新到达的消息腾出空间，队列头部的消息会被标记为丢弃指示。然而，如果启用了裁剪，该消息可能会被裁剪，客户端将收不到丢弃指示。
| PubSub+ 消息 API | 调用方法 |
|---|---|
| JCSMP | XMLMessage.getDiscardIndication() |
| Java RTO | MessageHandle.getDiscardIndication() |
| C | solClient_msg_isDiscardIndication(...) |
| .NET | IMessage.DiscardIndication |
| JavaScript 和 Node.js | solace.Message.isDiscardIndication() |
查询是否已丢弃消息
使用自定义回调接收特定主题的消息
当使用 Java RTO、C 或 .NET API 时，默认情况下，直接消息会分发到为会话配置的接收回调或委托。然而，您也可以使用特殊的接收回调或委托来处理发布到特定主题的直接消息。此功能也称为主题分发，因为具有特定主题的消息会被分发到特定的回调或委托。
根据主题将消息分发到自定义消息接收回调或委托在匹配的订阅包含通配符时非常有用，因为它可以更精确地分离接收到的消息。例如，如果会话的主题是 part1/>，客户端可能会收到主题为 part1/item1 和 part1/item2 的消息。使用主题分发订阅，您可以为发布到 part1/item1 的消息配置一个接收回调或委托，为发布到 part1/item2 的消息配置另一个。
即使为会话启用了主题分发，创建会话时设置的消息接收回调或委托仍然被使用，并且它作为所有未使用分发选项添加的订阅的默认回调/委托（参阅添加主题订阅）。因此，只有当消息的主题不匹配一个或多个使用主题分发功能/方法添加的订阅时，接收到的消息才会由会话消息接收回调/委托处理。否则，消息将被分发到为这些订阅配置的回调/委托，而不是由默认的会话回调/委托处理。
完全支持主题分发的通配符订阅语法。因此，如果一条消息匹配多个具有配置分发回调/委托的订阅（例如，主题为 part1/item1 的消息匹配订阅主题 part1/item1 和 part1/>），则每个匹配的订阅都会调用一个回调/委托。因此，客户端可能会多次接收和处理同一条消息。（有关订阅支持的主题语法规则的信息，请参阅主题支持与语法。）
如果一条消息不匹配具有特定回调/委托的订阅主题，它将只被分发到默认的会话消息接收回调/委托一次，无论它匹配多少个订阅。
要添加使用主题分发的订阅，必须为会话启用主题分发会话属性。
| PubSub+ 消息 API | 会话属性 |
|---|---|
| JCSMP | 不适用 |
| Java RTO | SessionHandle.PROPERTIES.TOPIC_DISPATCH |
| C | SOLCLIENT_SESSION_PROP_TOPIC_DISPATCH |
| .NET | ISession.TopicDispatch |
| JavaScript 和 Node.js | 不适用 |
如何为会话启用主题分 发
要为特定主题使用分发，请使用以下列出的函数或方法，并执行以下操作：
- 对于 Java RTO API，创建一个
MessageDispatchTargetHandle并将其作为主题订阅传入。 - 对于 C API，传入主题订阅和用于该主题的消息接收回调。
- 对于 .NET API，传入一个
IDispatchTarget对象。IDispatchTarget封装了一个订阅和一个消息接收委托，用于匹配该订阅主题的消息。 - 对于每个 API，您还可以设置可选的订阅标志。
| PubSub+ 消息 API | 调用方法 |
|---|---|
| JCSMP | 不适用 |
| Java RTO | - Solclient.Allocator.newMessageDispatchTargetHandle(...) |
SessionHandle.subscribe(MessageDispatchTargetHandle ...)| | C | solClient_session_topicSubscribeWithDispatch(...) | | .NET | IMessageDispatcher.Subscribe(...)
一个ISession实现了IMessageDispatcher接口。 | | JavaScript 和 Node.js | 不适用 |
如何为订阅使用主题分发
| 标志 | 描述 |
|---|---|
| 请求确认 | 调用应立即返回，并在事件代理完成订阅添加或移除请求后生成确认事件。 |
| 全部单一投递 | 当此标志出现在订阅添加请求中时，它会覆盖消息中的单一投递属性。如果订阅匹配主题的消 息具有全部单一投递标志，消息将被投递给具有这些订阅的客户端，以及一个额外的具有匹配主题订阅但没有全部单一投递覆盖的客户端。 |
| 对于 .NET API，此选项设置为主题属性。 | |
| 等待确认 | 调用应等待直到从事件代理收到确认。 |
| 仅本地分发 | 将主题订阅添加到消息 API 的分发表中，但不添加到事件代理中。 |
可用的主题
分发订阅标志
有关根据订阅主题分发接收到的直接消息的更多信息和示例，请参阅 Java RTO、C 或 .NET 的 PubSub+ 消息 API 参考资料。
相关示例
有关如何为订阅使用主题分发的示例，请参考适用于相应消息 API 的 TopicDispatch 示例。
回复请求消息
为了回复一条传入的请求消息，应用程序可以调用以下列出的方法之一，并提供要回复的请求消息以及回复的消息内容。通常，回复消息的 ReplyTo 地址和相关性 ID 由接收到的请求消息提供。回复方法或函数会自动设置单比特响应属性，并使用与传入请求消息匹配的相关性 ID。
有关发送请求消息的信息，请参阅发布需要回复的消息。
| PubSub+ 消息 API | 调用方法 |
|---|---|
| JCSMP | XMLMessageProducer.sendReply(...) |
| Java RTO | SessionHandle.sendReply(...) |
| C | solClient_session_sendReply(...) |
| .NET | ISession.SendReply(...) |
| JavaScript 和 Node.js | solace.Session.sendReply(...) |
如何发送回复消息
相关示例
有关如何发送和接收请求/回复消息的示例，请参考 Java、Java RTO、C 和 .NET API 的 RRDirectRequester 和 RRDirectReplier 示例。对于 JavaScript 和 Node.js API，请参考 BasicRequestor 和 BasicReplier 示例。