com.solacesystems.solclientj.core.handle

Interface CacheSessionHandle

All Superinterfaces:

Handle

public interface CacheSessionHandle
extends Handle

The CacheSessionHandle interface allows applications to send messages to a Solace Cache Cluster. Applications that need this interface must instantiate an object with the CacheSessionHandle interface by calling Solclient.Allocator.newCacheSessionHandle

The CacheSessionHandle must be associated with a native CacheSession object by calling SessionHandle.createCacheSessionForHandle()

A single SessionHandle may have many SolCache objects. Messages that are retrieved from the cache are received in the usual SessionHandle MessageCallback function.

Events generated by asynchronous cache requests are seen in the CacheSessionEventCallback

See Also:

Handle

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	CacheSessionHandle.PROPERTIES Defines the property names used to create a Session handle

Method Summary

Modifier and Type	Method and Description
int	cancelCacheRequests() Cancel all in progress cache requests for a given cache session.
CacheSessionEvent	getCacheSessionEvent() This method returns a CacheSessionEvent instance in the context of CacheSessionEventCallback.onCacheSessionEvent(CacheSessionHandle)
int	sendCacheRequest(long requestId, java.nio.ByteBuffer topic, int cacheRequestFlags, int liveDataAction, int subscribeFlags) Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into CacheSessionHandle.sendCacheRequest(long, Topic, int, int, int).
int	sendCacheRequest(long requestId, Topic topic, int cacheRequestFlags, int liveDataAction, int subscribeFlags) Sends a cache request.
void	takeCacheSessionEvent(CacheSessionEvent cacheSessionEvent) This method clones the last CacheSessionEvent into the given CacheSessionEvent The given CacheSessionEvent is implementation specific and is expected to be the one produced by Allocator.newCacheSessionEvent() This call is valid while on the same thread and in context of CacheSessionEventCallback.onCacheSessionEvent() .

Methods inherited from interface com.solacesystems.solclientj.core.handle.Handle

destroy, isBound

Method Detail

cancelCacheRequests

int cancelCacheRequests()
                 throws SolclientException

Cancel all in progress cache requests for a given cache session. This function is thread safe and can be called from any thread

Returns:

SolEnum.ReturnCode

Throws:

SolclientException

sendCacheRequest

int sendCacheRequest(long requestId,
                     Topic topic,
                     int cacheRequestFlags,
                     int liveDataAction,
                     int subscribeFlags)
              throws SolclientException

Sends a cache request. If the cache request flag SolEnum.CacheRequest.NO_WAIT_REPLY is set, this function returns SolEnum.ReturnCode.IN_PROGRESS immediately upon successful buffering of the message for transmission. Otherwise this function waits for the cache response to be fulfilled according to the liveDataAction handling options. When the function waits for the cache response the cache event callback is not invoked.

Irrespective of the cache request flag, SolEnum.CacheRequest.NO_WAIT_REPLY, cache requests may be flow controlled if the underlying transport is flow controlled. The transport is considered flow controlled if the library is unable to write to the transport device (for example, the TCP socket is full), or if there are more than 1000 session requests (SessionHandle.sendRequest + CacheSessionHandle.sendCacheRequest()) outstanding. This causes CacheSessionHandle.sendCacheRequest to block if the session property, SessionHandle.PROPERTIES.SEND_BLOCKING is enabled. If SessionHandle.PROPERTIES.SEND_BLOCKING is disabled and it is not possible to write the cache request to the underlying transport, SolEnum.ReturnCode.WOULD_BLOCK is returned.

Cached messages received in response to the cache request are delivered to the application through the usual receive message callback as the messages arrive. This function returns when all cache responses have been received, or the request is either completed by live data (SolEnum.CacheLiveDataAction.FULFILL) or by a timeout. If, and only if, SolEnum.CacheRequest.NO_WAIT_REPLY is set, the cache request callback is invoked when any of these terminating conditions occurs.

Parameters:

requestId - - A unique identifier returned to the application in the CacheSessionEvent; it is also available in every cached message returned.

