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 ( )

inlinevirtual

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 ( )

inlinevirtual

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

getset

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.