Click or drag to resize

ISession Interface

version: 10.9.0
Represents a messaging API session. When a context is established, one or more sessions can be created within that context. A session (modeled as an interface called ISession) creates a client connection to the Solace appliance for sending and receiving messages. It also provides the following: Connect and disconnect on demand.Factory of IFlow instances.Factory of temporary destinations (see IDestination) .Factory of non-durable endpoints (see IDurableTopicEndpoint and IQueue) .Factory of cache session instances (see ICacheSession) .Ability to make request/replies.Subscribe and unsubscribe.Ability to update and retrieve session properties. Ability to retrieve session statistics (see IStatsAccessible).

Disposing a session must not be performed in a session callback delegate for the session being disposed. This includes all flows on the session.

Namespace:  SolaceSystems.Solclient.Messaging
Assembly:  SolaceSystems.Solclient.Messaging (in SolaceSystems.Solclient.Messaging.dll) Version: 10.9.0
Syntax
public interface ISession : IDisposable, 
	IStatsAccessible, IMessageDispatcher

The ISession type exposes the following members.

Properties
  NameDescription
Public propertyFlows
Represents the current read-only collection of active (not yet disposed) flows created by this session.
Public propertyProperties
Returns a copy of the current SessionProperties.
Top
Methods
  NameDescription
Public methodClearStats
Clears the stats dictionary.
(Inherited from IStatsAccessible.)
Public methodConnect
Connects the specified session. A session connection can be carried out in a blocking or non-blocking mode, depending upon the session property ConnectBlocking.

In blocking mode, the calling thread is blocked until either the session connection attempt succeeds or is determined to have failed. If the connection succeeds, SOLCLIENT_OK is returned. If the session could not connect, SOLCLIENT_NOT_READY is returned.

In non-blocking mode, SOLCLIENT_IN_PROGRESS is returned upon a successful session connect request, and the connection attempt proceeds in the background. In both non-blocking and blocking mode, a session event is generated for the session: UpNotice, if the session successfully connects; or ConnectFailedError, if the session fails to connect.

For blocking mode, the session event is issued before the call to Connect returns. For non-blocking mode, the timing is undefined (that is, it could occur before or after the call returns, but it is typically after). A session connection timer, controlled by the session property ConnectTimeoutInMsecs, controls the maximum amount of time a session connect attempt lasts for. If this amount time is exceeded, a ConnectFailedError event is issued for the session.

If there is an error when Connect is invoked, SOLCLIENT_FAIL is returned, and a session event is not subsequently issued. Therefore, the caller must check for a return code of SOLCLIENT_FAIL if it has logic that depends upon a subsequent session event to be issued. For a non-blocking session connect invocation, if the session connect attempt eventually fails, the last error information to indicate the reason for the failure cannot be determined by the calling thread, rather it must be discovered through the session event delegate (and GetLastSDKErrorInfo can be called in the session event delegate to get further information). For a blocking session connect invocation, if the session connect attempt does not return SOLCLIENT_OK, then the calling thread can determine the failure reason by immediately calling GetLastSDKErrorInfo.

Public methodCreateBrowser
Creates a new IBrowser instance.
Public methodCreateCacheSession
This method creates a cache session instance to be used in subsequent cache request operations on the session. Multiple ICacheSesssion instances may be created on an ISession instance.
Public methodCreateDispatchTarget
Creates a IDispatchTarget instance to be used in the Subscribe(IDispatchTarget, Int32, Object) and Unsubscribe(IDispatchTarget, Int32, Object) methods.

Note: Client applications must keep IDispatchTarget object references accessible if they want to Unsubscribe from the given IMessageDispatcher, and remove already added Topic subscriptions. IDispatchTarget internal object ID constitutes a unique key. Forgetting to keep a reference to IDispatchTarget objects make subsequent Unsubscribe(IDispatchTarget, Int32, Object) calls impossible.

(Inherited from IMessageDispatcher.)
Public methodCreateFlow(FlowProperties, IEndpoint, ISubscription, EventHandlerMessageEventArgs, EventHandlerFlowEventArgs)
Creates IFlow instances. A flow is an API concept, which allows client applications to consume messages from an IEndpoint. Messges are attracted by a ISubscription to a IDestination.

