Using PubSub+ Cache With the Java RTO API

When a session has been established with a Solace PubSub+ event broker, a client application using the Solace messaging application programming interface (API) for Java RTO 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 Sessions.
2. Send a cache request. Refer to Sending Cache Requests.
3. Receive requested cached messages. Refer to Receiving Cached Messages.
4. Destroy the cache session. Refer to Destroying Cache Sessions.

Creating Cache Sessions

A cache session contains static cache properties and cache state information, and it allows multiple outstanding cache requests and synchronizes those requests.

To create a cache session in a connected session, call the sessionHandle.createCacheSessionForHandle(...) function and pass in the cache session properties listed below. A single session can have many cache sessions.

Cache Session Properties

Parameter	Description
CacheSessionHandle.PROPERTIES.CACHE_NAME	The identifying name of the Distributed Cache, Cache Cluster, or PubSub+ Cache Instance to send the cache requests to. Specifying the Distributed Cache is the preferred method because specifying a PubSub+ Cache Instance bypasses redundancy and load balancing of cache requests.
CacheSessionHandle.PROPERTIES.MAX_AGE	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 CacheSessionHandle.PROPERTIES.MAX_MSGS.
CacheSessionHandle.PROPERTIES.MAX_MSGS	The maximum number of cached messages to retrieve for any one topic. If more messages are cached for a topic than the maximum value, the newest messages are returned. A value of 0 retrieves all messages newer than CacheSessionHandle.PROPERTIES.MAX_AGE.
CacheSessionHandle.PROPERTIES.REQUESTREPLY_TIMEOUT_MS	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 blocking or a non-blocking cache request for messages published to a specific topic, call cacheSessionHandle.sendCacheRequest(...) and pass in the parameters listed in the table below.

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 64-bit integer provided by the application that is returned to the application in the cache request response. The request ID is also available in every cached message returned.
topic	The topic for which messages are requested from the cache. Use of #noexport is not supported in the topic. Wildcard cache requests are only supported for FLOWTHRU 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).
cacheRequestFlags	Flags that are used to further define the cache request behavior.
liveDataAction	Additional flags that can be used to define what happens when live data is received during a cache request.
subscribeFlags	The subscription flags for a subscription made through a cache request are the same as those made through a regular topic subscription. For more information, refer to the documentation provided for SolEnum.SubscribeFlags in Java RTO API. When the cache request flag SolEnum.CacheRequest.NO_SUBSCRIBE is set, subscription flags are ignored.

The table below lists the optional flags that can be set on a cache request with the cacheRequestFlags parameter.

Cache Request Flags

Parameter	Description
SolEnum.CacheRequest.NO_ SUBSCRIBE	If this flag is set, do not include a subscription to the event broker with the cache request. Only send a cache request to the Cache Cluster. By default, a subscription is automatically added for the topic then the cache request is added. By adding the subscription, the client will receive relevant live data messages after it has received all of the cached messages.
SolEnum.CacheRequest.NO_WAIT_ REPLY	If this flag is set, the cache request returns immediately with the SolEnum.ReturnCode.IN_PROGRESS event; when the cache request completes, its status is returned through a callback. By default, this flag is not set, and the send cache request function blocks until the cache request is complete.

The table below lists the optional flags that can be set on a cache request with the liveDataAction parameter.

When sending cache requests you must always specify one and only one of the CacheLiveDataAction flag options (there is no default).

Live Data Action Flags

Parameter	Description
SolEnum.CacheLiveDataAction.FULFILL	If this flag is set, when live data that matches the outstanding cache request topic arrives before the cache response, allow the live data to fulfill the cache request. Any subsequent matching cached data messages are discarded.
SolEnum.CacheLiveDataAction.QUEUE	If this flag is set, queue received live data messages that match the cache request topic until the cache request completes.
SolEnum.CacheLiveDataAction.FLOWTHRU	If this flag is set, received live data messages that match the cache request topic are passed through to the application. A cache request can remain outstanding while live data messages are being passed through. The subsequent matching cached data messages are also delivered to the application. The SolEnum.CacheLiveDataAction.FLOWTHRU flag must be set for wildcard cache requests.

Receiving Cached Messages

When using the Java RTO API, cached messages are received through the message callback defined in the SessionHandle from which the current CacheSessionHandle was created. For more information on receiving direct messages, refer to Receiving Direct Messages.

Messages in cache responses may be bundled together by the cache, but they are delivered to applications individually by the messaging API.

If an application registers an event callback with cache requests flagged as SolEnum.CacheRequest.NO_WAIT_REPLY (that is, non-blocking), the cache request status is returned through a callback.

The following table lists the return codes that can be returned. Although these codes are also returned for non-cache request API calls for clients connecting to an event broker, the provided descriptions indicate what the events signify for a cache request.

Cache Request Events

Event	Description
SolEnum.ReturnCode.OK	Indicates that: the cache replies were all received before the timer expired none of the received cached messages were suspect at least one cache reply had data
SolEnum.ReturnCode.INCOMPLETE	Indicates that incomplete data has been returned. Reasons might include: all of the cache replies contained no data at least one message was suspect
SolEnum.ReturnCode.FAIL	Indicates that an error occurred during the initial cache request. Possible reasons include: timeout waiting for a cache response a cache error response an add subscription error response a transport error when communicating with the event broker If an error occurs after the initial cache request (for example, when communicating with other PubSub+ Cache instances in the Cache Cluster), then SolEnum.ReturnCode.INCOMPLETE is returned. 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.

Destroying Cache Sessions

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

When CacheSessionHandle.destroy() is called, the following occurs:

• all outstanding cache requests are canceled
• live messages that have been queued are delivered
• all blocked synchronous cache requests return immediately with an INCOMPLETE return code, a PARAM_NULL_PTR subcode, and a “Cache session has been destroyed” error string
• no event is generated for in-progress asynchronous cache requests

Canceling Cache Requests

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

When CacheSessionHandle.cancelCacheRequests() is called, the following occurs:

• all outstanding cache requests are canceled
• all live messages that have been queued are delivered
• all blocked synchronous cache requests return immediately with an INCOMPLETE return code and a CACHE_REQUEST_CANCELLED subcode
• a REQUEST_COMPLETED_NOTICE cache event with a subcode of CACHE_REQUEST_CANCELLED is generated for each in‑progress asynchronous cache request