Version: 10.17.1
Class

solace.Session

Contents

class solace.Session

This class is not exposed for construction by API users. Applications must use solace.SolclientFactory.createSession to create a session.

Represents a client Session.

Session provides these major functions:

The Session object is an EventEmitter, and will emit events with event names from solace.SessionEventCode when Session events occur. Each session event can be subscribed using solace.Session#on with the corresponding solace.SessionEventCode. If any of the registered event listeners throw an exception, the exception will be emitted on the 'error' event.

Fires

Constructor Top

  Session ( )

Static Methods Top

void replyReceivedCallback ( solace.Session session, solace.Message message, Object userObject )
void requestFailedCallback ( solace.Session session, solace.RequestError error, Object userObject )

Methods Top

void connect ( )
solace.CacheSession createCacheSession ( solace.CacheSessionProperties properties )
solace.MessageConsumer createMessageConsumer ( solace.MessageConsumerProperties | Object consumerProperties )
solace.QueueBrowser createQueueBrowser ( solace.QueueBrowserProperties | Object browserProperties )
void deprovisionEndpoint ( solace.QueueDescriptor queueDescriptor, boolean ignoreMisssing, Object | String | null | undefined correlationKey )
void disconnect ( )
void dispose ( )
solace.SDTField getCapability ( solace.CapabilityType capabilityType )
solace.SessionProperties getSessionProperties ( )
Number getStat ( solace.StatType statType )
String getTransportInfo ( )
Boolean isCapable ( solace.CapabilityType capabilityType )
void provisionEndpoint ( solace.QueueDescriptor queueDescriptor, solace.QueueProperties queueProperties, boolean ignoreExists, Object | String | null | undefined correlationKey )
void resetStats ( )
void send ( solace.Message message )
void sendReply ( solace.Message messageToReplyTo, solace.Message replyMessage )
void sendRequest ( solace.Message message, Number timeout, solace.Session.replyReceivedCallback replyReceivedCBFunction, solace.Session.requestFailedCallback requestFailedCBFunction, Object userObject )
void subscribe ( solace.Destination topic, Boolean requestConfirmation, Object | String | null | undefined correlationKey, Number | null | undefined requestTimeout )
void unsubscribe ( solace.Destination topic, Boolean requestConfirmation, Object | String | null | undefined correlationKey, Number | null | undefined requestTimeout )
void unsubscribeDurableTopicEndpoint ( solace.AbstractQueueDescriptor | solace.QueueDescriptor queueDescriptor )
void updateAuthenticationOnReconnect ( Object authenticationProperties )
void updateProperty ( MutableSessionProperty mutableSessionProperty, Object newValue, Number requestTimeout, Object | String | null | undefined correlationKey )

Constructor details Top

Session ( )

This class is not exposed for construction by API users. Applications must use solace.SolclientFactory.createSession to create a session.

Represents a client Session.

Session provides these major functions:

The Session object is an EventEmitter, and will emit events with event names from solace.SessionEventCode when Session events occur. Each session event can be subscribed using solace.Session#on with the corresponding solace.SessionEventCode. If any of the registered event listeners throw an exception, the exception will be emitted on the 'error' event.

Fires

Static Methods Detail Top

static public void replyReceivedCallback ( solace.Session session, solace.Message message, Object userObject )

A callback that returns replies to requests sent via solace.Session#sendRequest. The replyReceivedCallback must be provided to the API as the third argument of solace.Session#sendRequest.

Parameters

solace.Session session

The session object that received the reply.
solace.Message message

The reply message received.
Object userObject

The user object associated with the callback. 'undefined' when not provided to sendRequest

Return Value

void

static public void requestFailedCallback ( solace.Session session, solace.RequestError error, Object userObject )

A callback that returns errors associated with requests sent via solace.Session#sendRequest. The requestFailedCallback must be provided to the API as the fourth argument of solace.Session#sendRequest

Parameters

solace.Session session

The session object associated with the event.
solace.RequestError error

The event associated with the failure.
Object userObject

The user object associated with the callback. 'undefined' when not provided to sendRequest

Return Value

void

Methods Detail Top

public void connect ( )

Connects the session to the Solace Message Router as configured in the solace.SessionProperties#url.

When the session is successfully connected to the Solace Message Router, the solace.SessionEventCode#UP_NOTICE event is emitted if a listener has been registered.

If solace.SessionProperties#reapplySubscriptions is set to true, this operation re-registers previously registered subscriptions. The connected session event (solace.SessionEventCode#event:UP_NOTICE) is emitted only when all the subscriptions are successfully added to the router.

