javax.jms

## Interface QueueSession

- All Superinterfaces:
    AutoCloseable, Runnable, Session

      public interface QueueSession
      extends Session

  A `QueueSession` object provides methods for creating `QueueReceiver`, `QueueSender`, `QueueBrowser`, and `TemporaryQueue` objects.

  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 `Session` object. The `QueueSession` is used to support existing code. Using the `Session` 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 an `IllegalStateException` if they are used from `QueueSession`:

  - `createDurableSubscriber`
  - `createDurableConsumer`
  - `createSharedConsumer`
  - `createSharedDurableConsumer`
  - `createTemporaryTopic`
  - `createTopic`
  - `unsubscribe`
  Since:
    JMS 1.0
  See Also:
    `Session`, `QueueConnection.createQueueSession(boolean, int)`, `XAQueueSession.getQueueSession()`

- - ### Field Summary

    - ### Fields inherited from interface javax.jms.Session

      `AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `QueueBrowser` | `createBrowser(Queue queue)` Creates a `QueueBrowser` object to peek at the messages on the specified queue.
    `QueueBrowser` | `createBrowser(Queue queue, String messageSelector)` Creates a `QueueBrowser` object to peek at the messages on the specified queue using a message selector.
    `Queue` | `createQueue(String queueName)` Creates a queue identity given a `Queue` name.
    `QueueReceiver` | `createReceiver(Queue queue)` Creates a `QueueReceiver` object to receive messages from the specified queue.
    `QueueReceiver` | `createReceiver(Queue queue, String messageSelector)` Creates a `QueueReceiver` object to receive messages from the specified queue using a message selector.
    `QueueSender` | `createSender(Queue queue)` Creates a `QueueSender` object to send messages to the specified queue.
    `TemporaryQueue` | `createTemporaryQueue()` Creates a `TemporaryQueue` object.

    - ### Methods inherited from interface javax.jms.Session

      `close, commit, createBytesMessage, createConsumer, createConsumer, createConsumer, createDurableConsumer, createDurableConsumer, createDurableSubscriber, createDurableSubscriber, createMapMessage, createMessage, createObjectMessage, createObjectMessage, createProducer, createSharedConsumer, createSharedConsumer, createSharedDurableConsumer, createSharedDurableConsumer, createStreamMessage, createTemporaryTopic, createTextMessage, createTextMessage, createTopic, getAcknowledgeMode, getMessageListener, getTransacted, recover, rollback, run, setMessageListener, unsubscribe`

- - ### Method Detail

    - #### createQueue

          Queue createQueue(String queueName)
                            throws JMSException

      Creates a queue identity given a `Queue` name.

      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.

      Specified by:
        `createQueue` in interface `Session`
      Parameters:
        `queueName` - the name of this `Queue`
      Returns:
        a `Queue` with the given name
      Throws:
        `JMSException` - if the session fails to create a queue due to some internal error.

    - #### createReceiver

          QueueReceiver createReceiver(Queue queue)
                                       throws JMSException

      Creates a `QueueReceiver` object to receive messages from the specified queue.
      Parameters:
        `queue` - the `Queue` to access
      Throws:
        `JMSException` - if the session fails to create a receiver due to some internal error.
        `InvalidDestinationException` - if an invalid queue is specified.

    - #### createReceiver

          QueueReceiver createReceiver(Queue queue,
                                     String messageSelector)
                                       throws JMSException

      Creates a `QueueReceiver` object to receive messages from the specified queue using a message selector.
      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.
      Throws:
        `JMSException` - if the session fails to create a receiver due to some internal error.
        `InvalidDestinationException` - if an invalid queue is specified.
        `InvalidSelectorException` - if the message selector is invalid.

    - #### createSender

          QueueSender createSender(Queue queue)
                                   throws JMSException

      Creates a `QueueSender` object to send messages to the specified queue.
      Parameters:
        `queue` - the `Queue` to access, or null if this is an unidentified producer
      Throws:
        `JMSException` - if the session fails to create a sender due to some internal error.
        `InvalidDestinationException` - if an invalid queue is specified.

    - #### createBrowser

          QueueBrowser createBrowser(Queue queue)
                                     throws JMSException

      Creates a `QueueBrowser` object to peek at the messages on the specified queue.
      Specified by:
        `createBrowser` in interface `Session`
      Parameters:
        `queue` - the `Queue` to access
      Throws:
        `JMSException` - if the session fails to create a browser due to some internal error.
        `InvalidDestinationException` - if an invalid queue is specified.

    - #### createBrowser

          QueueBrowser createBrowser(Queue queue,
                                   String messageSelector)
                                     throws JMSException

      Creates a `QueueBrowser` object to peek at the messages on the specified queue using a message selector.
      Specified by:
        `createBrowser` in interface `Session`
      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.
      Throws:
        `JMSException` - if the session fails to create a browser due to some internal error.
        `InvalidDestinationException` - if an invalid queue is specified.
        `InvalidSelectorException` - if the message selector is invalid.

    - #### createTemporaryQueue

          TemporaryQueue createTemporaryQueue()
                                              throws JMSException

      Creates a `TemporaryQueue` object. Its lifetime will be that of the `QueueConnection` unless it is deleted earlier.
      Specified by:
        `createTemporaryQueue` in interface `Session`
      Returns:
        a temporary queue identity
      Throws:
        `JMSException` - if the session fails to create a temporary queue due to some internal error.

Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.