topic - - The topic being requested from the cache.

cacheRequestFlags - SolEnum.CacheRequest modify the cache request behavior.

liveDataAction - SolEnum.CacheLiveDataAction modify the cache request behavior.

subscribeFlags - SolEnum.SubscribeFlags control the subscribe operation when the cache request sends a subscription as well.

Returns:

SolEnum.ReturnCode : OK , NOT_READY , INCOMPLETE , IN_PROGRESS , WOULD_BLOCK

Throws:

SolclientException - This function can throw an exceptionL for any of the following reasons:

• SolEnum.SubCode.CACHE_INVALID_SESSION - the underlying session in which the cacheSession was created has been destroyed.
• SolEnum.SubCode.INVALID_TOPIC_SYNTAX - the topic is invalid.
• SolEnum.SubCode.TOPIC_TOO_LARGE - the topic exceeds the maximum length.

When the SolEnum.CacheRequest.NO_WAIT_REPLY is set in cacheRequestFlags, the function returns SolEnum.ReturnCode.IN_PROGRESS and the subsequent callback indicates the final status of the cache request. Otherwise the return code indicates the status of the cache request. SolEnum.ReturnCode.OK , is returned when the cache request completes successfully and valid data is delivered. The SolEnum.SubCode is never set when SolEnum.ReturnCode.OK is returned. SolEnum.ReturnCode.INCOMPLETE may be returned if the cacheRequest or initial subscription request is sent but not completed successfully.

• SolEnum.SubCode.CACHE_TIMEOUT - the timeout specified by CacheSessionHandle.PROPERTIES.REQUESTREPLY_TIMEOUT_MS expired.
• SolEnum.SubCode.PROTOCOL_ERROR - the cache response is malformed.
• SolEnum.SubCode.CACHE_ERROR_RESPONSE - the cache responded with an error response.
• SolEnum.SubCode.CACHE_SUSPECT_DATA - at least one suspect message was received in response.
• SolEnum.SubCode.CACHE_NO_DATA - the cache request completed successfully with no suspect responses, but no data matching the cache request was found.
• SolEnum.SubCode.CACHE_REQUEST_CANCELLED - the cache request has been cancelled.
• SolEnum.SubCode.PARAM_NULL_PTR - the cache session has been destroyed.
• SolEnum.SubCode.CACHE_INVALID_SESSION - the underlying session in which the cacheSession was created has been destroyed.

See Also:

SolEnum.SubCode

sendCacheRequest

@Deprecated
int sendCacheRequest(long requestId,
                                 java.nio.ByteBuffer topic,
                                 int cacheRequestFlags,
                                 int liveDataAction,
                                 int subscribeFlags)
                          throws SolclientException

Deprecated. Applications should use a MutableTopic. A MutableTopic may be set/changed by the application as needed. The MutableTopic can then be passed into CacheSessionHandle.sendCacheRequest(long, Topic, int, int, int).

Sends a cache request. If the cache request flag SolEnum.CacheRequest.NO_WAIT_REPLY is set, this function returns SolEnum.ReturnCode.IN_PROGRESS immediately upon successful buffering of the message for transmission. Otherwise this function waits for the cache response to be fulfilled according to the liveDataAction handling options. When the function waits for the cache response the cache event callback is not invoked.

Irrespective of the cache request flag, SolEnum.CacheRequest.NO_WAIT_REPLY, cache requests may be flow controlled if the underlying transport is flow controlled. The transport is considered flow controlled if the library is unable to write to the transport device (for example, the TCP socket is full), or if there are more than 1000 session requests (SessionHandle.sendRequest + CacheSessionHandle.sendCacheRequest()) outstanding. This causes CacheSessionHandle.sendCacheRequest to block if the session property, SessionHandle.PROPERTIES.SEND_BLOCKING is enabled. If SessionHandle.PROPERTIES.SEND_BLOCKING is disabled and it is not possible to write the cache request to the underlying transport, SolEnum.ReturnCode.WOULD_BLOCK is returned.