If the API is unable to connect within solace.SessionProperties#connectTimeoutInMsecs or due to login failures, the session's state transitions back to 'disconnected' and an event is generated.

Note: Before the session's state transitions to 'connected', a client application cannot use the session; any attempt to call functions will throw solace.OperationError.

Return Value

void

Throws

solace.OperationError

public solace.CacheSession createCacheSession ( solace.CacheSessionProperties properties )

Creates a solace.CacheSession object that uses this Session to service its cache requests.

It should be disposed when the application no longer requires a CacheSession, by calling solace.CacheSession#dispose.

Parameters

solace.CacheSessionProperties properties

The properties for the cache session.

Return Value

solace.CacheSession

The newly created cache session.

Throws

solace.OperationError

if a CacheSession is already associated with this Session. Subcode: solace.ErrorSubcode.INVALID_OPERATION

public solace.MessageConsumer createMessageConsumer ( solace.MessageConsumerProperties | Object consumerProperties )

Creates a solace.MessageConsumer to receive Guaranteed Messages in this Session.

Consumer characteristics and behavior are defined by properties. The consumer properties are supplied as an object; the pertinent fields are exposed in solace.MessageConsumerProperties; other property names are ignored. If the Message Consumer creation specifies a non-durable endpoint, solace.QueueProperties can be used to change the default properties on the non-durable endpoint. Any values not supplied are set to default values.

When the consumer is created, a consumer object is returned to the caller. This is the object from which events are emitted, and upon which operations (for example, starting and stopping the consumer) are performed.

If this session does not support Guaranteed Messaging, this method will throw. The following must be true in order to create a MessageConsumer:

Parameters

solace.MessageConsumerProperties | Object consumerProperties

The properties for the consumer.

Return Value

solace.MessageConsumer

The newly created Message Consumer.

Throws

solace.OperationError

when Guaranteed Message Consume is not supported on this session.

public solace.QueueBrowser createQueueBrowser ( solace.QueueBrowserProperties | Object browserProperties )

Creates a solace.QueueBrowser to browse Guaranteed Messages on a specified queue in this Session.

Browser characteristics and behavior are defined by properties. The browser properties are supplied as an object; the pertinent fields are exposed in solace.QueueBrowserProperties; other property names are ignored. Any values not supplied are set to default values.

Delivery restrictions imposed by the queue’s Access type (exclusive or non-exclusive), do not apply when browsing messages with a Browser.

When the queue browser is created, a queue browser object is returned to the caller. This is the object from which events are emitted, and upon which operations (for example, starting and stopping the browser) are performed.

If this session does not support Guaranteed Messaging, this method will throw. The following must be true in order to create a QueueBrowser:

Parameters

solace.QueueBrowserProperties | Object browserProperties

The properties for the browser.

Return Value

solace.QueueBrowser

The newly created Queue Browser.

Throws

solace.OperationError

when Guaranteed Messaging is not supported on this session.

public void deprovisionEndpoint ( solace.QueueDescriptor queueDescriptor, boolean ignoreMisssing, Object | String | null | undefined correlationKey )

Deprovisons a queue or topic endpoint on the broker. The function returns immediately (unless the parameters fail validation in which case an exception is thrown), but the actual outcome of the operation on the broker is only reported later in the form of a POVISION_OK or PROVISION_ERROR session event. Make sure to subscribe for those when using this fuction.

Parameters

solace.QueueDescriptor queueDescriptor

The name and type (queue or TE) of the endpoint. Durability is ignored.
boolean ignoreMisssing

Makes the operation idempotent if true, by ignoring "endpoint doesn't exist" errors.
Object | String | null | undefined correlationKey

If specified, this is the value identifying the operation in the resulting PROVISION_OK or PROVISION_ERROR session event SessionEvent

Return Value

void

Throws

solace.OperationError

public void disconnect ( )

Disconnects the session. The session attempts to disconnect cleanly, concluding all operations in progress. The disconnected session event solace.SessionEventCode#event:DISCONNECTED is emitted when these operations complete and the session has completely disconnected.

Return Value

void

Throws

solace.OperationError

if the session is disposed, or has never been connected. Subcode: solace.ErrorSubcode.INVALID_OPERATION.

public void dispose ( )

Release all resources associated with the session. It is recommended to call disconnect() first for proper handshake with the message-router.

Return Value

void

public solace.SDTField getCapability ( solace.CapabilityType capabilityType )

Get the value of an router capability, or null if unknown. This function must be called after connecting the session.

