使用JavaScript API与PubSub+缓存
客户端应用程序可以使用 Solace Web 消息应用程序编程接口（API）JavaScript，也称为 SolclientJS，通过事件代理网络执行缓存请求。
已连接客户端在会话中发送和接收缓存请求的基本步骤如下：
- 创建缓存会话。参见“创建缓存会话”。
- 发送缓存请求。参见“发送缓存请求”。
- 接收缓存响应以及任何匹配的缓存 消息。参见“接收缓存请求消息”。
有关如何使用 JavaScript API 为客户端创建会话的信息，请参阅“创建客户端会话”。
创建缓存会话
当使用 JavaScript API 时，必须使用现有的已连接会话创建 CacheSession 实例。
CacheSession 允许多个未完成的异步缓存请求，并将每个响应与这些请求相关联。可以在单个会话中创建多个 CacheSession 对象。
要创建 CacheSession，请使用 solace.CacheSessionProperties 对象调用 solace.Session.createCacheSession(...) 方法。可以在构造属性对象期间或通过属性访问器方法设置以下表中列出的缓存会话属性。
| 参数 | 描述 |
|---|---|
| cacheName | 要发送缓存请求的分布式缓存、缓存集群或 PubSub+ 缓存实例的标识名称。 |
| 指定 PubSub+ 缓存实例会绕过缓存请求的冗余和负载均衡。建议指定分布式缓存。 | |
| maxAgeSec | 对缓存请求的响应中允许传递的消息最大年龄（以秒为单位）。值为 0 表示没有年龄限制。默认值为 0。 |
| maxMessages | 对于任何一个主题，要检索的消息的最大数量。如果某个主题的缓存消息数量超过最大值，则返回最新的消息。 |
| 值为 0 时，将检索所有缓存消息。 | |
| timeoutMsec | 等待缓存对缓存请求的响应的时间量（以毫秒为单位）。这是一个每个请求的超时，应用程序发送的每个请求都可能导致多个底层请求。 |
缓存会话属性参数
发送缓存请求
针对给定主题缓存的消息的缓存请求是在 CacheSession 实例中发送的。
在创建缓存请求时，客户端可以指定是否希望为缓存请求所针对的相同主题向事件代理添加订阅。然后，客户端还可以开始接收其请求缓存消息的主题的实时数据。在发送缓存请求之前会建立主题订阅。
缓存请求的结果通过指定的监听器（solace.CacheCBInfo）处理的返回代码表示。请求返回的任何缓存消息都通过与创建 CacheSession 的会话相关联的消息接收回调（solace.MessageRxCBInfo）处理。有关更多信息，请参阅“创建客户端会话”。
客户端应用程序需要处理请求超时问题，因为缓存集群、事件代理或单独的 PubSub+ 缓存实例可能在缓存请求处理过程中失败或断开连接。缓存响应会指示 PubSub+ 缓存实例是否处于丢失消息状态。有关详细信息，请参阅“丢失消息状态”。
要发送针对特定主题发布的异步缓存请求，请调用 solace.CacheSession.sendCacheRequest(...) 并传入下表中列出的参数。
| 参数 | 描述 |
|---|---|
| requestID | 由应用程序提供的数字，在缓存请求响应中返回给应用程序。请求 ID 也包含在返回的每条缓存消息中。 |
| topic | 请求从缓存中获取消息的主题，如果 subscribe 参数设置为 true，则也是向事件代理添加订阅的主题。主题中不支持使用 #noexport。 仅支持 FLOW_THRU 缓存请求的通配符缓存请求。当通配符请求匹配多个缓存主题时，返回的各个主题之间没有时间顺序保证（尽管特定主题的消息之间仍然会保留时间顺序）。 |
| subscribe | 如果此参数设置为 true，则在发送缓存请求之前向事件代理添加该主题的订阅。 主题订阅使客户端能够接收发布到匹配主题的实时数据消息，这些消息是在初始缓存请求完成之后。 如果由于任何原因订阅未成功（例如，订阅已存在且 ignoreDuplicateSubscriptionError SessionProperty 设置为 false），请求回调报告 FAIL，并且请求不会继续。 |
| liveDataAction | 指定在未完成的缓存请求期间接收实时数据消息时要执行的操作： - FLOW_THRU — 立即将匹配缓存请求主题的实时数据消息传递给应用程序。随后匹配的缓存消息也会传递给应用程序。 - FULFILL — 立即将匹配缓存请求主题的实时数据消息传递给应用程序。如果在缓存响应之前收到匹配缓存请求主题的实时数据消息，则丢弃缓存响应。 - QUEUE — 将匹配缓存请求主题的实时数据消息排队，直到收到缓存响应，然后在缓存响应数据之后将实时数据传递给应用程序。 要执行通配符缓存请求，必须为 liveDataAction 参数设置 FLOW_THRU。 |
| cbInfo | 封装缓存会话的请求监听器回调函数和可选的应用程序指定上下文对象的 solace.CacheCBInfo 对象。 当缓存请求完成时，调用监听器以指示缓存请求完成。返回的 solace.CacheRequestResult 提供了 getReturnCode()、getReturnSubcode() 和 getTopic() 方法，这些方法用于获取返回代码、可能的伴随子代码以及提交请求的订阅主题。 |
缓存请求消息参数
缓存返回代码
缓存请求完成后，solace.CacheCBInfo 对象可以返回以下列出的任何代码。每个返回代码都可以有提供更多信息的伴随子代码。
| 缓存返回代码 | 可能的伴随子代码 |
|---|---|
| OK | |
| 表示： |
- 在计时器到期之前收到了所有缓存回复
- 缓存数据在回复中返回，或者请求由实时数据完成
- 接收到的缓存消息中没有可疑消息
- 至少有一个缓存有数据 | 适用的子代码包括：
solace.CacheReturnSubcode.REQUEST_COMPLETE— 缓存请求成功完成。solace.CacheReturnSubcode.LIVE_DATA_FULFILL— 当实时数据到达请求的主题时完成缓存请求。 | | FAIL
表示在初始缓存请求期间发生了错误。
发生故障时，API 不会自动重试任何未完成的请求。此外，如果与事件代理的连接丢失，则取消所有未完成的请求。 | 适用的子代码包括：solace.CacheReturnSubcode.ERROR_RESPONSE— PubSub+ 缓存实例或会话对缓存请求返回了错误响应。solace.CacheReturnSubcode.INVALID_SESSION— 缓存请求失败，因为用于构建它的solace.Session已被销毁。solace.CacheReturnSubcode.REQUEST_ALREADY_IN_PROGRESS— 缓存请求是在现有请求的相同主题上进行的，并且未设置solace.CacheLiveDataAction.FLOW_THRU。solace.CacheReturnSubcode.CACHE_SESSION_DISPOSED— 缓存请求因缓存会话被销毁而终止。solace.CacheReturnSubcode.SUBSCRIPTION_ERROR— 缓存请求因给定主题的订阅请求失败而终止。 | | INCOMPLETE
表示未返回数据或返回了不完整的数据。 | -solace.CacheReturnSubcode.NO_DATA— 返回的缓存回复中没有包含任何数据。solace.CacheReturnSubcode.REQUEST_TIMEOUT— 缓存请求因请求超时而失败。solace.CacheReturnSubcode.SUSPECT_DATA— 返回的缓存数据被认为是可疑的。如果缓存处于丢失消息状态，则返回的缓存数据被认为是可疑的。 |
缓存请求返回代码及关联子代码
接收缓存请求消息
请求返回的任何消息都通过与创建缓存会话的会话相关联的消息接收回调（solace.MessageRxCBInfo）处理。有关更多信息，请参阅“创建客户端会话”。
要确定返回到回调的缓存消息的状态，请调用 message.getCacheRequestStatus()。该方法可以返回以下内容之一：
solace.MessageCacheStatus.LIVE— 表示消息是实时的。solace.MessageCacheStatus.CACHED— 表示消息是缓存的。solace.MessageCacheStatus.SUSPECT— 表示消息是缓存的，并且被认为是可疑的。
如果返回的消息是 CACHED 或 SUSPECT，客户端应用程序可以调用 message.getCacheRequestId() 以返回
与此消息相关的缓存请求的 requestID。对于实时数据，缓存请求 ID 从未设置。
JavaScript API 不会尝试对跨不同缓 存集群接收的缓存消息进行重新排序。此外，API 不会尝试丢弃来自缓存集群或实时发布者的重复消息。
缓存中的消息可能会被缓存捆绑在一起，但消息 API 会单独将它们传递给应用程序。