## Contents

- Static Methods
- Methods

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:

- Subscriber control, such as updating subscriptions;
- Publishes both Direct and Guaranteed Messages to the router;
- Receives direct messages from the router.

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

- solace.SessionEventCode#event:ACKNOWLEDGED_MESSAGE
- solace.SessionEventCode#event:CAN_ACCEPT_DATA
- solace.SessionEventCode#event:CONNECT_FAILED_ERROR
- solace.SessionEventCode#event:DISCONNECTED
- solace.SessionEventCode#event:DOWN_ERROR
- solace.SessionEventCode#event:GUARANTEED_MESSAGE_PUBLISHER_DOWN
- solace.SessionEventCode#event:MESSAGE
- solace.SessionEventCode#event:PROPERTY_UPDATE_ERROR
- solace.SessionEventCode#event:PROPERTY_UPDATE_OK
- solace.SessionEventCode#event:RECONNECTED_NOTICE
- solace.SessionEventCode#event:RECONNECTING_NOTICE
- solace.SessionEventCode#event:REJECTED_MESSAGE_ERROR
- solace.SessionEventCode#event:REPUBLISHING_UNACKED_MESSAGES
- solace.SessionEventCode#event:SUBSCRIPTION_ERROR
- solace.SessionEventCode#event:SUBSCRIPTION_OK
- solace.SessionEventCode#event:UNSUBSCRIBE_TE_TOPIC_ERROR
- solace.SessionEventCode#event:UNSUBSCRIBE_TE_TOPIC_OK
- solace.SessionEventCode#event:UP_NOTICE
- solace.SessionEventCode#event:VIRTUALROUTER_NAME_CHANGED