SDT Type conversions:

Parameters

solace.CapabilityType capabilityType

The router capability to query.

Return Value

solace.SDTField

The result of the capability query.

Throws

solace.OperationError

public solace.SessionProperties getSessionProperties ( )

Returns a clone of the properties for this session.

Return Value

solace.SessionProperties

A clone of this session's properties.

Throws

solace.OperationError

if the session is disposed. Subcode: solace.ErrorSubcode.INVALID_OPERATION.

public Number getStat ( solace.StatType statType )

Returns the value of a given solace.StatType.

Parameters

solace.StatType statType

The statistic to query.

Return Value

Number

The value of the requested statistic.

Throws

solace.OperationError

public String getTransportInfo ( )

Gets a transport session information string. This string is informative only, and applications should not attempt to parse it.

Return Value

String

A description of the current session's transport.

public Boolean isCapable ( solace.CapabilityType capabilityType )

Check the value of a boolean router capability.

This function is a shortcut for solace.Session#getCapability. It performs the same operation, but instead of returning a solace.SDTField wrapping a capability value, it just returns the boolean value.

Attempting to query a non-boolean capability will return null.

Parameters

solace.CapabilityType capabilityType

The capability to check.

Return Value

Boolean

the value of the capability queried.

Throws

solace.OperationError

public void provisionEndpoint ( solace.QueueDescriptor queueDescriptor, solace.QueueProperties queueProperties, boolean ignoreExists, Object | String | null | undefined correlationKey )

Provisons a queue or topic endpoint on the broker without binding a flow or adding a subscription. The function returns immediately (unless the parameters fail validation in which case an exception is thrown), but the actual outcome of the operation on the broker is only reported later in the form of a POVISION_OK or PROVISION_ERROR session event. Make sure to subscribe for those when using this fuction.

Parameters

solace.QueueDescriptor queueDescriptor

The name and type (queue or TE) of the endpoint. Only durable endpoints supported currently.
solace.QueueProperties queueProperties

Optional, in-out parameter. In: Properties of the Queue/TE to be created. Empty or undefined fields are left to broker defaults. Out (on PROVISION_OK, not on function return): Properties of the endpoint as created.
boolean ignoreExists

Makes the operation idempotent if true, by ignoring "endpoint already exists" errors.
Object | String | null | undefined correlationKey

If specified, this is the value identifying the operation in the resulting PROVISION_OK or PROVISION_ERROR session event SessionEvent

Return Value

void

Throws

solace.OperationError

public void resetStats ( )

Reset session statistics to initial values.

Return Value

void

Throws

solace.OperationError

if the session is disposed. Subcode: solace.ErrorSubcode.INVALID_OPERATION.

public void send ( solace.Message message )

Publish (send) a message over the session. The message is sent to its set destination.

This method is used for sending both direct and Guaranteed Messages. If the message's solace.MessageDeliveryModeType is solace.MessageDeliveryModeType.DIRECT, the message is a direct message; otherwise, it is a guaranteed message.

Parameters

solace.Message message

The message to send. It must have a destination set.

Return Value

void

Throws

solace.OperationError

public void sendReply ( solace.Message messageToReplyTo, solace.Message replyMessage )

Sends a reply message to the destination specified in messageToReplyTo.

If messageToReplyTo is non-null:

If messageToReplyTo is null, the application is responsible for setting the destination and correlationId on the replyMessage.

Parameters

solace.Message messageToReplyTo

The message to which a reply will be sent.
solace.Message replyMessage

The reply to send.

Return Value

void

Throws

solace.OperationError

public void sendRequest ( solace.Message message, Number timeout, solace.Session.replyReceivedCallback replyReceivedCBFunction, solace.Session.requestFailedCallback requestFailedCBFunction, Object userObject )

Sends a request using user-specified callback functions.

The API fills in the correlationId and replyTo fields in the request when they are not preset by the application. This is the preferred use case to ensure replies are directed back to the correct requester.

Parameters

solace.Message message

The request message to send.
Number timeout

The timeout value (in milliseconds). The minimum value is 100 msecs.

(Optional)
solace.Session.replyReceivedCallback replyReceivedCBFunction

The callback to notify when a reply is received.

(Optional)
solace.Session.requestFailedCallback requestFailedCBFunction

The callback to notify when the request failed.

(Optional)
Object userObject

An optional correlation object to use in the response callback.

(Optional)

Return Value

void

Throws

solace.OperationError

