WebSphere WebSphere Business Integration Message Service Clients for C/C++ Version 1.2.7 and .NET Version 1.2.6 Operating Systems: AIX, Linux, Solaris, Windows

ISession

A session is a single threaded context for sending and receiving messages.

Inheritance hierarchy:
IBM.XMS.IPropertyContext
   |
   +----IBM.XMS.ISession

For a list of the XMS defined properties of a Session object, see Properties of Session.

.NET properties

Summary of .NET properties:
.NET property Description
AcknowledgeMode Get the acknowledgement mode for the session.
Transacted Determine whether the session is transacted.

AcknowledgeMode – Get Acknowledgement Mode

Interface:
AcknowledgeMode AcknowledgeMode
    {
      get;
    }

Get the acknowledgement mode for the session.

The acknowledgement mode is specified when the session is created.

Provided the session is not transacted, the acknowledgement mode is one of the following values:

  • AcknowledgeMode.AutoAcknowledge
  • AcknowledgeMode.ClientAcknowledge
  • AcknowledgeMode.DupsOkAcknowledge

For more information about acknowledgement modes, see Message acknowledgement.

A session that is transacted has no acknowledgement mode. If the session is transacted, the method returns AcknowledgeMode.SessionTransacted instead.

Exceptions:
  • XMSException

Transacted – Determine Whether Transacted

Interface:
Boolean Transacted
    {
      get;
    }

Determine whether the session is transacted.

The transacted stated is:

  • True, if the session is transacted.
  • False, if the session is not transacted.

For a real-time connection to a broker, the method always returns False.

Exceptions:
  • XMSException

Methods

Summary of methods:
Method Description
Close Close the session.
Commit Commit all messages processed in the current transaction.
CreateBrowser Create a queue browser for the specified queue.
CreateBrowser Create a queue browser for the specified queue using a message selector.
CreateBytesMessage Create a bytes message.
CreateConsumer Create a message consumer for the specified destination.
CreateConsumer Create a message consumer for the specified destination using a message selector.
CreateConsumer Create a message consumer for the specified destination using a message selector and, if the destination is a topic, specifying whether the message consumer receives the messages published by its own connection.
CreateDurableSubscriber Create a durable subscriber for the specified topic.
CreateDurableSubscriber Create a durable subscriber for the specified topic using a message selector and specifying whether the durable subscriber receives the messages published by its own connection.
CreateMapMessage Create a map message.
CreateMessage Create a message that has no body.
CreateObjectMessage Create an object message.
CreateProducer Create a message producer to send messages to the specified destination.
CreateQueue Create a Destination object to represent a queue in the messaging server.
CreateStreamMessage Create a stream message.
CreateTemporaryQueue Create a temporary queue.
CreateTemporaryTopic Create a temporary topic.
CreateTextMessage Create a text message with an empty body.
CreateTextMessage Create a text message whose body is initialized with the specified text.
CreateTopic Create a Destination object to represent a topic.
Recover Recover the session.
Rollback Rollback all messages processed in the current transaction.
Unsubscribe Delete a durable subscription.

Close – Close Session

Interface:
void Close();

Close the session. If the session is transacted, any transaction in progress is rolled back.

If an application tries to close a session that is already closed, the call is ignored.

Parameters:
None
Returns:
Void
Thread context:
Any
Exceptions:
  • XMSException

Commit – Commit

Interface:
void Commit();

Commit all messages processed in the current transaction.

The session must be a transacted session.

Parameters:
None
Returns:
Void
Exceptions:
  • XMSException
  • IllegalStateException
  • TransactionRolledBackException

CreateBrowser – Create Queue Browser

Interface:
IQueueBrowser CreateBrowser(IDestination queue) ;

Create a queue browser for the specified queue.

Parameters:
queue (input)
A Destination object representing the queue.
Returns:
The QueueBrowser object.
Exceptions:
  • XMSException
  • InvalidDestinationException

CreateBrowser – Create Queue Browser (with message selector)

Interface:
IQueueBrowser CreateBrowser(IDestination queue, String selector) ;

Create a queue browser for the specified queue using a message selector.

Parameters:
queue (input)
A Destination object representing the queue.
selector (input)
A String object encapsulating a message selector expression. Only those messages with properties that match the message selector expression are delivered to the queue browser.

A null String object means that there is no message selector for the queue browser.

Returns:
The QueueBrowser object.
Exceptions:
  • XMSException
  • InvalidDestinationException
  • InvalidSelectorException