The message receive delegate is invoked for each received message on this flow. The flow event delegate is invoked when flow events occur, such as the flow going up or down. Both delegates are invoked in the context of the context thread to which this session belongs.

Note: disposing the corresponding context (IContext) or any of its contained context timers (TimerTask), sessions (ISession) or flows (IFlow) must not be performed from within the registered delegates (messageEventHandler or flowEventHandler).

An endpoint is a holding area which allows a client to attract Guaranteed messages matching a given subscription to a destination. There are two types of endpoints: "durable" and "non-durable". Durable in this context means that the client that is bound to the given endpoint does not have to be online to attract messages. Non-durable endpoints are disposed when the bound client disconnects.

A destination can be either temporary or non-temporary. A temporary destination is used as a "reply to" field in request/reply message exchange patterns. Wildcard subscription capabilities do not apply to temporary destinations.

With the exception of durable endpoint with temporary destination, the following cases are supported:

use caseendPointsubscription
A flow bound to a non-temporary IQueue.A non-null IQueue, created by CreateQueue(String)null
A flow bound to a temporary IQueue.A non-null IQueue, created by CreateTemporaryQueue.null
A flow bound to a non-temporary ITopic and a durable ITopicEndpoint.A non-null ITopicEndpoint, created by CreateDurableTopicEndpoint(String).A non-null ITopic, created by CreateTopic(String) or CreateTopic(TopicProperties).
A flow bound to a non-temporary ITopic and a non-durable ITopicEndpoint.A Non-Durable ITopicEndpoint, created by CreateNonDurableTopicEndpoint. A non-null ITopic, created by CreateTopic(String) or CreateTopic(TopicProperties).
A flow bound to a temporary ITopic and a non-durable ITopicEndpoint.A Non-Durable ITopicEndpoint, created by CreateNonDurableTopicEndpoint. A non-null ITopic, created by CreateTemporaryTopic or CreateTopic(TopicProperties).
Public methodCreateFlow(FlowProperties, IEndpoint, ISubscription, EventHandlerMessageEventArgs, EventHandlerFlowEventArgs, EndpointProperties)
Creates IFlow instances. In addition, if endPoint is a non-durable Endpoint, it is possible to specify the EndpointProperties of implicitly created Endpoint on the appliance.

The message receive delegate is invoked for each received message on this flow. The flow event delegate is invoked when flow events occur, such as the flow going up or down. Both delegates are invoked in the context of the context thread to which this session belongs.

Note: disposing the corresponding context (IContext) or any of its contained context timers (TimerTask), sessions (ISession) or flows (IFlow) must not be performed from within the registered delegates (messageEventHandler or flowEventHandler).

Public methodCreateMessage
Creates an IMessage instance. Applications are responsible for disposing all messages allocated by this method as soon as they are done with them.

This method is simply provided for convenience's sake. There is no lifecycle dependency between ISession and IMessage.

Public methodCreateNonDurableTopicEndpoint
Creates a non-durable Topic Endpoint. The non-durable Topic Endpoint must be bound to by a IFlow on this session.

The non-durable endpoint is created on the appliance when a consumer is bound on this session.

Public methodCreateNonDurableTopicEndpoint(String)
Creates a non-durable Topic Endpoint based on the given name. The non-durable Topic Endpoint must be bound to by a IFlow on this session.

The non-durable endpoint is created on the appliance when a consumer is bound on this session.

Public methodCreateTemporaryQueue
Creates a temporary Queue for this session. This queue should only be bound to by a consumer on this session; although other sessions can publish to it.

A temporary Queue can only be used to bind to non-durable endpoints. The non-durable endpoint is created on the appliance when a consumer is bound on this session.

Connect must be called before calling this method.

Public methodCreateTemporaryQueue(String)
Creates a temporary Queue on this session with the given name. This Queue should only be bound to by a consumer on this session; although other sessions can publish to it.

A temporary queue can only be used to bind to non-durable endpoints. The non-durable endpoint is created on the appliance when a consumer is bound on this session.

Connect must be called before calling this method.

