使用JCSMP API与PubSub+缓存
当客户端应用程序使用 PubSub+ JCSMP API 与 PubSub+ 事件代理建立会话后，可以创建缓存会话并发起针对缓存消息的请求（即缓存请求）。
在会话中发起缓存请求的基本步骤如下：
- 创建缓存会话。参阅创建缓存会话对象。
- 发送缓存请求。参阅发送缓存请求。
- 接收请求的缓存消息。参阅接收缓存消息。
创建缓存会话对象
一旦获取了 JCSMPSession，客户端可以调用 createCacheSession(CacheSessionProperties) 方法，并传入以下缓存会话属性以创建缓存会话对象。
缓存会话对象允许存在多个未完成的缓存请求，并对这些请求进行同步。一个会话可以有多个缓存会话对象。
| 参数 | 描述 |
|---|---|
| cacheName | 要发送缓存请求的分布式缓存、缓存集群或 PubSub+ 缓存实例的标识名称。 |
| 指定 PubSub+ 缓存实例将绕过缓存请求的冗余和负载平衡。建议使用分布式缓存。 | |
| maxMsgAge | 要检索的消息的最大年龄（以秒为单位）。缓存时间超过此时间的消息不会被检索。 |
值为 0 时，将返回主题的所有可能消息，具体由 maxMsgsPerTopic 定义。 | |
| maxMsgsPerTopic | 对于任何一个主题，要检索的最大消息数。如果某个主题上缓存的消息数量超过最大值，则返回最新消息。 |
值为 0 时，将检索所有比 maxMsgAge 新的消息。 | |
| timeout | 等待缓存响应缓存请求的时间量（以毫秒为单位）。这是每个请求的超时时间，应用程序发送的每个请求都可能导致多个底层请求。 |
缓存会话属性参数
发送缓存请求
要发送缓存请求，客户端应用程序必须调用 getMessageProducer(JCSMPStreamingPublishEventHandler) 以从会话中获取 XMLMessageProducer 的实例，以及调用 getMessageConsumer(XMLMessageListener) 以获取 XMLMessageConsumer 的实例。可以在创建缓存会话之前或之后获取 XMLMessageProducer 和 XMLMessageConsumer，但在发送缓存请求之前必须 获取它们。
在缓存会话内，客户端应用程序可以调用 sendCacheRequest(Long, Topic, boolean, CacheLiveDataAction) 以发送阻塞缓存请求，或者调用 sendCacheRequest(Long, Topic, boolean, CacheLiveDataAction, CacheRequestListener) 以在缓存会话中发送非阻塞缓存请求消息。
如果传入参数有误，将抛出 JCSMPException。
客户端需要处理请求超时问题，因为缓存集群、事件代理或单个 PubSub+ 缓存实例可能在缓存请求处理过程中失败或断开连接。缓存响应将指示 PubSub+ 缓存实例是否处于丢失消息状态。有关详细信息，请参阅丢失消息状态。
| 参数 | 描述 |
|---|---|
| requestId | 由应用程序提供的请求的长整型值，用于在 CacheRequestListener 回调和收到的缓存消息中标识原始请求。 |
| topic | 请求缓存数据的主题。主题中不支持使用 #noexport。 |
仅支持 FLOW_THRU 缓存请求的通配符请求。当通配符请求匹配多个缓存主题时，返回的各个主题之间没有时间顺序保证（尽管特定主题的消息之间仍会保留时间顺序）。 | |
| subscribe | 如果此参数设置为 true，则与缓存请求一起向事件代理发送主题的订阅请求。 |
| 通过与缓存请求一起发送订阅，客户端在收到所有缓存消息后将接收相关的实时数据消息。 | |
| liveDataAction | 在未完成的缓存请求期间收到的实时数据消息的枚举操作： |
FLOW_THRU— 立即将匹配缓存请求主题的实时数据消息传递给应用程序。后续匹配的缓存消息也会传递给应用程序。FULFILL— 立即将匹配缓存请求主题的实时数据消息传递给 应用程序。如果在缓存响应之前收到匹配缓存请求主题的实时数据消息，则丢弃缓存响应。QUEUE— 将匹配缓存请求主题的实时数据消息排队，直到收到缓存响应，然后在缓存响应数据之后将实时数据传递给应用程序。
要执行通配符缓存请求，必须为liveDataAction参数设置FLOW_THRU。 | | listener | 要通知缓存请求完成状态的CacheRequestListener。此参数仅对非阻塞缓存请求必需。 |
缓存请求消息参数
发起非阻塞缓存请求后，当请求完成或返回异常时，API 可以调用以下回调方法。
| 方法 | 描述 |
|---|---|
| onComplete(...) | 指示非阻塞缓存请求成功完成。提供相应的请求 ID、订阅主题和缓存请求结果。 |
| 可能的缓存请求结果包括： |
OK— 缓存数据以缓存响应的形式返回，或者请求由实时数据满足。NO_DATA— 返回的缓存响应中未包含任何数据。SUSPECT_DATA— 返回的缓存数据可疑。如果缓存处于丢失消息状态，则返回的缓存数据可疑。 | | onException(...) | 错误中断了非阻塞缓存请求。提供在缓存请求期间发生的相应请求 ID、订阅主题和异常。
如果发生故障，API 不会自动重试任何未完成的缓存请求。此外，如果与事件代理的连接丢失，所有未完成的缓存请求将被取消。 |
返回的非阻塞缓存请求事件可能调用的方法
接收缓存消息
使用 JCSMP 时，接收缓存消息的方法 与其他消息相同，但非阻塞缓存消息需要 CacheRequestListener。有关接收直接消息的更多信息，请参阅在 PubSub+ JCSMP API 中接收直接消息。
消息传递 API 不会尝试对跨不同缓存集群收到的缓存消息进行重新排序。此外，消息传递 API 不会尝试丢弃来自缓存集群或实时发布者的重复消息。
销毁缓存会话
要取消所有未完成的请求并销毁缓存会话对象，请调用 close() 方法。可以从任何线程安全地调用此方法。
调用 close() 时，将发生以下情况：
- 所有未完成的缓存请求将被隐式取消，就像调用
cancel()方法时一样。 - 任何后续缓存请求都将抛出
ClosedFacilityException。
取消缓存请求
要取消所有未完成的请求，而不销毁缓存会话对象，请调用 cancel() 方法。可以从任何线程安全地调用此方法，并且可以多次调用。
调用 cancel() 时，将发生以下情况：
- 所有未完成的缓存请求被取消。
- 所有已排队的实时消息被传递。
- 所有正在进行的同步缓存请求立即通过
JCSMPInterruptedException返回给调用者。 - 所有正在进行的异步缓存请求的
CacheRequestListener onException(...)方法将立即被调用，带有JCSMPInterruptedException。