Using PubSub+ Cache With the JavaScript API

Client applications can use the Solace Web messaging application programming interface (API) for JavaScript, also known a SolclientJS, to perform cache requests over an event broker network.

The basic steps for a connected client to send and receive cache requests in a session are:

Create a cache session. Refer to Creating Cache Sessions.
Send a cache request. Refer to Sending Cache Requests.
Receive a cache response and any matching cached messages. Refer to Receiving Cache Request Messages.

For information on how to create a session for a client using the JavaScript API, see Creating Client Sessions.

Creating Cache Sessions

When using the JavaScript API, a CacheSession instance must be created with an existing connected Session.

A CacheSession allows multiple outstanding asynchronous cache requests and correlates each response with those requests. Multiple CacheSession objects can be created in a single Session.

To create a CacheSession, call the solace.Session.createCacheSession(...) method with a solace.CacheSessionProperties object. The cache session properties listed in the table below can be set during construction of the properties object or through property accessor methods.

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.
maxAgeSec	The maximum allowable message age (in seconds) to deliver in response to cache requests. A value of 0 means there is no age restriction. The default value is 0.
maxMessages	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 cached messages.
timeoutMsec	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

Cache requests for messages cached for a given topic are sent in CacheSession instances.

When creating a cache request, the client can specify whether it wants to add a subscription to the event broker for the same topic that the cache request is made for. The client can then also begin to receive live data for the topic that it requested cached messages for. The topic subscription is made before the cache request is sent.

The result of a cache request is indicated by return codes that are handled by the specified listener (solace.CacheCBInfo). Any cached messages that are returned for the request are handled through message receive callback (solace.MessageRxCBInfo) associated with the Session that the CacheSession is created in. For more information, see Creating Client Sessions.

It is up to the client application to deal with request timeouts as it is possible that Cache Clusters, event brokers, or individual PubSub+ Cache Instances could 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.

To send an asynchronous cache request for messages published to a specific topic, call solace.CacheSession.sendCacheRequest(...) and pass in the parameters listed below.

Cache Request Message Parameters
Parameter	Description
requestID	A number 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, and, if the `subscribe` parameter is set to `true`, the topic for which a subscription is added to the event broker. 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 is no temporal ordering guarantee between the individual topics returned (although temporal ordering is preserved amongst the messages for a specific topic).
subscribe	If this parameter is set to `true`, add a subscription to the event broker for the topic before sending the cache request. The topic subscription enables the client to receive live data messages that are published to matching topics, after the initial cache request is fulfilled. If the subscription does not succeed for any reason (for example, the subscription already exists and the `ignoreDuplicateSubscriptionError SessionProperty` is set to `false`), the request callback reports `FAIL`, and the request does not proceed.
liveDataAction	Specifies the 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.
cbInfo	The `solace.CacheCBInfo` object that encapsulates the cache session’s request listener callback function and optional application-specified context object. When the cache request completes, the listener is invoked to indicate the completion of the cache request. The returned `solace.CacheRequestResult` provides the methods `getReturnCode()`, `getReturnSubcode()`, and `getTopic()`, which are used to get the return code, possible accompanying subcode, and subscription topic that the request was submitted for.

Cache Return Codes

After the cache request completes, the solace.CacheCBInfo object can return any of the codes listed below. Each return code can have an associated subcode that provides more information.

Cache Request Return Codes and Associated Subcodes
Cache Return Code	Possible Accompanying Subcodes
OK Indicates that: the cache replies were all received before the timer expired cached data was returned in a reply or the request was fulfilled by live data none of the received cached messages were suspect at least one cache had data	Applicable subcodes are: `solace.CacheReturnSubcode.REQUEST_COMPLETE`—The cache request completed successfully. `solace.CacheReturnSubcode.LIVE_DATA_FULFILL`—The cache request completed when live data arrived on the topic requested.
FAIL Indicates that an error occurred during the initial cache request. When a failure occurs, the API does not automatically retry any outstanding requests. In addition, if there is a loss of connection with the event broker, any outstanding requests are canceled.	Applicable subcodes are: `solace.CacheReturnSubcode.ERROR_RESPONSE`—The PubSub+ Cache Instance or session returned an error response to the cache request. `solace.CacheReturnSubcode.INVALID_SESSION`—The cache request failed because the `solace.Sessio`n used to construct it has been destroyed. `solace.CacheReturnSubcode.REQUEST_ALREADY_IN_PROGRESS`—The cache request was made on the same topic as an existing request, and `solace.CacheLiveDataAction.FLOW_THRU` was not set. `solace.CacheReturnSubcode.CACHE_SESSION_DISPOSED`—The cache request was terminated because the cache session was disposed. `solace.CacheReturnSubcode.SUBSCRIPTION_ERROR`—The cache request was terminated because the subscription request for the given topic failed.
INCOMPLETE Indicates that no data or incomplete data has been returned.	`solace.CacheReturnSubcode.NO_DATA`—The returned cache reply did not contain any data. `solace.CacheReturnSubcode.REQUEST_TIMEOUT`—The cache request failed because the request timeout expired. `solace.CacheReturnSubcode.SUSPECT_DATA`—The returned cache data was suspect. The returned cache data is suspect if the cache is in the lost message state.

Receiving Cache Request Messages

Any messages that are returned for the request are handled through message receive callback (solace.MessageRxCBInfo) associated with the session that the cache session is created in. For more information, see Creating Client Sessions.

To determine the status of a cached message that is returned to the callback, call message.getCacheRequestStatus(). The method can return one of the following:

solace.MessageCacheStatus.LIVE—Indicates that the message is live.
solace.MessageCacheStatus.CACHED—Indicates that the message is cached.
solace.MessageCacheStatus.SUSPECT—Indicates that the message is cached, and it is deemed suspect.

If the returned message is CACHED or SUSPECT, the client application can call message.getCacheRequestId() to return the requestID of the cache request associated with this message. For live data, the cache request ID is never set.

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

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

Provide feedback