public void subscribe ( solace.Destination topic, Boolean requestConfirmation, Object | String | null | undefined correlationKey, Number | null | undefined requestTimeout )

Subscribe to a topic, optionally requesting a confirmation from the router.

If requestConfirmation is set to true: solace.SessionEventCode.SUBSCRIPTION_OK is generated when subscription is added successfully; otherwise, session event solace.SessionEventCode.SUBSCRIPTION_ERROR is generated.

If requestConfirmation is set to false, only session event solace.SessionEventCode.SUBSCRIPTION_ERROR is generated upon failure.

When the application receives session event solace.SessionEventCode.SUBSCRIPTION_ERROR, it can obtain the failed topic subscription by calling solace.SessionEvent#reason. The returned string is in the format of "Topic: ".

Parameters

solace.Destination topic

The topic destination subscription to add.
Boolean requestConfirmation

true, to request a confirmation; false otherwise.
Object | String | null | undefined correlationKey

If specified, and if requestConfirmation is true, this value is echoed in the session event within SessionEvent.
Number | null | undefined requestTimeout

The request timeout period (in milliseconds). If specified, this value overwrites readTimeoutInMsecs property in SessionProperties.

Return Value

void

Throws

solace.OperationError

public void unsubscribe ( solace.Destination topic, Boolean requestConfirmation, Object | String | null | undefined correlationKey, Number | null | undefined requestTimeout )

Unsubscribe from a topic, and optionally request a confirmation from the router.

If requestConfirmation is set to true, session event solace.SessionEventCode.SUBSCRIPTION_OK is generated when subscription is removed successfully; otherwise, session event solace.SessionEventCode.SUBSCRIPTION_ERROR is generated.

If requestConfirmation is set to false, only session event solace.SessionEventCode.SUBSCRIPTION_ERROR is generated upon failure.

When the application receives session event solace.SessionEventCode.SUBSCRIPTION_ERROR, it can obtain the failed topic subscription by calling solace.SessionEvent#reason. The returned string is in the format "Topic: ".

Parameters

solace.Destination topic

The topic destination subscription to remove.
Boolean requestConfirmation

true, to request a confirmation; false otherwise.
Object | String | null | undefined correlationKey

If null or undefined, a Correlation Key is not set in the confirmation session event.
Number | null | undefined requestTimeout

The request timeout period (in milliseconds). If specified, this value overwrites readTimeoutInMsecs property in SessionProperties.

Return Value

void

Throws

solace.OperationError

public void unsubscribeDurableTopicEndpoint ( solace.AbstractQueueDescriptor | solace.QueueDescriptor queueDescriptor )

Request that a Durable Topic Endpoint stop receiving data on a topic. Unsubscribe requests are only allowed by the router when no clients are bound to the DTE. If the unubscribe request is successful, the DTE will stop attracting messages, and all messages spooled to the DTE will be deleted.

solace.SessionEventCode.UNSUBSCRIBE_TE_TOPIC_OK is generated when the subscription is removed successfully; otherwise, solace.SessionEventCode.UNSUBSCRIBE_TE_TOPIC_ERROR is generated.

When the application receives session event solace.SessionEventCode.UNSUBSCRIBE_TE_TOPIC_ERROR, it can obtain the failed topic subscription by calling solace.SessionEvent#reason.

Parameters

solace.AbstractQueueDescriptor | solace.QueueDescriptor queueDescriptor

A description of the queue to which the topic is subscribed.

Return Value

void

Throws

solace.OperationError

public void updateAuthenticationOnReconnect ( Object authenticationProperties )

Modify (some) authentication-related session properties. The modifications take effect the next time the session connects or reconnects to the broker. There is no change to the active connection. Calling this method does not in itself trigger any kind of reconnection, reauthentication or renegotiation.

Note: the update of "accessToken" and "idToken" properties is currently supported. Authentication Properties

Parameters

Object authenticationProperties

to be set

Return Value

void

Throws

solace.OperationError

public void updateProperty ( MutableSessionProperty mutableSessionProperty, Object newValue, Number requestTimeout, Object | String | null | undefined correlationKey )

Modify a session property after creation of the session.

This method only works for a select few properties, and updates their value on the live broker session.

Parameters

MutableSessionProperty mutableSessionProperty

The property key to modify.
Object newValue

The new property value.
Number requestTimeout

The request timeout period (in milliseconds). If specified, it overwrites readTimeoutInMsecs
Object | String | null | undefined correlationKey

If specified, this value is echoed in the session event within SessionEvent property in SessionProperties

Return Value

void

Throws

solace.OperationError