CreateBytesMessage – Create Bytes Message

Interface:
IBytesMessage CreateBytesMessage();

Create a bytes message.

Parameters:
None
Returns:
The BytesMessage object.
Exceptions:
  • XMSException
  • IllegalStateException (The session is closed)

CreateConsumer – Create Consumer

Interface:
IMessageConsumer CreateConsumer(IDestination dest) ;

Create a message consumer for the specified destination.

Parameters:
dest (input)
The Destination object.
Returns:
The MessageConsumer object.
Exceptions:
  • XMSException
  • InvalidDestinationException

CreateConsumer – Create Consumer (with message selector)

Interface:
IMessageConsumer CreateConsumer(IDestination dest, 
                                String selector) ;

Create a message consumer for the specified destination using a message selector.

Parameters:
dest (input)
The Destination object.
selector (input)
A String object encapsulating a message selector expression. Only those messages with properties that match the message selector expression are delivered to the message consumer.

A null String object means that there is no message selector for the message consumer.

Returns:
The MessageConsumer object.
Exceptions:
  • XMSException
  • InvalidDestinationException
  • InvalidSelectorException

CreateConsumer – Create Consumer (with message selector and local message flag)

Interface:
IMessageConsumer CreateConsumer(IDestination dest, 
                                String selector, 
                                Boolean noLocal) ;

Create a message consumer for the specified destination using a message selector and, if the destination is a topic, specifying whether the message consumer receives the messages published by its own connection.

Parameters:
dest (input)
The Destination object.
selector (input)
A String object encapsulating a message selector expression. Only those messages with properties that match the message selector expression are delivered to the message consumer.

A null String object means that there is no message selector for the message consumer.

noLocal (input)
The value True means that the message consumer does not receive the messages published by its own connection. The value False means that the message consumer does receive the messages published by its own connection. The default value is False.
Returns:
The MessageConsumer object.
Exceptions:
  • XMSException
  • InvalidDestinationException
  • InvalidSelectorException

CreateDurableSubscriber – Create Durable Subscriber

Interface:
IMessageConsumer CreateDurableSubscriber(IDestination dest, 
                                         String subscription) ;

Create a durable subscriber for the specified topic.

This method is not valid for a real-time connection to a broker.

For more information about durable subscribers, see Durable subscribers.

Parameters:
dest (input)
A Destination object representing the topic. The topic must not be a temporary topic.
subscription (input)
A String object encapsulating a name that identifies the durable subscription. The name must be unique within the client identifier for the connection.
Returns:
The MessageConsumer object representing the durable subscriber.
Exceptions:
  • XMSException
  • InvalidDestinationException

CreateDurableSubscriber – Create Durable Subscriber (with message selector and local message flag)

Interface:
IMessageConsumer CreateDurableSubscriber(IDestination dest, 
                                         String subscription, 
                                         String selector, 
                                         Boolean noLocal) ;

Create a durable subscriber for the specified topic using a message selector and specifying whether the durable subscriber receives the messages published by its own connection.

This method is not valid for a real-time connection to a broker.

For more information about durable subscribers, see Durable subscribers.

Parameters:
dest (input)
A Destination object representing the topic. The topic must not be a temporary topic.
subscription (input)
A String object encapsulating a name that identifies the durable subscription. The name must be unique within the client identifier for the connection.
selector (input)
A String object encapsulating a message selector expression. Only those messages with properties that match the message selector expression are delivered to the durable subscriber.

A null String object means that there is no message selector for the durable subscriber.

noLocal (input)
The value True means that the durable subscriber does not receive the messages published by its own connection. The value False means that the durable subscriber does receive the messages published by its own connection. The default value is False.
Returns:
The MessageConsumer object representing the durable subscriber.
Exceptions:
  • XMSException
  • InvalidDestinationException
  • InvalidSelectorException

CreateMapMessage – Create Map Message

Interface:
IMapMessage CreateMapMessage();

Create a map message.

Parameters:
None
Returns:
The MapMessage object.
Exceptions:
  • XMSException
  • IllegalStateException (The session is closed)

CreateMessage – Create Message

Interface:
IMessage CreateMessage();

Create a message that has no body.

Parameters:
None
Returns:
The Message object.
Exceptions:
  • XMSException
  • IllegalStateException (The session is closed)

CreateObjectMessage – Create Object Message

Interface:
IObjectMessage CreateObjectMessage();

Create an object message.

