Working 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 a Solace router network.

The basic steps for a connected client to send and receive cache requests 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 a cache response and any matching cached messages. Refer to Receiving Cache Request Messages.

Note:  For information on how to create a session for a client using the JavaScript API, refer to 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 SolCache Instance to send the cache requests to.

Note:  Specifying a SolCache 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.

Note:  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 router 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, refer to systCreating Client Sessions.)

Note:  It is up to the client application to deal with request timeouts as it is possible that Cache Clusters, Solace routers, or individual SolCache Instances could fail or disconnect in the middle of cache request processing. The cache response indicates whether the SolCache 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 router.

Note:  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 Solace router 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.

Note:  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.

Note:  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.

Note:  When a failure occurs, the API does not automatically retry any outstanding requests. In addition, if there is a loss of connection with the router, any outstanding requests are canceled.

Applicable subcodes are:

  • solace.CacheReturnSubcode.ERROR_RESPONSE—The SolCache Instance or session returned an error response to the cache request.
  • solace.CacheReturnSubcode.INVALID_SESSION—The cache request failed because the solace.Session 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. For example, the returned data might not be complete because the maxMessages cache session property was exceeded.

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, refer to 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.

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