TIBCO EMS .NET API 8.5 TIBCO EMS .NET API 8.5

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Public Attributes | Properties | List of all members
TIBCO.EMS.Session Class Reference

A Session object is a single-threaded context for producing and consuming messages. More...

Inheritance diagram for TIBCO.EMS.Session:

## Public Member Functions
QueueBrowser | CreateBrowser (TIBCO.EMS.Queue queue)
| Create a QueueBrowser object to peek at the messages on the specified queue. More...
QueueBrowser | CreateBrowser (TIBCO.EMS.Queue queue, string messageSelector)
| Create a QueueBrowser object to peek at the messages on the specified queue using a message selector. More...
MessageConsumer | CreateConsumer (Destination dest)
| Create a MessageConsumer for a specific destination. More...
MessageConsumer | CreateConsumer (Destination dest, string messageSelector)
| Create a MessageConsumer for a specific destination, using a message selector. More...
MessageConsumer | CreateConsumer (Destination dest, string messageSelector, bool noLocal)
| Create MessageConsumer for the specified destination, using a message selector. This method can specify whether messages published by its own connection should be delivered to it, if the destination is a topic More...
TemporaryTopic | CreateTemporaryTopic ()
| Create a TemporaryTopic object More...
TemporaryQueue | CreateTemporaryQueue ()
| Create a TemporaryQueue object More...
TopicSubscriber | CreateDurableSubscriber (Topic topic, string name)
| Create a durable subscriber to the specified topic More...
TopicSubscriber | CreateDurableSubscriber (Topic topic, string name, string messageSelector, bool noLocal)
| Create a durable subscriber to the specified topic, using a message selector and specifying whether messages published by its own connection should be delivered to it. More...
MessageConsumer | CreateSharedConsumer (Topic topic, string sharedSubscriptionName)
| Create a shared non-durable subscription (with the specified name on the specified topic - if one does not already exist), and a consumer on that subscription. More...
MessageConsumer | CreateSharedConsumer (Topic topic, string sharedSubscriptionName, string messageSelector)
| Create a shared non-durable subscription (with the specified name on the specified topic - if one does not already exist), and a consumer on that subscription, using the specidied message selector. More...
MessageConsumer | CreateSharedDurableConsumer (Topic topic, string name)
| Create a shared durable subscription (with the specified name on the specified topic - if one does not already exist), and a consumer on that subscription. More...
MessageConsumer | CreateSharedDurableConsumer (Topic topic, string name, string messageSelector)
| Create a shared durable subscription (with the specified name on the specified topic - if one does not already exist), and a consumer on that subscription, using the specified message selector. More...
Topic | CreateTopic (string topicName)
| Create a topic More...
TIBCO.EMS.Queue | CreateQueue (string queueName)
| Create a queue More...
MessageProducer | CreateProducer (Destination dest)
| Create a MessageProducer to send messages to the specified destination. More...
void | Unsubscribe (string name)
| Unsubscribe a durable topic subscription More...
BytesMessage | CreateBytesMessage ()
| Create a byte array message More...
MapMessage | CreateMapMessage ()
| Create a MapMessage object. A MapMessage object is used to send a self-defining set of name-value pairs, where names are String objects and values are primitive values in the .NET programming language. More...
Message | CreateMessage ()
| Create a Message object. The Message interface is the root interface of all TIBCO EMS messages. A Message object holds all the standard message header information. It can be sent when a message containing only header information is sufficient More...
ObjectMessage | CreateObjectMessage ()
| Create an ObjectMessage object. An ObjectMessage object is used to send a message that contains a serializable .NET object. More...
ObjectMessage | CreateObjectMessage (Object obj)
| Create an ObjectMessage object. An ObjectMessage object is used to send a message that contains a serializable .NET object. More...
StreamMessage | CreateStreamMessage ()
| Create a StreamMessage object More...
TextMessage | CreateTextMessage ()
| Create a TextMessage object More...
TextMessage | CreateTextMessage (string text)
| Create a TextMessage object More...
virtual void | Commit ()
| Commit the open transaction More...
virtual void | Rollback ()
| Roll back messages in the current transaction More...
void | Close ()
| Close a session and reclaim resources More...
void | Recover ()
| Recover from undetermined state during message processing More...
void | Run ()
| Obsolete: Not to be used by ordinary JMS Clients More...
override string | ToString ()
| Returns a string representation of this `Session` object. More...

