# tibemsSession

Type

## Purpose

Organizes context for message activity.

## Remarks

Sessions combine several roles:

- Create message producers and consumers
- Create message objects
- Create temporary destinations
- Create dynamic destinations
- Create queue browsers
- Serialize for inbound and outbound messages
- Serialize for asynchronous message events (or message listeners) of its consumer objects
- Cache inbound messages (until the program acknowledges them).
- Transaction support (when enabled).

## Single Thread

The JMS specification restricts programs to use each session within a single thread.

Associated Objects

The same single-thread restriction applies to objects associated with a session—namely, messages, message consumers, durable subscribers, message producers, queue browsers, and temporary destinations (however, static and dynamic destinations are exempt from this restriction).

Corollary

One consequence of this rule is that all the consumers of a session must deliver messages in the same mode—either synchronously or asynchronously.

Asynchronous

In asynchronous delivery, the program registers message handler events or message listeners with the session’s consumer objects. An internal dispatcher thread delivers messages to those event handlers or listeners (in all the session’s consumer objects). No other thread may use the session (nor objects created by the session).

Synchronous

In synchronous delivery, the program explicitly begins a thread for the session. That thread processes inbound messages and produces outbound messages, serializing this activity among the session’s producers and consumers. Functions that request the next message (such as`tibemsMsgConsumer_Receive`) can organize the thread’s activity.

Close

The only exception to the rule restricting session calls to a single thread is the function `tibemsSession_Close`; programs can call Close from any thread at any time.

## Transactions

A session has either transaction or non-transaction semantics. When a program specifies transaction semantics, the session object cooperates with the server, and all messages that flow through the session become part of a transaction.

- When the program calls `tibemsSession_Commit`, the session acknowledges all inbound messages in the current transaction, and the server delivers all outbound messages in the current transaction to their destinations.
- If the program calls `tibemsSession_Rollback`, the session recovers all inbound messages in the current transaction (so the program can consume them in a new transaction), and the server destroys all outbound messages in the current transaction.

After these actions, both Commit and Rollback immediately begin a new transaction.

Function | Description
--- | ---
Messages
`tibemsSession_CreateBytesMessage` | Create a byte array message.
`tibemsSession_CreateMapMessage` | Create a map message.
`tibemsSession_CreateMessage` | Create a message.
`tibemsSession_CreateStreamMessage` | Create a stream message.
`tibemsSession_CreateTextMessage` | Create a text message.
Destinations
`tibemsSession_CreateBrowser` | Create a queue browser.
`tibemsSession_CreateTemporaryQueue` | Create a temporary queue.
`tibemsSession_CreateTemporaryTopic` | Create a temporary topic.
`tibemsSession_DeleteTemporaryQueue` | Delete a temporary queue.
`tibemsSession_DeleteTemporaryTopic` | Delete a temporary topic.
Consumers & Producers
`tibemsSession_CreateConsumer` | Create a message consumer.
`tibemsSession_CreateDurableSubscriber` | Create a durable topic subscriber.
`tibemsSession_CreateProducer` | Create a message producer.
`tibemsSession_CreateSharedConsumer` | Create a shared consumer.
`tibemsSession_CreateSharedDurableConsumer` | Create a shared durable consumer.
`tibemsSession_Unsubscribe` | Unsubscribe a durable topic subscription.
Transactions
`tibemsSession_Commit` | Commit the open transaction.
`tibemsSession_Rollback` | Roll back messages in the current transaction.
`tibemsSession_GetTransacted` | Get the transactional semantics property of a session.
Other
`tibemsSession_Close` | Close a session; reclaim resources.
`tibemsSession_Recover` | Recover from undetermined state during message processing.
`tibemsSession_GetAcknowledgeMode` | Get the acknowledge mode of a session.

Copyright © Cloud Software Group, Inc. All rights reserved.