Parameters:
None
Returns:
The ObjectMessage object.
Exceptions:
  • XMSException
  • IllegalStateException (The session is closed)

CreateProducer – Create Producer

Interface:
IMessageProducer CreateProducer(IDestination dest) ;

Create a message producer to send messages to the specified destination.

Parameters:
dest (input)
The Destination object.

If you specify a null Destination object, the message producer is created without a destination. In this case, the application must specify a destination every time it uses the message producer to send a message.

Returns:
The MessageProducer object.
Exceptions:
  • XMSException
  • InvalidDestinationException

CreateQueue – Create Queue

Interface:
IDestination CreateQueue(String queue) ;

Create a Destination object to represent a queue in the messaging server.

This method does not create the queue in the messaging server. You must create the queue before an application can call this method.

Parameters:
queue (input)
A String object encapsulating the name of the queue, or encapsulating a uniform resource identifier (URI) that identifies the queue.
Returns:
The Destination object representing the queue.
Exceptions:
  • XMSException

CreateStreamMessage – Create Stream Message

Interface:
IStreamMessage CreateStreamMessage();

Create a stream message.

Parameters:
None
Returns:
The StreamMessage object.
Exceptions:
  • XMSException
  • XMS_ILLEGAL_STATE_EXCEPTION

CreateTemporaryQueue – Create Temporary Queue

Interface:
IDestination CreateTemporaryQueue() ;

Create a temporary queue.

The scope of the temporary queue is the connection. Only the sessions created by the connection can use the temporary queue.

The temporary queue remains until it is explicitly deleted, or the connection ends, whichever is the sooner.

For more information about temporary queues, see Temporary destinations.

Parameters:
None
Returns:
The Destination object representing the temporary queue.
Exceptions:
  • XMSException

CreateTemporaryTopic – Create Temporary Topic

Interface:
IDestination CreateTemporaryTopic() ;

Create a temporary topic.

The scope of the temporary topic is the connection. Only the sessions created by the connection can use the temporary topic.

The temporary topic remains until it is explicitly deleted, or the connection ends, whichever is the sooner.

For more information about temporary topics, see Temporary destinations.

Parameters:
None
Returns:
The Destination object representing the temporary topic.
Exceptions:
  • XMSException

CreateTextMessage – Create Text Message

Interface:
ITextMessage CreateTextMessage();

Create a text message with an empty body.

Parameters:
None
Returns:
The TextMessage object.
Exceptions:
  • XMSException

CreateTextMessage – Create Text Message (initialized)

Interface:
ITextMessage CreateTextMessage(String initialValue);

Create a text message whose body is initialized with the specified text.

Parameters:
initialValue (input)
A String object encapsulating the text to initialize the body of the text message.
None
Returns:
The TextMessage object.
Exceptions:
  • XMSException

CreateTopic – Create Topic

Interface:
IDestination CreateTopic(String topic) ;

Create a Destination object to represent a topic.

Parameters:
topic (input)
A String object encapsulating the name of the topic, or encapsulating a uniform resource identifier (URI) that identifies the topic.
Returns:
The Destination object representing the topic.
Exceptions:
  • XMSException

Recover – Recover

Interface:
void Recover();

Recover the session. Message delivery is stopped and then restarted with the oldest unacknowledged message.

The session must not be a transacted session.

For more information about recovering a session, see Message acknowledgement.

Parameters:
None
Returns:
Void
Exceptions:
  • XMSException
  • IllegalStateException

Rollback – Rollback

Interface:
void Rollback();

Rollback all messages processed in the current transaction.

The session must be a transacted session.

Parameters:
None
Returns:
Void
Exceptions:
  • XMSException
  • IllegalStateException

Unsubscribe – Unsubscribe

Interface:
void Unsubscribe(String subscription);

Delete a durable subscription. The messaging server deletes the record of the durable subscription that it is maintaining and does not send any more messages to the durable subscriber.

An application cannot delete a durable subscription in any of the following circumstances:
  • While there is an active message consumer for the durable subscription
  • While a consumed message is part of a pending transaction
  • While a consumed message has not been acknowledged

This method is not valid for a real-time connection to a broker.

Parameters:
subscription (input)
A String object encapsulating the name that identifies the durable subscription.
Returns:
Void
Exceptions:
  • XMSException
  • InvalidDestinationException
  • IllegalStateException

Inherited properties and methods


Reference topic

Terms of Use | Rate this page

Last updated: 18 Jun 2008

© Copyright IBM Corporation 2005, 2008. All Rights Reserved.