## Public Attributes
const int | SESSION_TRANSACTED = 0
| The session is transacted More...
const int | AUTO_ACKNOWLEDGE = 1
| Automatic acknowledgment More...
const int | CLIENT_ACKNOWLEDGE = 2
| Client acknowledgment More...
const int | DUPS_OK_ACKNOWLEDGE = 3
| Duplication ok acknowledgment More...
const int | NO_ACKNOWLEDGE = 22
| No acknowledge acknowledge mode More...
const int | EXPLICIT_CLIENT_ACKNOWLEDGE = 23
| Explicit client acknowledge mode More...
const int | EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE = 24
| Explicit client acknowledge mode with dups_ok More...

## Properties
Connection | Connection`[get]`
| Get the connection the session belongs to More...
bool | IsClosed`[get]`
bool | IsTransacted`[get]`
| Get whether the session is transacted More...
int | AcknowledgeMode`[get]`
| Get the acknowledge mode of the session as integer constants as defined in Session class. More...
SessionMode | SessionAcknowledgeMode`[get]`
| Get the acknowledge mode of the session as a SessionMode type More...
bool | Transacted`[get]`
| Get whether an open session is transacted More...
IMessageListener | MessageListener`[get, set]`
| Get or set the message listener for the session. -Deprecated, use MessageConsumer.MessageListener instead. More...

## Detailed Description

A Session object is a single-threaded context for producing and consuming messages.

Sessions combine several roles:

- Factory for message producers and consumers.
- Factory for message objects.
- Factory for temporary destinations.
- Factory for dynamic destinations.
- Factory for queue browsers.
- Serializer for inbound and outbound messages.
- Serializer for asynchronous message events (or message listeners) of its consumer objects.
- Cache for 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. Methods that request the next message (such as MessageConsumer.Receive) can organize the thread's activity.
Close | The only exception to the rule restricting session calls to a single thread is the method 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 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 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.

## Member Function Documentation

void TIBCO.EMS.Session.Close | ( |  | ) |
| inline

Close a session and reclaim resources

Closing a session automatically closes its consumers (except for durable subscribers), producers and browsers.

Blocking

If any message listener or receive call associated with the session is processing a message when the program calls this method, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this method blocks until that processing completes – that is, until all message listeners and receive calls have returned. A blocked message consumer receive call returns null when this session is closed.

Transactions

Closing a session rolls back the open transaction in the session.

virtual void TIBCO.EMS.Session.Commit | ( |  | ) |
| inline virtual

Commit the open transaction

A session (with transaction semantics) always has exactly one open transaction. Message operations associated with the session become part of that transaction. This call commits all the messages within the transaction and releases any locks. Then it opens a new transaction.

Exceptions

  EMSException | If the Commit failed due to some internal error.
  TransactionRolledBackException | An attempt to commit a transaction resulted in rollback.
  IllegalStateException | Commit occurred in an inappropriate context.

QueueBrowser TIBCO.EMS.Session.CreateBrowser | ( | TIBCO.EMS.Queue | queue | ) |
| inline

Create a QueueBrowser object to peek at the messages on the specified queue.

Parameters

  queue | The queue to browse

Exceptions

  EMSException | If the session fails to create a browser due to some internal error.
  InvalidDestinationException | If an invalid destination is specified

QueueBrowser TIBCO.EMS.Session.CreateBrowser | ( | TIBCO.EMS.Queue | queue,
|  | string | messageSelector
| ) |  |
| inline

Create a QueueBrowser object to peek at the messages on the specified queue using a message selector.

Parameters

  queue | The queue to browse
  messageSelector | Only messages with properties matching the message selector expression are delivered. A value of null or an empty string specifies that the browser is to view all messages in the queue.

Exceptions

  EMSException | If the session fails to create a browser due to some internal error.
  InvalidDestinationException | If an invalid destination is specified.
  InvalidSelectorException | If the message selector is invalid.

BytesMessage TIBCO.EMS.Session.CreateBytesMessage | ( |  | ) |
| inline

Create a byte array message

This method creates a BytesMessage object, which is used to send a message containing a stream of uninterpreted bytes.

MessageConsumer TIBCO.EMS.Session.CreateConsumer | ( | Destination | dest | ) |
| inline

Create a MessageConsumer for a specific destination.

