ISession

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

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

Parent topic: .NET interfaces


.NET properties

    Summary of .NET properties:

    .NET property Description
    AcknowledgeMode Get the acknowledgment mode for the session.
    Transacted Determine whether the session is transacted.


AcknowledgeMode - Get Acknowledgement Mode

    Interface:
    AcknowledgeMode AcknowledgeMode
    {
      get;
    }

Get the acknowledgment mode for the session.

The acknowledgment mode is specified when the session is created.

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

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

For more information about acknowledgment modes, see Message acknowledgment.

A session that is transacted has no acknowledgment 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 Roll back 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. We 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 acknowledgment.

    Parameters:
    None

    Returns:
    Void

    Exceptions:

    • XMSException
    • IllegalStateException


Rollback - Rollback

    Interface:
    void Rollback();

Roll back 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 was not 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

The following methods are inherited from the IPropertyContext interface: