在PubSub+ JCSMP API中设置消息属性

以下部分讨论了一些重要的消息属性，这些属性可以为使用 PubSub+ JCSMP API 发布的消息设置。这些属性会影响消息的路由方式。

要查看可以设置的消息属性的完整列表，请参阅适用于相应消息传递 API 的 PubSub+ 消息传递 API 文档。

传递模式

每个要发布的消息都有一个传递模式。默认情况下，使用直接传递模式。有关详细信息，请参阅消息传递模式。

要设置传递模式，请使用 Message.setDeliveryMode(...) 方法：

TextMessage msg = JCSMPFactory.onlyInstance().createMessage(TextMessage.class);
msg.setDeliveryMode(DeliveryMode.PERSISTENT);

有关如何为消息设置传递模式的示例，请参阅 Solace 开发者中心中的 DirectPubSub 示例。

主题代表一个逻辑目的地。客户端可以向主题目的地发布消息。客户端也可以订阅主题，当事件代理为客户端匹配消息的目的地时，客户端可以接收消息。

主题可以分层组织。因此，支持通配符的主题订阅可以为客户端吸引层次结构的一部分，而无需订阅每个可能的层次级别组合。有关事件代理支持的字符和语法的详细信息，请参阅主题支持和语法。

发布的直接消息根据其设置的主题目的地进行路由。

在 PubSub+ JCSMP API 中，目的地在用于发布消息的发送方法上设置。请参阅在 PubSub+ JCSMP API 中发送直接消息或一次性发送多条消息。

有关如何向主题发布消息的示例，请参阅 Solace 开发者中心中的 DirectPubSub 示例。

当会话连接到事件代理时，您可以使用仅传递给一个（DTO）标志将直接消息发送给单个客户端，即使可能有多个具有适当订阅的客户端能够接收该消息。值为 true 时，会在传出消息上设置此标志。

要设置仅传递给一个消息标志，请使用 XMLMessage.setDeliverToOne(...) 方法：

TextMessage msg = JCSMPFactory.onlyInstance().createMessage(TextMessage.class);
msg.setDeliverToOne(true);

有关如何发布仅传递给一个消息的示例，请参阅 Solace 开发者中心中的 DTOPubSub 示例。

仅传递给一个已被弃用，取而代之的是共享订阅。

您可以将服务等级（COS）级别应用于发布到事件代理的直接消息。COS 值指定消息放置在事件代理上的每个客户端优先级队列中的哪一个，这可能会影响它们从事件代理发送到消费客户端的速率。COS 级别 1 是最低服务等级，COS 级别 3 是最高服务等级。默认值为级别 1。

您必须使用每个 API 提供的数据结构设置 COS 值。不要直接使用整数设置值。

有关每个客户端出站优先级队列的详细信息，请参阅消息传递资源。

要设置服务等级标志，请使用 Message.setCos(...) 方法。

Solace PubSub+ 的消息省略功能使客户端应用程序能够仅以它们能够管理的速率接收它们订阅的主题上发布的最新消息。在存在慢速消费者或需要较低消息速率的情况下，使用消息省略可能会很有用。

要使用消息省略，需要执行以下步骤：

发布的消息必须标记为有资格进行消息省略。
接收客户端应用程序必须通过其客户端用户名分配一个允许其使用消息省略的客户端配置文件。客户端配置文件还设置了一个速率，以控制延迟间隔，即新的省略合格消息省略之前排队等待向客户端投递的先前版本。有关如何配置客户端配置文件并将其分配给客户端的详细信息，请参阅配置客户端身份验证。

要启用消息省略资格，请使用 Message.setElidingEligible(...) 方法：

TextMessage msg = JCSMPFactory.onlyInstance().createMessage(TextMessage.class);
msg.setElidingEligible(true);

消息优先级是保证消息传递的一个功能。事件代理使用消息优先级值按适当顺序投递消息，即高优先级的消息会在低优先级的消息之前发送。有效的优先级值范围是 0-255，其中 0 是最低优先级，255 是最高优先级，但事件代理将所有高于 9 的值视为 9。默认的消息优先级值为 4。

您还可以将消息优先级值应用于发布到事件代理的直接消息。只有同时满足以下两个条件时，才会尊重直接消息的优先级值：

有关详细信息，请参阅消息提升和降级。

当端点配置为强制执行消息优先级时，它增加了在从连接故障中恢复后，向消费客户端投递重复消息的可能性。

要启用消息优先级，请使用 Message.setPriority(...) 方法：

TextMessage msg = JCSMPFactory.onlyInstance().createMessage(TextMessage.class);
msg.setPriority(254);