Because Queue and Topic both inherit from Destination, they can be used in the destination parameter to create a MessageConsumer.

A client uses a MessageConsumer object to receive messages that have been sent to a destination.

Parameters

  dest | The Destination to access.

Exceptions

  EMSException | If the session fails to create a consumer due to some internal error.
  InvalidDestinationException | If an invalid destination is specified.

MessageConsumer TIBCO.EMS.Session.CreateConsumer | ( | Destination | dest,
|  | string | messageSelector
| ) |  |
| inline

Create a MessageConsumer for a specific destination, using a message selector.

Because Queue and Topic both inherit from Destination, they can be used in the destination parameter to create a MessageConsumer.

A client uses a MessageConsumer object to receive messages that have been sent to a destination.

Parameters

  dest | The Destination to access.
  messageSelector | Only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that the message consumer is to receive all messages.

Exceptions

  EMSException | If the session fails to create a consumer due to some internal error.
  InvalidDestinationException | If an invalid destination is specified.
  InvalidSelectorException | If the message selector is invalid.

MessageConsumer TIBCO.EMS.Session.CreateConsumer | ( | Destination | dest,
|  | string | messageSelector,
|  | bool | noLocal
| ) |  |
| inline

Create MessageConsumer for the specified destination, using a message selector. This method can specify whether messages published by its own connection should be delivered to it, if the destination is a topic

Since Queue and Topic both inherit from Destination, they can be used in the destination parameter to create a MessageConsumer.

A client uses a MessageConsumer object to receive messages that have been sent to a destination.

Parameters

  dest | The Destination to access
  messageSelector | Only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that the message consumer is to receive all messages.
  noLocal | When true, the server filters messages so the consumer does not receive messages that originate locally – that is, messages sent through the same connection.

When absent or false, the consumer receives messages with local origin.

Exceptions

  EMSException | If the session fails to create a consumer due to some internal error.
  InvalidDestinationException | If an invalid destination is specified.
  InvalidSelectorException | If the message selector is invalid.

TopicSubscriber TIBCO.EMS.Session.CreateDurableSubscriber | ( | Topic | topic,
|  | string | name
| ) |  |
| inline

Create a durable subscriber to the specified topic

The server associates a durable subscription with at most one subscriber object at a time. When a subscriber object exists, the subscription is active, and the server delivers messages to it; when no subscriber object exists, the subscription is inactive.

Durable subscriptions guarantee message delivery across periods during which the subscriber is inactive. The server retains unacknowledged messages until the subscriber acknowledges them, or until the messages expire.

Subscription Continuity

Continuity across inactive periods uses two data items from the client:

- Subscription Name a parameter of this method
- Client ID an optional property of the Connection (used only when supplied)

The server uses one or both of these two items to match a subscriber object with its subscription. If a matching subscription exists, and it is inactive, then the server associates it with the subscriber (and the subscription becomes active). The server delivers unacknowledged messages to the subscriber.

If a matching subscription exists, but it is already active, this method throws EMSException.

If a matching subscription to the topic does not yet exist, the server creates one.

Matching Client ID

If the Connection's client ID is non-null when a session creates a durable subscription, then only sessions of a connection with the same client ID can attach to that subscription.

If the Connection's client ID is null when a session creates a durable subscription, then any session can attach to that subscription (to receive its messages).

Changing Topic

Notice that the server does not use the topic argument to match a subscriber to an existing subscription. As a result, client programs can change a subscription by altering the topic. The effect is equivalent to deleting the existing subscription (from the server) and creating a new one (albeit with the same client ID and subscription name).

Parameters

  topic | Create a durable subscriber for this topic (which cannot be a TemporaryTopic)
  name | This unique name lets the server associate the subscriber with a subscription.

TopicSubscriber TIBCO.EMS.Session.CreateDurableSubscriber | ( | Topic | topic,
|  | string | name,
|  | string | messageSelector,
|  | bool | noLocal
| ) |  |
| inline

Create a durable subscriber to the specified topic, using a message selector and specifying whether messages published by its own connection should be delivered to it.

The server associates a durable subscription with at most one subscriber object at a time. When a subscriber object exists, the subscription is active, and the server delivers messages to it; when no subscriber object exists, the subscription is inactive.

Durable subscriptions guarantee message delivery across periods during which the subscriber is inactive. The server retains unacknowledged messages until the subscriber acknowledges them, or until the messages expire.

