Using PubSub+ Cache With the .NET API

This section describes how to develop applications using the messaging application programming interface (API) for .Net, also known as SolClient for .NET, to perform cache requests over an event broker network.

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 message. Refer to Sending Cache Requests.
3. Receive requested cached messages. Refer to Receiving Cached Messages.
4. Destroy the cache session object when done with cache requests. Refer to Destroying Cache Sessions.

Creating Cache Sessions

Once JCSMPSession is acquired, a client can call the createCacheSession(CacheSessionProperties) method and pass in the cache session properties listed in the Cache Session Property Parameters table 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.

CacheSessionProperties cacheProps = new CacheSessionProperties();
cacheProps.CacheName = cacheName;
cacheProps.MaxMessagesPerTopic = maxMsgs;cacheProps.MaxMessageAgeInSecs = maxAge;
cacheProps.CacheRequestTimeoutInMsecs = timeout;
ICacheSession cacheSession

Then, using a session instance reference, invoke the CreateCacheSession() method and pass in the cache session properties, as follows:

session.CreateCacheSession(cacheProps);

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.
CacheRequestTimeoutInMsecs	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.
MaxMessageAgeInSecs	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 MaxMessagesPerTopic.
MaxMessagesPerTopic	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 MaxMessagesPerTopic.

Sending Cache Requests

An application can send a cache request message by invoking one of the following methods on ICacheSession:

• ReturnCode SendCacheRequest(Int64 requestId, ITopic topic, bool subscribe, CacheLiveDataAction liveDataAction)

  A synchronous cache request. When this method is invoked, the API waits for the cache response to be fulfilled according to the CacheLiveDataAction handling options.

• ReturnCode SendCacheRequest(Int64 requestId, ITopic topic, bool subscribe, CacheLiveDataAction liveDataAction, EventHandler<CacheRequestEventArgs> cacheRequestListener)

  An asynchronous cache request. When this method is invoked, the API returns immediately upon successful buffering of the cache request for transmission. The result of the request is reported through the cacheRequestListener.

When the client application sends a cache request message, it must provide the parameters listed below.

Cache Request Message Parameters

Parameter	Description
requestId	A positive Int64 that is returned to the application in the cache request response. The request ID is available in every cached message returned.
topic	An ITopic instance that represents the topic 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).
liveDataAction	Enumerated actions to perform on receiving a live data message during an outstanding cache request. The possible actions include: FULFILL—Deliver live data matching the cache request to the application immediately. The subsequent cache response is discarded. QUEUE—Queue live data matching the cache request topic until the cache-response is received, and deliver the matching live data to the application after the cache response data. Live data not matching an outstanding cache request is immediately delivered to the application. FLOW_THRU—Deliver live data matching the cache request to the application immediately. The subsequent cache response is also delivered. Wildcard cache requests must be FLOW_THRU.
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.
cacheRequestListener	The delegate for reporting cache request completion status. This parameter is only used for asynchronous cache requests.

Receiving Cached Messages

Cached messages are received through the EventHandler<MessageEventArgs> delegate.

The API does not attempt to reorder cached messages that are 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.

If an application registers an event callback delegate with a non-blocking cache request, the cache request status is returned in the return code of the CacheRequest EventArg.

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
SOLCLIENT_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
SOLCLIENT_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
SOLCLIENT_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 further cache instances in the Cache Cluster), then SOLCLIENT_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 ICacheSession.Dispose() method. It is safe to call this method from any thread.

When Dispose() is called, the following occurs:

• all outstanding cache requests are cancelled
• live messages that have been queued are delivered
• all blocked synchronous cache requests return immediately with an SOLCLIENT_INCOMPLETE return code, a ParamNullReference 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 ICacheSession.CacheRequestCancelled() method. It is safe to call this method from any thread, and it can be called repeatedly.

When CacheRequestCancelled() 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 a SOLCLIENT_INCOMPLETE return code and a CacheRequestCancelled subcode
• a cache event RequestCompletedNotice with a subcode of CacheRequestCancelled is generated for each in‑progress asynchronous cache request