Cached messages received in response to the cache request are delivered to the application through the usual receive message callback as the messages arrive. This function returns when all cache responses have been received, or the request is either completed by live data (SolEnum.CacheLiveDataAction.FULFILL) or by a timeout. If, and only if, SolEnum.CacheRequest.NO_WAIT_REPLY is set, the cache request callback is invoked when any of these terminating conditions occurs.

Parameters:

requestId - - A unique identifier returned to the application in the CacheSessionEvent; it is also available in every cached message returned.

topic - - The topic being requested from the cache. This is a ByteBuffer (java.nio.ByteBuffer) that contains a topic. The topic must be a UTF-8 represention of the topic string. The data from the Buffer.position() to the Buffer.limit() is used to construct the subscription. It does not need to be null terminated. The Buffer.position() is updated before return.

cacheRequestFlags - SolEnum.CacheRequest modify the cache request behavior.

liveDataAction - SolEnum.CacheLiveDataAction modify the cache request behavior.

subscribeFlags - SolEnum.SubscribeFlags control the subscribe operation when the cache request sends a subscription as well.

Returns:

SolEnum.ReturnCode : OK , NOT_READY , INCOMPLETE , IN_PROGRESS , WOULD_BLOCK

Throws:

SolclientException - This function can throw an exceptionL for any of the following reasons:

• SolEnum.SubCode.CACHE_INVALID_SESSION - the underlying session in which the cacheSession was created has been destroyed.
• SolEnum.SubCode.INVALID_TOPIC_SYNTAX - the topic is invalid.
• SolEnum.SubCode.TOPIC_TOO_LARGE - the topic exceeds the maximum length.

When the SolEnum.CacheRequest.NO_WAIT_REPLY is set in cacheRequestFlags, the function returns SolEnum.ReturnCode.IN_PROGRESS and the subsequent callback indicates the final status of the cache request. Otherwise the return code indicates the status of the cache request. SolEnum.ReturnCode.OK , is returned when the cache request completes successfully and valid data is delivered. The SolEnum.SubCode is never set when SolEnum.ReturnCode.OK is returned. SolEnum.ReturnCode.INCOMPLETE may be returned if the cacheRequest or initial subscription request is sent but not completed successfully.

• SolEnum.SubCode.CACHE_TIMEOUT - the timeout specified by CacheSessionHandle.PROPERTIES.REQUESTREPLY_TIMEOUT_MS expired.
• SolEnum.SubCode.PROTOCOL_ERROR - the cache response is malformed.
• SolEnum.SubCode.CACHE_ERROR_RESPONSE - the cache responded with an error response.
• SolEnum.SubCode.CACHE_SUSPECT_DATA - at least one suspect message was received in response.
• SolEnum.SubCode.CACHE_NO_DATA - the cache request completed successfully with no suspect responses, but no data matching the cache request was found.
• SolEnum.SubCode.CACHE_REQUEST_CANCELLED - the cache request has been cancelled.
• SolEnum.SubCode.PARAM_NULL_PTR - the cache session has been destroyed.
• SolEnum.SubCode.CACHE_INVALID_SESSION - the underlying session in which the cacheSession was created has been destroyed.

See Also:

SolEnum.SubCode

getCacheSessionEvent

CacheSessionEvent getCacheSessionEvent()

This method returns a CacheSessionEvent instance in the context of CacheSessionEventCallback.onCacheSessionEvent(CacheSessionHandle)

Returns:

CacheSessionEvent

takeCacheSessionEvent

void takeCacheSessionEvent(CacheSessionEvent cacheSessionEvent)

This method clones the last CacheSessionEvent into the given CacheSessionEvent

• The given CacheSessionEvent is implementation specific and is expected to be the one produced by Allocator.newCacheSessionEvent()
• This call is valid while on the same thread and in context of CacheSessionEventCallback.onCacheSessionEvent() .

Parameters:

cacheSessionEvent - a CacheSessionEvent produced by Allocator.newCacheSessionEvent()