KMQueueSession Class Reference
Overview
A QueueSession object provides methods for creating QueueReceiver, QueueSender, QueueBrowser, and TemporaryQueue objects.
KMQueueSession is a JMS 1.0 API. KMSession should be used instead.
If there are messages that have been received but not acknowledged when a QueueSession terminates, these messages will be retained and redelivered when a consumer next accesses the queue.
A QueueSession is used for creating Point-to-Point specific objects. In general, use the KMSession object. Using the KMSession object simplifies the programming model, and allows transactions to be used across the two messaging domains.
A QueueSession cannot be used to create objects specific to the publish/subscribe domain. The following methods inherit from Session, but must throw a KMIllegalStateException if they are used from QueueSession:
- createDurableSubscriber
- createTemporaryTopic
- createTopic
- unsubscribe
Tasks
-
– createQueue:
Creates a queue identity given a Queue name.
-
– createReceiver:
Creates a QueueReceiver object to receive messages from the specified queue.
-
– createReceiver:messageSelector:
Creates a QueueReceiver object to receive messages from the specified queue using a message selector.
-
– createSender:
Creates a QueueSender object to send messages to the specified queue.
-
– createBrowser:
Creates a QueueBrowser object to peek at the messages on the specified queue.
-
– createBrowser:messageSelector:
Creates a QueueBrowser object to peek at the messages on the specified queue using a message selector.
-
– createTemporaryQueue
Creates a TemporaryQueue object. Its lifetime will be that of the QueueConnection unless it is deleted earlier.
Instance Methods
createBrowser:
Creates a QueueBrowser object to peek at the messages on the specified queue.
- (KMQueueBrowser *)createBrowser:(KMQueue *)queue
Parameters
- queue
the Queue to access
Exceptions
- KMJMSException
if the session fails to create a browser due to some internal error.
- KMInvalidDestinationException
if an invalid queue is specified.
Declared In
KMQueueSession.h
createBrowser:messageSelector:
Creates a QueueBrowser object to peek at the messages on the specified queue using a message selector.
- (KMQueueBrowser *)createBrowser:(KMQueue *)queue messageSelector:(NSString *)messageSelector
Parameters
- queue
the Queue to access
- messageSelector
only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.
Exceptions
- KMJMSException
if the session fails to create a browser due to some internal error.
- KMInvalidDestinationException
if an invalid queue is specified.
- KMInvalidSelectorException
if the message selector is invalid.
Declared In
KMQueueSession.h
createQueue:
Creates a queue identity given a Queue name.
- (KMQueue *)createQueue:(NSString *)queueName
Parameters
- queueName
the name of this Queue
Return Value
a Queue with the given name
Discussion
This facility is provided for the rare cases where clients need to dynamically manipulate queue identity. It allows the creation of a queue identity with a provider-specific name. Clients that depend on this ability are not portable.
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 JMS API. The one exception is the creation of temporary queues, which is accomplished with the createTemporaryQueue method.
Exceptions
- KMJMSException
if the session fails to create a queue due to some internal error.
Declared In
KMQueueSession.h
createReceiver:
Creates a QueueReceiver object to receive messages from the specified queue.
- (KMQueueReceiver *)createReceiver:(KMQueue *)queue
Parameters
- queue
the Queue to access
Exceptions
- KMJMSException
if the session fails to create a receiver due to some internal error.
- KMInvalidDestinationException
if an invalid queue is specified.
Declared In
KMQueueSession.h
createReceiver:messageSelector:
Creates a QueueReceiver object to receive messages from the specified queue using a message selector.
- (KMQueueReceiver *)createReceiver:(KMQueue *)queue messageSelector:(NSString *)messageSelector
Parameters
- queue
the Queue to access
- messageSelector
only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.
Exceptions
- KMJMSException
if the session fails to create a receiver due to some internal error.
- KMInvalidDestinationException
if an invalid queue is specified.
- KMInvalidSelectorException
if the message selector is invalid.
Declared In
KMQueueSession.h
createSender:
Creates a QueueSender object to send messages to the specified queue.
- (KMQueueSender *)createSender:(KMQueue *)queue
Parameters
- queue
the Queue to access, or null if this is an unidentified producer
Exceptions
- KMJMSException
if the session fails to create a sender due to some internal error.
- KMInvalidDestinationException
if an invalid queue is specified.
Declared In
KMQueueSession.h
createTemporaryQueue
Creates a TemporaryQueue object. Its lifetime will be that of the QueueConnection unless it is deleted earlier.
- (KMTemporaryQueue *)createTemporaryQueue
Return Value
a temporary queue identity
Exceptions
- KMJMSException
if the session fails to create a temporary queue due to some internal error.
Declared In
KMQueueSession.h