Public methodCreateTemporaryTopic
Creates a temporary topic for this session. Only a consumer on this session should bind to this topic; although clients on other sessions can publish to it.

Temporary topics can only be used to bind to non-durable endpoints.

Connect must be called before calling this method.

Public methodCreateTransactedSession
Creates a transacted session on the given ISession instance. If CreateMessageDispatcher is false, the default Context-bound Message Dispatcher is used by the transacted session to deliver messages asynchronously to transacted flows. By enabling CreateMessageDispatcher, a new transacted-session-bound messge dispatcher is created when the transacted session creates its first transacted consumer flow with asynchrounous message delivery. CreateTransactedSession(TransactedSessionProperties) blocks until a transacted session is created on the appliance. If HasPublisher is enabled, it also waits until a default publisher flow is opened properly.
Public methodDeprovision
Deprovisions or removes a durable ITopicEndpoint or IQueue from the appliance. Endpoint deprovisioning can be carried out in a synchronous or asynchronous mode, depending upon the provision flags passed in to this method. If WaitForConfirm is specified in flags, the calling thread is blocked until the endpoint deprovisioning attempt either succeeds or is determined to have failed. If WaitForConfirm is not set, SOLCLIENT_IN_PROGRESS is returned when the endpoint deprovision request is successfully sent, and the remove attempt proceeds in the background.

An Endpoint provision timer, controlled by the property ProvisionTimeoutInMsecs, controls the maximum amount of time a deprovsion attempt lasts for. Upon expiry of this timer, a ProvisionError event is returned in the session event delegate.

Public methodDisconnect
Disconnects the session.
Public methodDispose
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
(Inherited from IDisposable.)
Public methodGetCapability
Returns an ICapability instance for the given CapabilityType.
Public methodGetContext
Returns a reference to the Context that was used to create this session.
Public methodGetProperty
Returns the object value of a given property.
Public methodGetRxStats
Returns the Rx Stats.
(Inherited from IStatsAccessible.)
Public methodGetTxStats
Returns the Tx Stats.
(Inherited from IStatsAccessible.)
Public methodIsCapable
Checks if the specified capability type is set on the currently connected session. Returns true if the session has the specified CapabilityType.
Public methodModifyClientInfo
Allows the following client name and description properties of a Session to be modified after the Session has been created.

The property modifications can be carried out in a blocking or non-blocking mode, depending on the flag ModifyPropertyFlag Attempting to specify other Session properties will result in SOLCLIENT_FAIL being returned.

Note that only one outstanding client info modification request is allowed. Note that changing client name property would trigger the P2P topic changes. To avoid message loss, it is recommended that this API is used only at the initialization time.

Public methodModifyProperty
Allows certain properties of a session to be modified after the session has been created. Currently, only the following session properties can be modified:
ClientDescription (Deprecated - See Note below)

ClientName (Deprecated - See Note below)

Host (may only be modified when session is disconnected)

Port (may only be modified when session is disconnected)

Note: Applications shall use ModifyClientInfo(SessionPropertiesPROPERTY, Object, Int32, Object) to modify the following session properties:
ClientDescription

ClientName
Public methodProvision
Provisions a durable ITopicEndpoint or IQueue on the appliance. Endpoint creation can be carried out in a synchronous or asynchronous mode, depending upon the provision flags passed in to this method. If WaitForConfirm is specified in flags, the calling thread is blocked until the endpoint creation attempt either succeeds or is determined to have failed. If WaitForConfirm is not specified in flags, SOLCLIENT_IN_PROGRESS is returned when the endpoint provision request is successfully sent, and the creation attempt proceeds in the background.

An Endpoint provision timer, controlled by the property ProvisionTimeoutInMsecs, controls the maximum amount of time a provision attempt lasts for. Upon expiry of this timer, a ProvisionError event is returned in the session event delegate.

Public methodSend(IMessage)
Sends a message over the session.
Public methodSend(IMessage, Int32, Int32, Int32)
Sends an array of messages over the session, attempting to send them all at once.

Note that the number of messages which can be sent through a single call to this method is limited to 50.

For sessions in which Send(IMessage[],...) is used, it is recommended that TcpNoDelay be set to true (it is enabled by default). In this case, multiple messages are sent at once onto a TCP connection, and therefore there is no need to have the operating system carry out the TCP delay algorithm to cause fuller IP packets.

