Creating Client Sessions

A session creates a single, client connection to a PubSub+ event broker for sending and receiving messages. The Solace Message Format (SMF) is used to facilitate the communication between a client and an event broker, and this SMF communication is then encapsulated through a single TCP connection.

A session can also use a shared memory transport when using the inter‑process communications (IPC) capabilities of the PubSub+ C API; for more information see Configuring Inter-Process Communications. However, shared memory transport and IPC capabilities are not available when using the PubSub+ C API for iOS applications.

By default, sessions are unsecured—in a connected session, the SMF data sent between a client and an event broker is transmitted as plain text. However, it is also possible to establish a secure session that uses Transport Layer Security (TLS)/ Secure Sockets Layer (SSL) protocols so that the SMF data is encrypted. For information on how to configure specific TLS/SSL session properties and establish a secure session, see Creating Secure Sessions.

Sessions are always created within a context. The client application controls whether one or multiple sessions are grouped under a processing context. Once a session is created within a given context, it remains associated with that single context until it is disposed.

To create a session, the client application must provide the following:

  • Session properties

    Properties used to customize the session. Any session property that is not explicitly supplied is set to default values. Although the defaults can be used in many cases, some client and event broker parameters require specific input from the client to establish a connection to a Message VPN on an event broker. See Session Properties Required to Establish a Connection.

  • Session event callback or delegate

    For the PubSub+ Java RTO API, PubSub+ C API, or PubSub+ .NET API, a session event callback or delegate must be specified when creating a session. This callback or delegate is invoked for each session event. See Handling Session Events.

  • Message receive callback or delegate

    For the PubSub+ Java RTO API, PubSub+ C API, or PubSub+ .NET API, a message event callback or delegate must be specified when creating a session. This callback or delegate is invoked each time a Direct message is received through the session. see Receiving Direct Messages.

Once a session is created, it must be connected. For the PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .NET API , you must use the session connect calls listed below.

To Create a Session
PubSub+ Messaging API Use

PubSub+ Java RTO API

  • ContextHandle.createSessionForHandle(...)

    Creates a session that is bound to an unbound SessionHandle.

PubSub+ C API

solClient_session_create(...)

PubSub+ .NET API

IContext.CreateSession(...)

PubSub+ JavaScript API and PubSub+ Node.js API

  • solace.SolclientFactory.createSession(...)

    Creates a session.

  • Session.on(...)

    Registers a session event listener, e.g.: for a MESSAGE event.

To Connect a Session
PubSub+ Messaging API Use

PubSub+ Java RTO API

SessionHandle.connect()

PubSub+ C API

solClient_session_connect(...)

PubSub+ .NET API

ISession.Connect()

PubSub+ JavaScript API and PubSub+ Node.js API

Session.connect()

To Close a Session
PubSub+ Messaging API Call

PubSub+ Java RTO API

  • SessionHandle.disconnect()

  • SessionHandle.destroy()

Destroying the session is not required.

PubSub+ C API

  • solClient_session_disconnect(...)

  • solClient_session_destroy(...)

Destroying the session is not required.

PubSub+ .NET API

  • ISession.Disconnect()

  • ISession.Dispose()

Disposing of the session is not required.

PubSub+ JavaScript API and PubSub+ Node.js API

  • Session.disconnect()

  • Session.dispose()

  • When using the PubSub+ Java RTO API, PubSub+ C API, PubSub+ JavaScript API, PubSub+ Node.js API, or PubSub+ .NET API, calling destroy or dispose to destroy a session object is not required. If the session object is not destroyed, you may reconnect to it at a later time.
  • When using the PubSub+ C API or PubSub+ .NET API, if a session is destroyed/disposed or a global cleanup is performed, any buffered messages associated with that session are discarded before it is disconnected. When a context is destroyed/disposed, the buffered messages associated with every session contained within that context are discarded.
  • When using the PubSub+ JavaScript API or PubSub+ Node.js API APIs, calling dispose releases all resources associated with the session. Solace recommends calling disconnect first for a proper handshake with the event broker.

Related Samples

For an example of how to create and connect sessions, see the DirectPubSub sample for the PubSub+ Java RTO API, PubSub+ C API, and PubSub+ .NET API, and the TopicPublisher sample for the PubSub+ JavaScript API and PubSub+ Node.js API.