## 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 | 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 | 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 correlationKey, Number requestTimeout ) |
void | unsubscribe ( solace.Destination topic, Boolean requestConfirmation, Object correlationKey, Number requestTimeout ) |
void | unsubscribeDurableTopicEndpoint ( solace.AbstractQueueDescriptor | solace.QueueDescriptor queueDescriptor ) |
void | updateProperty ( MutableSessionProperty mutableSessionProperty, Object newValue, Number requestTimeout, Object 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:

- Subscriber control, such as updating subscriptions;
- Publishes both Direct and Guaranteed Messages to the router;
- Receives direct messages from the router.

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

- solace.SessionEventCode#event:ACKNOWLEDGED_MESSAGE
- solace.SessionEventCode#event:CAN_ACCEPT_DATA
- solace.SessionEventCode#event:CONNECT_FAILED_ERROR
- solace.SessionEventCode#event:DISCONNECTED
- solace.SessionEventCode#event:DOWN_ERROR
- solace.SessionEventCode#event:GUARANTEED_MESSAGE_PUBLISHER_DOWN
- solace.SessionEventCode#event:MESSAGE
- solace.SessionEventCode#event:PROPERTY_UPDATE_ERROR
- solace.SessionEventCode#event:PROPERTY_UPDATE_OK
- solace.SessionEventCode#event:RECONNECTED_NOTICE
- solace.SessionEventCode#event:RECONNECTING_NOTICE
- solace.SessionEventCode#event:REJECTED_MESSAGE_ERROR
- solace.SessionEventCode#event:REPUBLISHING_UNACKED_MESSAGES
- solace.SessionEventCode#event:SUBSCRIPTION_ERROR
- solace.SessionEventCode#event:SUBSCRIPTION_OK
- solace.SessionEventCode#event:UNSUBSCRIBE_TE_TOPIC_ERROR
- solace.SessionEventCode#event:UNSUBSCRIBE_TE_TOPIC_OK
- solace.SessionEventCode#event:UP_NOTICE
- solace.SessionEventCode#event:VIRTUALROUTER_NAME_CHANGED

## 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.Sesssion#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 replyReceivedCallback must be provided to the API as the fourth argument of solace.Sesssion#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 | if the session is disposed, already connected or connecting. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the underlying transport cannot be established. Subcode: solace.ErrorSubcode.CONNECTION_ERROR.

###
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:

- The transport protocol list does not contain any HTTP transport protocols. See solace.SessionProperties#transportProtocol and solace.FactoryProfile#cometEnabled
- The Solace Messaging Router must support Guaranteed Messaging

#### 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:

- The transport protocol list does not contain any HTTP transport protocols. See solace.SessionProperties#transportProtocol and solace.FactoryProfile#cometEnabled
- The Solace Messaging Router must support Guaranteed Messaging

#### 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 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:

- {string} values are returned as solace.SDTFieldType.STRING.
- {boolean} values are returned as solace.SDTFieldType.BOOL.
- All numeric values are returned as solace.SDTFieldType.INT64.

#### Parameters

solace.CapabilityType | capabilityType The router capability to query.

#### Return Value

solace.SDTField | The result of the capability query.

#### Throws

solace.OperationError | if the session is disposed Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type or value. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE.

###
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 | if the session is disposed. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the StatType is invalid. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE.

###
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 | if the session is disposed. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type or value. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE.

###
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 | if the session is disposed or disconnected. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE. if the message does not have a topic. Subcode: solace.ErrorSubcode.TOPIC_MISSING. if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA. if no Guaranteed Message Publisher is available and the message deliveryMode is solace.MessageDeliveryModeType.PERSISTENT or solace.MessageDeliveryModeType.NON_PERSISTENT. Subcode: solace.ErrorSubcode.GM_UNAVAILABLE.

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

Sends a reply message to the destination specified in messageToReplyTo.

If `messageToReplyTo` is non-null:

- solace.Message#getReplyTo is copied from `messageToReplyTo` to solace.Message#setDestination on `replyMessage`, unless `replyTo` is null.
- solace.Message#setCorrelationId is copied from `messageToReplyTo` to solace.Message#setCorrelationId on `replyMessage`, unless `correlationId` is 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 | if the session is disposed or disconnected. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE. if the parameters have an invalid value. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE. if the message does not have a topic. Subcode: solace.ErrorSubcode.TOPIC_MISSING. if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA. if no Guaranteed Message Publisher is available and the message deliveryMode is solace.MessageDeliveryModeType.PERSISTENT or solace.MessageDeliveryModeType.NON_PERSISTENT. Subcode: solace.ErrorSubcode.GM_UNAVAILABLE.

###
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.
Note: The API sets the correlationId and replyTo fields of the message being sent; this overwrites any existing correlationId and replyTo values on the message.

#### 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 | if the session is disposed or disconnected. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE. if the parameters have an invalid value. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE. if the message does not have a topic. Subcode: solace.ErrorSubcode.TOPIC_MISSING. if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA. if no Guaranteed Message Publisher is available and the message deliveryMode is solace.MessageDeliveryModeType.PERSISTENT or solace.MessageDeliveryModeType.NON_PERSISTENT. Subcode: solace.ErrorSubcode.GM_UNAVAILABLE.

###
public void subscribe ( solace.Destination topic, Boolean requestConfirmation, Object correlationKey, Number 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 | correlationKey If specified, and if requestConfirmation is true, this value is echoed in the session event within SessionEvent.
Number | requestTimeout The request timeout period (in milliseconds). If specified, this value overwrites readTimeoutInMsecs property in SessionProperties.

#### Return Value

void |

#### Throws

solace.OperationError | if the session is disposed or disconnected. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE. if the parameters have an invalid value. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE. if the topic has invalid syntax. Subcode: solace.ErrorSubcode.INVALID_TOPIC_SYNTAX. if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA.

###
public void unsubscribe ( solace.Destination topic, Boolean requestConfirmation, Object correlationKey, Number 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 | correlationKey If `null` or undefined, a Correlation Key is not set in the confirmation session event.
Number | requestTimeout The request timeout period (in milliseconds). If specified, this value overwrites readTimeoutInMsecs property in SessionProperties.

#### Return Value

void |

#### Throws

solace.OperationError | if the session is disposed or disconnected. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE. if the parameters have an invalid value. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE. if the topic has invalid syntax. Subcode: solace.ErrorSubcode.INVALID_TOPIC_SYNTAX. if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA.

###
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 | if the session is disposed or disconnected. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE. if the parameters have an invalid value. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE. if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA.

###
public void updateProperty ( MutableSessionProperty mutableSessionProperty, Object newValue, Number requestTimeout, Object correlationKey )

Modify a session property after creation of the 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 | correlationKey If specified, this value is echoed in the session event within SessionEvent property in SessionProperties

#### Return Value

void |

#### Throws

solace.OperationError | if the session is disposed or disconnected. Subcode: solace.ErrorSubcode.INVALID_OPERATION. if the parameters have an invalid type. Subcode: solace.ErrorSubcode.PARAMETER_INVALID_TYPE. if the parameters have an invalid value. Subcode: solace.ErrorSubcode.PARAMETER_OUT_OF_RANGE. if there's no space in the transport to send the request. Subcode: solace.ErrorSubcode.INSUFFICIENT_SPACE. See: solace.SessionEventCode#event:CAN_ACCEPT_DATA.