Public methodSendReply
Sends a Reply Message (see SetAsReplyMessage() on IMessage). If messageToReply is non-null, the following message properties are copied to replyMessage: ReplyTo is copied to Destination, unless ReplyTo is null.CorrelationId, unless it is null. If messageToReplyTo is null, the application is responsible for setting the Destination and CorrelationId on the replyMessage.
Public methodSendRequest
Send a Topic Request message. The application expects an end-to-end reply from the client that receives the request message. If the Reply-To destination in the UserProperties of the request message is not set, it defaults to the current session's ReplyTo destination. Leaving the replyTo destination unset and allowing the API to set the default replyTo destination is the easiest way to set a valid replyTo destination. When the responses are handled asynchronously (that is, the timeout parameter is zero), the application may set any replyTo destination. When the application needs to block and wait for the reply (that is, the timeout parameter is non-zero), the replyTo destination must be a topic that the application has subscribed to for Direct messages. If timeoutInMsecs is zero, this method returns immediately upon successfully accepting the request message for transmission. Any replies sent back by the destination client are delivered to the ReplyTo Destination through the message receive delegate. In such a case, the reply tag is set (IsReplyMessage == true) on the response message. It is entirely the responsibility of the application to manage asynchronous replies. Applications can use the CorrelationId message property on outgoing requests. If the timeoutInMsecs parameter is non-zero, the function waits for the amount of time specified by timeoutInMsecs milliseconds before returning with SOLCLIENT_INCOMPLETE. If the replyTo destination is set to an unsubscribed topic, or endpoint, a call to Session.SendRequest() will block until the amount of time set for the timeout parameter expires and then return SOLCLIENT_INCOMPLETE. The function only allows one blocking request (timeout non-zero) at a time. If a multiple threaded application calls Session.SendRequest() from multiple threads at the same time, the first processed request is sent and all other requests block until the first response is received, then the next request is sent.This will consume some of the timeout period for each request.
Public methodSetClientDescription Obsolete.
Sets the Client Description.
Public methodSubscribe(ISubscription, Boolean)
Registers a subscription to the appliance. When the appliance is running SolOS-TR, a Topic is required.
Public methodSubscribe(IDispatchTarget, Int32, Object)
Adds a IDispatchTarget subscription to the given IMessageDispatcher.

Note: In order to use this feature, the parent ISession's SessionProperties must have TopicDispatch set to true.

(Inherited from IMessageDispatcher.)
Public methodSubscribe(IEndpoint, ISubscription, Int32, Object)
Add a ITopic subscription on the endpoint if the operation is supported on the endpoint (Only endpoints of type IQueue or type IClientName support this operation).
Public methodUnsubscribe(ISubscription, Boolean)
Remove a subscription.
Public methodUnsubscribe(ITopicEndpoint, Int32) Obsolete.
Unsubscribes from a durable Topic Endpoint.
Public methodUnsubscribe(ITopicEndpoint, Object)
Unsubscribes from a durable Topic Endpoint. This is only valid if no clients are bound to the topic endpoint.
Public methodUnsubscribe(IDispatchTarget, Int32, Object)
Removes an IDispatchTarget subscription from the given IMessageDispatcher.

Note: To use this feature, the parent ISession's SessionProperties must have TopicDispatch set to true.

(Inherited from IMessageDispatcher.)
Public methodUnsubscribe(IEndpoint, ISubscription, Int32, Object)
Remove a ITopic subscription from the endpoint if the operation is supported on the endpoint (Only endpoint of type IQueue supports this operation).
Public methodValidateTopic
This method checks a topic string against topic encoding rules for the appliance. This method is intended for use before sending a message to a topic. This method should not be used with Subscribe methods. Subscribe methods perform its own topic validation, which includes accepting wildcards. For performance reasons Send(IMessage) and Send(IMessage, Int32, Int32, Int32) does not validate topics, and this method is provided as a convenience to the developer to ensure a topic is valid before sending a message that could be rejected by the appliance. It is expected then that the same topic will be used for sending many messages.
Top
See Also