Using PubSub+ Cache With the JCSMP API

When a session has been established with a PubSub+ event broker, a client application using the PubSub+ Message API for JCSMP can create a cache session and then make requests for cached messages (that is, cache requests).

The basic steps to make a cache request in a session are:

1. Create a cache session. Refer to Creating Cache Session Objects.
2. Send a cache request. Refer to Sending Cache Requests.
3. Receive requested cached messages. Refer to Receiving Cached Messages.

Creating Cache Session Objects

Once JCSMPSession is acquired, a client can call the createCacheSession(CacheSessionProperties) method and pass in the cache session properties listed below to create a cache session object.

A cache session object allows multiple outstanding cache requests and synchronizes those requests. A single session can have many cache session objects.

Cache Session Property Parameters

Parameter	Description
cacheName	The identifying name of the Distributed Cache, Cache Cluster, or PubSub+ Cache Instance to send the cache requests to. Specifying a PubSub+ Cache Instance bypasses redundancy and load balancing of cache requests. Specifying the Distributed Cache is the preferred method.
maxMsgAge	The maximum age (in seconds) of the messages to retrieve. Messages that have been cached for more than this amount of time are not retrieved. A value of 0 returns all possible messages for the topic, as defined by maxMsgsPerTopic.
maxMsgsPerTopic	The maximum number of messages to retrieve for any one topic. If more messages are cached on a topic than the maximum value, the newest messages are returned. A value of 0 retrieves all messages newer than maxMsgAge.
timeout	The amount of time (in milliseconds) to wait for a response to the cache request from the cache. This is a per-request timeout where each request sent by the application could result in multiple underlying requests.

Sending Cache Requests

To send a cache request, the client application must call getMessageProducer(JCSMPStreamingPublishEventHandler) to get an instance of XMLMessageProducer and getMessageConsumer(XMLMessageListener) to get an instance of XMLMessageConsumer from the session. XMLMessageProducer and XMLMessageConsumer can be obtained before or after creating a cache session, but they must be obtained before sending a cache request.

Within a cache session, the client application can call sendCacheRequest(Long, Topic, boolean, CacheLiveDataAction) to send a blocking cache request or call sendCacheRequest(Long, Topic, boolean, CacheLiveDataAction, CacheRequestListener) to send a non‑blocking cache request message in the cache session.

If there is an error in the passed parameters, JCSMPException is thrown.

It is up to the client to deal with request timeouts as it is possible that Cache Clusters, event brokers, or individual PubSub+ Cache Instances may fail or disconnect in the middle of cache request processing. The cache response indicates whether the PubSub+ Cache Instance is in a lost message state. Refer to Lost Message State for details.

Cache Request Message Parameters

Parameter	Description
requestId	A long value for a request provided by the application that is used to identify the originating request in the CacheRequestListener callbacks and the received cache messages.
topic	The topic for which data is requested from the cache. Use of #noexport is not supported in the topic. Wildcard cache requests are only supported for FLOW_THRU cache requests. When a wildcard request matches multiple cached subjects, there are no temporal ordering guarantees between the individual topics returned (although temporal ordering will still be preserved amongst the messages for a specific topic).
subscribe	If this parameter is set to true, send a subscription request to the event broker for the topic with the cache request. By sending a subscription with the cache request, the client will receive relevant live data messages after it has received all of the cached messages.
liveDataAction	Enumerated actions to perform on live data messages received during an outstanding cache request: FLOW_THRU—Immediately deliver live data messages matching the cache request topic to the application. Subsequent matching cache messages are also delivered to the application. FULFILL—Immediately deliver live data messages matching the cache request topic to the application. If a live data message matching the cache request topic is received before the cache response, the cache response is discarded. QUEUE—Queue live data messages matching the cache request topic until the cache response is received, and deliver the live data to the application after the cache‑response data. To perform wildcard cache requests, FLOW_THRU must be set for the liveDataAction parameter.
listener	The CacheRequestListener to be notified of the cache request’s completion status. This parameter is only required for a non‑blocking cache request.

After a non‑blocking cache request is made, the API can invoke the callback methods listed below when the request completes or returns an exception.

Possible Methods That Are Invoked for Returned Non-Blocking Cache Request Events

Method	Description
onComplete(...)	Indicates that the non‑blocking cache request completed successfully. The corresponding request ID, subscription topic, and cache request result are provided. The possible cache request results include: OK—Cached data was returned in a cache reply or the request was fulfilled by live data. NO_DATA—The returned cache reply did not contain any data. SUSPECT_DATA—The returned cache data was suspect. The returned cache data is suspect if the cache is in the lost message state.
onException(...)	An error interrupted the non‑blocking cache request. The corresponding request ID, subscription topic, and exception that occurred during the cache request are provided. If a failure occurs, the API does not automatically retry any outstanding cache requests. In addition, if there is a loss of connection with the event broker, any outstanding cache requests are canceled.

Receiving Cached Messages

When using JCSMP, cached messages are received using the same methods as other messages, except that for non‑blocking cache messages a CacheRequestListener is required. For more information on receiving Direct messages, refer to Receiving Direct Messages.

The messaging API does not attempt to reorder cached messages received across different Cache Clusters. In addition, the messaging API does not attempt to drop duplicate messages received from Cache Clusters or live publishers.

Destroying Cache Sessions

To cancel all outstanding requests and destroy the cache session object, call the close() method. It is safe to call this method from any thread.

When close() is called, the following occurs:

• All outstanding cache requests are implicitly cancelled as they are when the cancel() method is called.
• Any subsequent cache requests throw a ClosedFacilityException.

Canceling Cache Requests

To cancel all outstanding requests, without destroying the cache session object, call the cancel() method. It is safe to call this method from any thread, and it can be called repeatedly.

When cancel() is called, the following occurs:

• all outstanding cache requests are canceled
• all live messages that have been queued are delivered
• all in-progress synchronous cache requests immediately return to the caller through a JCSMPInterruptedException
• all in-progress asynchronous cache requests have their CacheRequestListener onException(...) method called immediately with a JCSMPInterruptedException