TIBCO EMS .NET API 8.5
TIBCO EMS .NET API 8.5
|
A Session object is a single-threaded context for producing and consuming messages. More...
Public Member Functions | |
QueueBrowser | CreateBrowser (Queue queue) |
Create a QueueBrowser object to peek at the messages on the specified queue. More... | |
QueueBrowser | CreateBrowser (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... | |
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 specified 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... | |
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... | |
Topic | CreateTopic (string topicName) |
Create a topic More... | |
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 | Recover () |
Recover from undetermined state during message processing More... | |
void | Close () |
Close a session and reclaim resources 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 = TIBCO.EMS.Session.SESSION_TRANSACTED |
The session is transacted More... | |
const int | AUTO_ACKNOWLEDGE = TIBCO.EMS.Session.AUTO_ACKNOWLEDGE |
Automatic acknowledgment More... | |
const int | CLIENT_ACKNOWLEDGE = TIBCO.EMS.Session.CLIENT_ACKNOWLEDGE |
Client acknowledgment More... | |
const int | DUPS_OK_ACKNOWLEDGE = TIBCO.EMS.Session.DUPS_OK_ACKNOWLEDGE |
Duplication ok acknowledgment More... | |
const int | NO_ACKNOWLEDGE = TIBCO.EMS.Session.NO_ACKNOWLEDGE |
No acknowledge acknowledge mode More... | |
const int | EXPLICIT_CLIENT_ACKNOWLEDGE = TIBCO.EMS.Session.EXPLICIT_CLIENT_ACKNOWLEDGE |
Explicit client acknowledge mode More... | |
const int | EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE = TIBCO.EMS.Session.EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE |
Explicit client acknowledge mode with dups_ok More... | |
Properties | |
int | AcknowledgeMode [get] |
Get the acknowledge mode of the session as integer constants as defined in Session class. More... | |
Connection | Connection [get] |
Get the connection the session belongs to More... | |
bool | IsClosed [get] |
bool | IsTransacted [get] |
Get whether the session is transacted More... | |
TIBCO.EMS.SessionMode | SessionAcknowledgeMode [get] |
Get the acknowledge mode of the session as a SessionMode type More... | |
IMessageListener | MessageListener [get, set] |
Get or set the message listener for the session. -Deprecated, use MessageConsumer.MessageListener instead. More... | |
bool | Transacted [get] |
Get whether an open session is transacted More... | |
A Session object is a single-threaded context for producing and consuming messages.
Sessions combine several roles:
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.
After these actions, both Commit and Rollback immediately begin a new transaction.
|
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.
|
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.
TIBCO.EMS.EMSException | If the Commit failed due to some internal error. |
TIBCO.EMS.TransactionRolledBackException | An attempt to commit a transaction resulted in rollback. |
TIBCO.EMS.IllegalStateException | Commit occurred in an inappropriate context. |
|
inline |
Create a QueueBrowser object to peek at the messages on the specified queue.
The QueueBrowser object will be recreated during connection recovery process.
queue | The queue to browse |
TIBCO.EMS.EMSException | If the session fails to create a browser due to some internal error. |
TIBCO.EMS.InvalidDestinationException | If an invalid destination is specified |
|
inline |
Create a QueueBrowser object to peek at the messages on the specified queue using a message selector.
The QueueBrowser object will be recreated during connection recovery process.
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. |
TIBCO.EMS.EMSException | If the session fails to create a browser due to some internal error. |
TIBCO.EMS.InvalidDestinationException | If an invalid destination is specified. |
TIBCO.EMS.InvalidSelectorException | If the message selector is invalid. |
|
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.
|
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.
The MessageConsumer object will be recreated during connection recovery.
dest | The Destination to access. |
TIBCO.EMS.EMSException | If the session fails to create a consumer due to some internal error. |
TIBCO.EMS.InvalidDestinationException | If an invalid destination is specified. |
|
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.
The MessageConsumer object will be recreated during connection recovery.
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. |
TIBCO.EMS.EMSException | If the session fails to create a consumer due to some internal error. |
TIBCO.EMS.InvalidDestinationException | If an invalid destination is specified. |
TIBCO.EMS.InvalidSelectorException | If the message selector is invalid. |
|
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.
The MessageConsumer object will be recreated during connection recovery.
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.
TIBCO.EMS.EMSException | If the session fails to create a consumer due to some internal error. |
TIBCO.EMS.InvalidDestinationException | If an invalid destination is specified. |
TIBCO.EMS.InvalidSelectorException | If the message selector is invalid. |
|
inline |
Create a durable subscriber to the specified topic
Not supported by the UFO implementation.
|
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.
Not supported by the UFO implementation.
|
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.
|
inline |
|
inline |
Create an ObjectMessage object. An ObjectMessage object is used to send a message that contains a serializable .NET object.
|
inline |
Create an ObjectMessage object. An ObjectMessage object is used to send a message that contains a serializable .NET object.
obj | and .NET serialized object |
|
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. The MessageProducer object will be recreated during connection recovery.
dest | When non-null, the producer sends messages to this destination. When null, the client program must specify the destination for each message individually. |
|
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.
queueName | The name of the Queue to be created. |
|
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.
topic | the Topic to subscribe to |
sharedSubscriptionName | the name used to identify the shared non-durable subscription |
|
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 specified 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.
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. |
|
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.
Not supported by the UFO implementation.
|
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.
Not supported by the UFO implementation.
|
inline |
Create a StreamMessage object
A StreamMessage object is used to send a self-defining stream of primitive values in the .NET programming language.
|
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. It will be recreated during connection recovery.
TIBCO.EMS.EMSException | if the session fails to create a temporary queue due to some internal error. |
|
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. It will be recreated during connection recovery.
TIBCO.EMS.EMSException | If the session fails to create a temporary topic due to some internal error. |
|
inline |
Create a TextMessage object
A TextMessage object is used to send a message containing a String object.
|
inline |
Create a TextMessage object
A TextMessage object is used to send a message containing a String object.
text | The string used as data to initialize this message |
|
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.
topicName | Get or create the topic with this name. |
|
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:
When a session has transactional semantics, this method throws IllegalStateException (commit and rollback are more appropriate for transactions).
|
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.
TIBCO.EMS.IllegalStateException | The session does not have transactional semantics. |
|
inline |
Obsolete: Not to be used by ordinary JMS Clients
|
inline |
Returns a string representation of this Session
object.
|
inline |
Unsubscribe a durable topic subscription
Not supported by the UFO implementation.
const int TIBCO.EMS.UFO.Session.AUTO_ACKNOWLEDGE = TIBCO.EMS.Session.AUTO_ACKNOWLEDGE |
const int TIBCO.EMS.UFO.Session.CLIENT_ACKNOWLEDGE = TIBCO.EMS.Session.CLIENT_ACKNOWLEDGE |
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.UFO.Session.DUPS_OK_ACKNOWLEDGE = TIBCO.EMS.Session.DUPS_OK_ACKNOWLEDGE |
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.UFO.Session.EXPLICIT_CLIENT_ACKNOWLEDGE = TIBCO.EMS.Session.EXPLICIT_CLIENT_ACKNOWLEDGE |
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.UFO.Session.EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE = TIBCO.EMS.Session.EXPLICIT_CLIENT_DUPS_OK_ACKNOWLEDGE |
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.UFO.Session.NO_ACKNOWLEDGE = TIBCO.EMS.Session.NO_ACKNOWLEDGE |
No acknowledge acknowledge mode
In NO_ACKNOWLEDGE mode, messages do not require acknowledgement (which reduces message overhead). The server never redelivers messages. This mode is available for topic sessions only. This mode and behavior are proprietary extensions, specific to TIBCO EMS.
const int TIBCO.EMS.UFO.Session.SESSION_TRANSACTED = TIBCO.EMS.Session.SESSION_TRANSACTED |
The session is transacted
The IsTransacted property has this value (true) if the session is transacted.
|
get |
Get the acknowledge mode of the session as integer constants as defined in Session class.
Note: Clients should use the TIBCO.EMS.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.
|
get |
Get the connection the session belongs to
The Connection instance
summary>Get whether the session is closed.
value>True if session closed, false otherwise
|
get |
summary>Gets the id of the session.
value>The unique id of the sesion.
|
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.
|
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
TIBCO.EMS.IllegalStateException | If the session is closed |
|
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 TIBCO.EMS.SessionMode.
|
get |
Get whether an open session is transacted
IllegalStateException will be thrown if the session is closed.