Creating Client Sessions in the PubSub+ JCSMP API

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 Solace C API; for more information refer to Configuring Inter-Process Communications. However, shared memory transport and IPC capabilities are not available when using the 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, refer to Creating Secure Sessions in the PubSub+ JCSMP API.

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. Refer to Session Properties Required to Establish a Connection in the PubSub+ JCSMP API.

  • Specific Context instance

    For JCSMP, if you want to use a Context other than the default Context, you can pass in a specific Context to the factory method.

  • Session event callback or delegate

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

    A session event callback is optional for JCSMP.

  • Message receive callback or delegate

    For the Java RTO, C, or .NET APIs, 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. Refer to Receiving Direct Messages in the PubSub+ JCSMP API.

    For JCSMP, Direct messages delivered to a session are received through a com.solacesystems.jcsmp.Consumer, which is acquired by the client application after the session is created.

Once a session is created, it must be connected. For JCSMP, explicitly calling connect is recommended as best practice; although the API will automatically attempt to connect when requesting a producer or consumer.

  • To create a session, use JCSMPFactory.createSession(...).

  • To register a message callback, use JCSMPSession.getMessageConsumer(...).

  • To connect a session, use Session.connect().

  • To close a session, use Session.closeSession().

For an example of how to create and connect sessions, see the DirectPubSub sample in the Solace Developer Hub.