Creating Client Sessions

A session creates a single, client connection to a Solace 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.

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 Solace Java RTO 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 Solace Java RTO 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 Solace Java RTO API, you must use the session connect calls listed below.

To Create a Session

In the Solace Java RTO API, use ContextHandle.createSessionForHandle(...) - Creates a session that is bound to an unbound SessionHandle.

To Connect a Session

In the Solace Java RTO API, use SessionHandle.connect()

To Close a Session

In the Solace Java RTO API, use:

  • SessionHandle.disconnect()
  • SessionHandle.destroy()

Destroying the session is not required.

  • When using the Solace Java RTO API, calling destroy to destroy a session object is not required. If the session object is not destroyed, you may reconnect to it at a later time.

Related Samples

For an example of how to create and connect sessions, see the DirectPubSub sample for the Solace Java RTO API.

Handling Session Events

Session events provide information about the state of a client connection to the event broker, including connection establishment, disconnection, and error conditions. Properly handling these events allows your application to respond appropriately to changes in connection status and maintain robust messaging operations.

Registering Session Event Callbacks

An application can register a SessionEventCallback when creating a session with ContextHandle.createSessionForHandle(...).

For high-performance implementations of the Solace Java RTO API, applications should use SessionHandle.getSessionEvent(...) rather than SessionHandle.takeSessionEvent(...). When a get is used, the API retains responsibility for the event and will destroy it at the appropriate time. When a take is used, the API gives up control of the event and it is up to the application to destroy it.

For more information on using getSessionEvent() and takeSessionEvent(), see Get vs. Take in Solace Java RTO API Best Practices.

For an example of how to configure a session event callback for the Solace Java RTO API, see SampleUtils.java included with the sample files.