Subscription Continuity

Continuity across inactive periods uses two data items from the client:

- Subscription Name a parameter of this method
- Client ID an optional property of the Connection (used only when supplied)

The server uses one or both of these two items to match a subscriber object with its subscription. If a matching subscription exists, and it is inactive, then the server associates it with the subscriber (and the subscription becomes active). The server delivers unacknowledged messages to the subscriber.

If a matching subscription exists, but it is already active, this method throws EMSException.

If a matching subscription to the topic does not yet exist, the server creates one.

Matching Client ID

If the Connection's client ID is non-null when a session creates a durable subscription, then only sessions of a connection with the same client ID can attach to that subscription.

If the Connection's client ID is null when a session creates a durable subscription, then any session can attach to that subscription (to receive its messages).

Changing Topic or Selector

Notice that the server does not use the topic and message selector arguments to match a subscriber to an existing subscription. As a result, client programs can change a subscription by altering either or both of these arguments. The effect is equivalent to deleting the existing subscription (from the server) and creating a new one (albeit with the same client ID and subscription name).

Parameters

  topic | Create a durable subscriber for this topic (which cannot be a TemporaryTopic)
  name | This unique name lets the server associate the subscriber with a subscription.
  messageSelector | When present, the server filters messages using this selector, so the subscriber receives only matching messages. (See "Message Selectors" in the TIBCO Enterprise Message Service User's Guide.)

When absent, null, or the empty string, the subscriber receives messages without filtering.

Parameters

  noLocal | When true, the server filters messages so the subscriber does not receive messages that originate locally - that is, messages sent through the same connection.

When absent or false, the consumer receives messages with local origin.

MapMessage TIBCO.EMS.Session.CreateMapMessage | ( |  | ) |
| inline

Create a MapMessage object. A MapMessage object is used to send a self-defining set of name-value pairs, where names are String objects and values are primitive values in the .NET programming language.

Message TIBCO.EMS.Session.CreateMessage | ( |  | ) |
| inline

Create a Message object. The Message interface is the root interface of all TIBCO EMS messages. A Message object holds all the standard message header information. It can be sent when a message containing only header information is sufficient

ObjectMessage TIBCO.EMS.Session.CreateObjectMessage | ( |  | ) |
| inline

Create an ObjectMessage object. An ObjectMessage object is used to send a message that contains a serializable .NET object.

ObjectMessage TIBCO.EMS.Session.CreateObjectMessage | ( | Object | obj | ) |
| inline

Create an ObjectMessage object. An ObjectMessage object is used to send a message that contains a serializable .NET object.

Parameters

  obj | and .NET serialized object

MessageProducer TIBCO.EMS.Session.CreateProducer | ( | Destination | dest | ) |
| inline

Create a MessageProducer to send messages to the specified destination.

A client uses a MessageProducer object to send messages to a destination. Since Queue and Topic both inherit from Destination, they can be used in the destination parameter to create a MessageProducer object.

Parameters

  dest | When non-null, the producer sends messages to this destination. When null, the client program must specify the destination for each message individually.

TIBCO.EMS.Queue TIBCO.EMS.Session.CreateQueue | ( | string | queueName | ) |
| inline

Create a queue

This facility is provided for the rare cases where clients need to dynamically manipulate queue identity.

Note that this method is not for creating the physical queue. The physical creation of queues is an administrative task and is not to be initiated by the EMS API. The one exception is the creation of temporary queues, which is accomplished with the CreateTemporaryQueue() method.

If the named queue already exists at the server, then this method returns that queue. (That queue can be either static or dynamic.)

If the named queue does not yet exist at the server, and the server allows dynamic queues, then this method creates a dynamic queue.

Dynamic destinations are provider-specific, so programs that use them might not be portable to other providers.

Parameters

  queueName | The name of the Queue to be created.

Returns
  A Queue with the given name.

MessageConsumer TIBCO.EMS.Session.CreateSharedConsumer | ( | Topic | topic,
|  | string | sharedSubscriptionName
| ) |  |
| inline

Create a shared non-durable subscription (with the specified name on the specified topic - if one does not already exist), and a consumer on that subscription.

If a shared non-durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector value has been specified, then this method creates a MessageConsumer on the existing subscription.

A non-durable shared subscription is used by a client which needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. A non-durable shared subscription may therefore have more than one consumer. Each message from the subscription will be delivered to only one of the consumers on that subscription. Such a subscription is not persisted and will be deleted (together with any undelivered messages associated with it) when there are no consumers on it. The term "consumer" here means a MessageConsumer on any client.

A shared non-durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared non-durable subscription must use the same client identifier.

If a shared non-durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the subscription, then an EMSException will be thrown.

There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

Parameters

  topic | the Topic to subscribe to
  sharedSubscriptionName | the name used to identify the shared non-durable subscription

MessageConsumer TIBCO.EMS.Session.CreateSharedConsumer | ( | Topic | topic,
|  | string | sharedSubscriptionName,
|  | string | messageSelector
| ) |  |
| inline

Create a shared non-durable subscription (with the specified name on the specified topic - if one does not already exist), and a consumer on that subscription, using the specidied message selector.

If a shared non-durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector value has been specified, then this method creates a MessageConsumer on the existing subscription.

A non-durable shared subscription is used by a client which needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. A non-durable shared subscription may therefore have more than one consumer. Each message from the subscription will be delivered to only one of the consumers on that subscription. Such a subscription is not persisted and will be deleted (together with any undelivered messages associated with it) when there are no consumers on it. The term "consumer" here means a MessageConsumer on any client.

A shared non-durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared non-durable subscription must use the same client identifier.

If a shared non-durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the subscription, then an EMSException will be thrown.

There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

Parameters

  topic | the Topic to subscribe to
  sharedSubscriptionName | the name used to identify the shared non-durable subscription
  messageSelector | only messages with properties matching the message selector expression are added to the shared non-durable subscription. A value of null or an empty string indicates that there is no message selector for the shared non-durable subscription.

MessageConsumer TIBCO.EMS.Session.CreateSharedDurableConsumer | ( | Topic | topic,
|  | string | name
| ) |  |
| inline

Create a shared durable subscription (with the specified name on the specified topic - if one does not already exist), and a consumer on that subscription.

A durable subscription is used by an application which needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The EMS Server retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription or until they have expired.

A durable subscription will continue to accumulate messages until it is deleted using the Session.Unsubscribe method.

This method may only be used with shared durable subscriptions. Any durable subscription created using this method will be shared. This means that multiple active (i.e. not closed) consumers on the subscription may exist at the same time. The term "consumer" here means a MessageConsumer object in any client.

A shared durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared durable subscription must use the same client identifier.

If a shared durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector has been specified, then this method creates a MessageConsumer on the existing shared durable subscription.

If a shared durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is no consumer already active (i.e. not closed) on the durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a new one.

If a shared durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the durable subscription, then an EMSException will be thrown.

A shared durable subscription and an unshared durable subscription may not have the same name and client identifier (if set). If an unshared durable subscription already exists with the same name and client identifier (if set) then an EMSException is thrown.

There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

Parameters

  topic | the Topic to subscribe to
  name | the name used to identify this subscription

MessageConsumer TIBCO.EMS.Session.CreateSharedDurableConsumer | ( | Topic | topic,
|  | string | name,
|  | string | messageSelector
| ) |  |
| inline

Create a shared durable subscription (with the specified name on the specified topic - if one does not already exist), and a consumer on that subscription, using the specified message selector.

A durable subscription is used by an application which needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The EMS Server retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription or until they have expired.

A durable subscription will continue to accumulate messages until it is deleted using the Session.Unsubscribe method.

This method may only be used with shared durable subscriptions. Any durable subscription created using this method will be shared. This means that multiple active (i.e. not closed) consumers on the subscription may exist at the same time. The term "consumer" here means a MessageConsumer object in any client.

A shared durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared durable subscription must use the same client identifier.

If a shared durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector has been specified, then this method creates a MessageConsumer on the existing shared durable subscription.

If a shared durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is no consumer already active (i.e. not closed) on the durable subscription then this is equivalent to unsubscribing (deleting) the old one and creating a new one.

If a shared durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the durable subscription, then an EMSException will be thrown.

A shared durable subscription and an unshared durable subscription may not have the same name and client identifier (if set). If an unshared durable subscription already exists with the same name and client identifier (if set) then an EMSException is thrown.

There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

Parameters

  topic | the Topic to subscribe to
  name | the name used to identify this subscription
  messageSelector | only messages with properties matching the message selector expression are added to the durable subscription. A value of null or an empty string indicates that there is no message selector for the durable subscription.

StreamMessage TIBCO.EMS.Session.CreateStreamMessage | ( |  | ) |
| inline

Create a StreamMessage object

A StreamMessage object is used to send a self-defining stream of primitive values in the .NET programming language.

Returns
  A new StreamMessage object.

TemporaryQueue TIBCO.EMS.Session.CreateTemporaryQueue | ( |  | ) |
| inline

Create a TemporaryQueue object

A temporary queue lasts no longer than the connection. That is, when the connection is closed or broken, the server deletes temporary queues associated with the connection.

Returns
  a temporary queue identity

Exceptions

  EMSException | if the session fails to create a temporary queue due to some internal error.

TemporaryTopic TIBCO.EMS.Session.CreateTemporaryTopic | ( |  | ) |
| inline

Create a TemporaryTopic object

A temporary topic lasts no longer than the Connection object. That is, when the connection is closed or broken, the server deletes temporary topic associated with the connection.

Returns
  A TemporaryTopic object

Exceptions

  EMSException | If the session fails to create a temporary topic due to some internal error.

TextMessage TIBCO.EMS.Session.CreateTextMessage | ( |  | ) |
| inline

Create a TextMessage object

A TextMessage object is used to send a message containing a String object.

Returns
  A new TextMessage object.

TextMessage TIBCO.EMS.Session.CreateTextMessage | ( | string | text | ) |
| inline

Create a TextMessage object

A TextMessage object is used to send a message containing a String object.

Parameters

  text | The string used as data to initialize this message

Topic TIBCO.EMS.Session.CreateTopic | ( | string | topicName | ) |
| inline

Create a topic

If the named topic already exists at the server, then this method returns that topic. (That topic can be either static or dynamic.)

If the named topic does not yet exist at the server, and the server allows dynamic topics, then this method creates a dynamic topic.

Dynamic destinations are provider-specific, so programs that use them might not be portable to other providers.

Note: This facility is provided for the rare cases where clients need to dynamically manipulate topic identity. This method is not for creating the physical topic. The physical creation of topics is an administrative task and is not to be initiated by the EMS API. The one exception is the creation of temporary topics, which is accomplished with the createTemporaryTopic method.

Parameters

  topicName | Get or create the topic with this name.

Returns
  A Topic with the given name.

void TIBCO.EMS.Session.Recover | ( |  | ) |
| inline

Recover from undetermined state during message processing

Exceptions during message processing can sometimes leave a program in an ambiguous state. For example, some messages might be partially processed. This method lets a program return to an unambiguous state - the point within the message stream when the program last acknowledged the receipt of inbound messages. Programs can then review the messages delivered since that point (they are marked as redelivered), and resolve ambiguities about message processing.

Programs can also use this method to resolve similar ambiguities after a Connection stops delivering messages, and then starts again.

Operation

This method requests that the server do this sequence of actions:

1. Stop message delivery within the session.
2. Mark as redelivered, any messages that the server has attempted to deliver to the session, but for which it has not received acknowledgement (that is, messages for which processing state is ambiguous). According to the JMS specification, the server does not needs to redeliver messages in the same order as it first delivered them.
3. Restart message delivery (including messages marked as redelivered in step 2).

When a session has transactional semantics, this method throws IllegalStateException (commit and rollback are more appropriate for transactions).

virtual void TIBCO.EMS.Session.Rollback | ( |  | ) |
| inline virtual

Roll back messages in the current transaction

Roll back any messages done in this transaction and release any locks currently held.

Messages sent to a queue with prefetch=none and maxRedelivery=number properties are not received number times by an EMS application that receives in a loop and does an XA rollback after the XA prepare phase.

Exceptions

  IllegalStateException | The session does not have transactional semantics.

void TIBCO.EMS.Session.Run | ( |  | ) |
| inline

Obsolete: Not to be used by ordinary JMS Clients

Deprecated:
  Ordinary JMS clients should not use this method.

override string TIBCO.EMS.Session.ToString | ( |  | ) |
| inline

Returns a string representation of this `Session` object.

Returns
  A string representation

void TIBCO.EMS.Session.Unsubscribe | ( | string | name | ) |
| inline

Unsubscribe a durable topic subscription

This method deletes the named subscription from the server.

Parameters

  name | The name of the durable subscriber

Exceptions

  EMSException | Attempt to delete an active subscription (while a MessageConsumer or TopicSubscriber exists) or to delete a subscription while one of its messages is either unacknowledged, or uncommitted (in the current transaction).
  IllegalStateException | Session is closed.

## Member Data Documentation

const int TIBCO.EMS.Session.AUTO_ACKNOWLEDGE = 1

Automatic acknowledgment

In this mode, the session automatically acknowledges a message when message processing is finished. "Finished" in this case is when either of these methods returns successfully:

- Synchronous Receive call
- Asynchronous listener handler OnMessage call

const int TIBCO.EMS.Session.CLIENT_ACKNOWLEDGE = 2

Client acknowledgment

In this mode, the client program acknowledges receipt by calling Message.Acknowledge. Each call acknowledges all messages received so far.

const int TIBCO.EMS.Session.DUPS_OK_ACKNOWLEDGE = 3

Duplication ok acknowledgment

As with AUTO_ACKNOWLEDGE, the session automatically acknowledges messages. However, it may do so lazily. Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message. Lazy acknowledgement can reduce session overhead.

const int TIBCO.EMS.Session.EXPLICIT_CLIENT_ACKNOWLEDGE = 23

Explicit client acknowledge mode

As with CLIENT_ACKNOWLEDGE, the client program acknowledges receipt by calling Message.Acknowledge. However, each call acknowledges only the individual message. The client may acknowledge messages in any order.

This mode and behavior are proprietary extensions, specific to TIBCO EMS.

const int TIBCO.EMS.Session.EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE = 24

Explicit client acknowledge mode with dups_ok

In EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE mode, the client program lazily acknowledges only the individual message, by calling Message.Acknowledge. The client may acknowledge messages in any order.

Lazy means that the provider client library can delay transferring the acknowledgement to the server until a convenient time; meanwhile the server might redeliver the message.

This mode and behavior are proprietary extensions, specific to TIBCO EMS.

const int TIBCO.EMS.Session.NO_ACKNOWLEDGE = 22

No acknowledge acknowledge mode

In NO_ACKNOWLEDGE mode, messages do not require acknowledgement (which reduces message overhead). The server never redelivers messages. This mode and behavior are proprietary extensions, specific to TIBCO EMS.

const int TIBCO.EMS.Session.SESSION_TRANSACTED = 0

The session is transacted

The IsTransacted property has this value (true) if the session is transacted.

## Property Documentation

int TIBCO.EMS.Session.AcknowledgeMode
| get

Get the acknowledge mode of the session as integer constants as defined in Session class.

Note: Clients should use the SessionMode enum instead.

This mode governs message acknowledgement and redelivery for consumers associated with the session. For values, see the Session Acknowledge Modes.

This property is irrelevant when IsTransacted is true.

Connection TIBCO.EMS.Session.Connection
| get

Get the connection the session belongs to

The Connection instance

bool TIBCO.EMS.Session.IsClosed
| get

summary>Gets the id of the session.

value>The unique id of the sesion.

bool TIBCO.EMS.Session.IsTransacted
| get

Get whether the session is transacted

When true, the session has transaction semantics, and AcknowledgeMode is irrelevant.

When false, it has non-transaction semantics.

IMessageListener TIBCO.EMS.Session.MessageListener
| get set

Get or set the message listener for the session. -Deprecated, use MessageConsumer.MessageListener instead.

The access of message listener through the Session object is deprecated. Please use the facility in MessageConsumer instead.

User should either use MessageHandler or MessageListener to handle asynchronous message consumptions, but not both. Setting up both will cause the message to be handled more than once which can result in undefined behavior

Exceptions

  IllegalStateException | If the session is closed

Deprecated:
  Use MessageConsumer.MessageListener instead.

SessionMode TIBCO.EMS.Session.SessionAcknowledgeMode
| get

Get the acknowledge mode of the session as a SessionMode type

This property accesses the same information as AcknowledgeMode, but uses enumerated values rather than ordinary integers. It is recommend over AcknowledgeMode because it enables .NET to do stronger type checking at compile time, which can enhance program reliability. For return values, see SessionMode.

bool TIBCO.EMS.Session.Transacted
| get

Get whether an open session is transacted

IllegalStateException will be thrown if the session is closed.