jmssession.java

来自「OpenJMS是一个开源的Java Message Service API 1.」· Java 代码 · 共 1,363 行 · 第 1/4 页

        return (_ackMode == SESSION_TRANSACTED);
    }

    /**
     * Returns the acknowledgement mode of the session. The acknowledgement mode
     * is set at the time that the session is created. If the session is
     * transacted, the acknowledgement mode is ignored.
     *
     * @return If the session is not transacted, returns the current
     *         acknowledgement mode for the session. If the session is
     *         transacted, returns SESSION_TRANSACTED.
     * @throws JMSException if the JMS provider fails to return the
     *                      acknowledgment mode due to some internal error.
     * @see Connection#createSession
     */
    public int getAcknowledgeMode() throws JMSException {
        ensureOpen();
        return _ackMode;
    }

    /**
     * Creates a <code>MessageProducer</code> to send messages to the specified
     * destination.
     *
     * @param destination the <code>Destination</code> to send to, or null if
     *                    this is a producer which does not have a specified
     *                    destination.
     * @throws JMSException                if the session fails to create a
     *                                     MessageProducer due to some internal
     *                                     error.
     * @throws InvalidDestinationException if an invalid destination is
     *                                     specified.
     */
    public MessageProducer createProducer(Destination destination)
            throws JMSException {
        ensureOpen();
        return new JmsMessageProducer(this, destination);
    }

    /**
     * Creates a <code>MessageConsumer</code> for the specified destination.
     *
     * @param destination the <code>Destination</code> to access.
     * @throws JMSException                if the session fails to create a
     *                                     consumer due to some internal error.
     * @throws InvalidDestinationException if an invalid destination is
     *                                     specified.
     */

    public MessageConsumer createConsumer(Destination destination)
            throws JMSException {
        return createConsumer(destination, null);
    }

    /**
     * Creates a <code>MessageProducer</code> to receive messages from the
     * specified destination, matching particular selection criteria
     *
     * @param destination     the <code>Destination</code> to access
     * @param 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
     *                                     MessageConsumer due to some internal
     *                                     error.
     * @throws InvalidDestinationException if an invalid destination is
     *                                     specified.
     * @throws InvalidSelectorException    if the message selector is invalid.
     */
    public MessageConsumer createConsumer(Destination destination,
                                          String messageSelector)
            throws JMSException {
        return createConsumer(destination, messageSelector, false);
    }

    /**
     * Creates a <code>MessageConsumer</code> to receive messages from the
     * specified destination, matching particular selection criteria. This
     * method can specify whether messages published by its own connection
     * should be delivered to it, if the destination is a topic. <P>In some
     * cases, a connection may both publish and subscribe to a topic. The
     * consumer <code>noLocal</code> attribute allows a consumer to inhibit the
     * delivery of messages published by its own connection. The default value
     * for this attribute is false. The <code>noLocal</code> value must be
     * supported by destinations that are topics.
     *
     * @param destination     the <code>Destination</code> to access
     * @param 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.
     * @param noLocal         if true, and the destination is a topic, inhibits
     *                        the delivery of messages published by its own
     *                        connection.  The behavior for <code>noLocal</code>
     *                        is not specified if the destination is a queue.
     * @throws JMSException                if the session fails to create a
     *                                     MessageConsumer due to some internal
     *                                     error.
     * @throws InvalidDestinationException if an invalid destination is
     *                                     specified.
     * @throws InvalidSelectorException    if the message selector is invalid.
     */
    public MessageConsumer createConsumer(Destination destination,
                                          String messageSelector,
                                          boolean noLocal) throws JMSException {
        long consumerId = allocateConsumer(destination, messageSelector,
                                           noLocal);
        JmsMessageConsumer consumer = new JmsMessageConsumer(this, consumerId,
                                                             destination,
                                                             messageSelector);
        addConsumer(consumer);
        return consumer;
    }

    /**
     * Creates a queue identity given a <code>Queue</code> name.
     * <p/>
     * <P>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.
     * <p/>
     * <P>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 <code>createTemporaryQueue</code>
     * method.
     *
     * @param queueName the name of this <code>Queue</code>
     * @return a <code>Queue</code> with the given name
     * @throws JMSException if the session fails to create a queue due to some
     *                      internal error.
     */
    public Queue createQueue(String queueName) throws JMSException {
        ensureOpen();

        JmsQueue queue;

        if (queueName != null && queueName.length() > 0) {
            queue = new JmsQueue(queueName);
        } else {
            throw new JMSException(
                    "Cannot create a queue with null or empty name");
        }

        return queue;
    }

    /**
     * Creates a topic identity given a <code>Topic</code> name.
     * <p/>
     * <P>This facility is provided for the rare cases where clients need to
     * dynamically manipulate topic identity. This allows the creation of a
     * topic identity with a provider-specific name. Clients that depend on this
     * ability are not portable.
     * <p/>
     * <P>Note that 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 JMS API. The one exception is the creation of temporary
     * topics, which is accomplished with the <code>createTemporaryTopic</code>
     * method.
     *
     * @param topicName the name of this <code>Topic</code>
     * @return a <code>Topic</code> with the given name
     * @throws JMSException if the session fails to create a topic due to some
     *                      internal error.
     */
    public Topic createTopic(String topicName) throws JMSException {
        ensureOpen();

        JmsTopic topic;

        if (topicName != null && topicName.length() > 0) {
            topic = new JmsTopic(topicName);
        } else {
            throw new JMSException("Invalid or null topic name specified");
        }

        return topic;
    }

    /**
     * Creates a durable subscriber to the specified topic.
     * <p/>
     * <P>If a client needs to receive all the messages published on a topic,
     * including the ones published while the subscriber is inactive, it uses a
     * durable <code>TopicSubscriber</code>. The JMS provider retains a record
     * of this durable subscription and insures that all messages from the
     * topic's publishers are retained until they are acknowledged by this
     * durable subscriber or they have expired.
     * <p/>
     * <P>Sessions with durable subscribers must always provide the same client
     * identifier. In addition, each client must specify a name that uniquely
     * identifies (within client identifier) each durable subscription it
     * creates. Only one session at a time can have a <code>TopicSubscriber</code>
     * for a particular durable subscription.
     * <p/>
     * <P>A client can change an existing durable subscription by creating a
     * durable <code>TopicSubscriber</code> with the same name and a new topic
     * and/or message selector. Changing a durable subscriber is equivalent to
     * unsubscribing (deleting) the old one and creating a new one.
     * <p/>
     * <P>In some cases, a connection may both publish and subscribe to a topic.
     * The subscriber <code>noLocal</code> attribute allows a subscriber to
     * inhibit the delivery of messages published by its own connection. The
     * default value for this attribute is false.
     *
     * @param topic the non-temporary <code>Topic</code> to subscribe to
     * @param name  the name used to identify this subscription
     * @throws JMSException                if the session fails to create a
     *                                     subscriber due to some internal
     *                                     error.
     * @throws InvalidDestinationException if an invalid topic is specified.
     */
    public TopicSubscriber createDurableSubscriber(Topic topic, String name)
            throws JMSException {
        return createDurableSubscriber(topic, name, null, false);
    }

    /**
     * Creates 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.
     * <p/>
     * <P>If a client needs to receive all the messages published on a topic,
     * including the ones published while the subscriber is inactive, it uses a
     * durable <code>TopicSubscriber</code>. The JMS provider retains a record
     * of this durable subscription and insures that all messages from the
     * topic's publishers are retained until they are acknowledged by this
     * durable subscriber or they have expired.
     * <p/>
     * <P>Sessions with durable subscribers must always provide the same client
     * identifier. In addition, each client must specify a name which uniquely
     * identifies (within client identifier) each durable subscription it
     * creates. Only one session at a time can have a <code>TopicSubscriber</code>
     * for a particular durable subscription. An inactive durable subscriber is
     * one that exists but does not currently have a message consumer associated
     * with it.
     * <p/>
     * <P>A client can change an existing durable subscription by creating a
     * durable <code>TopicSubscriber</code> with the same name and a new topic
     * and/or message selector. Changing a durable subscriber is equivalent to
     * unsubscribing (deleting) the old one and creating a new one.
     *
     * @param topic           the non-temporary <code>Topic</code> to subscribe
     *                        to
     * @param name            the name used to identify this subscription
     * @param 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.
     * @param noLocal         if set, inhibits the delivery of messages
     *                        published by its own connection
     * @throws JMSException                if the session fails to create a
     *                                     subscriber due to some internal
     *                                     error.
     * @throws InvalidDestinationException if an invalid topic is specified.
     * @throws InvalidSelectorException    if the message selector is invalid.
     */
    public TopicSubscriber createDurableSubscriber(Topic topic, String name,
                                                   String messageSelector,
                                                   boolean noLocal)
            throws JMSException {
        ensureOpen();

        if (topic == null) {
            throw new InvalidDestinationException("Cannot create durable subscriber: argument 'topic' is "
                                                  + " null");
        }
        if (name == null || name.trim().length() == 0) {
            throw new JMSException("Invalid subscription name specified");
        }

        // check to see if the topic is a temporary topic. You cannot
        // create a durable subscriber for a temporary topic
        if (((JmsTopic) topic).isTemporaryDestination()) {
            throw new InvalidDestinationException(
                    "Cannot create a durable subscriber for a temporary topic");
        }

        long consumerId = _session.createDurableConsumer((JmsTopic) topic, name,
                                                         messageSelector,
                                                         noLocal);
        JmsTopicSubscriber subscriber = new JmsTopicSubscriber(this,
                                                               consumerId,
                                                               topic,
                                                               messageSelector,
                                                               noLocal);
        addConsumer(subscriber);

        return subscriber;
    }

    /**
     * Creates a <code>QueueBrowser</code> object to peek at the messages on the
     * specified queue.
     *
     * @param queue the queue to access
     * @throws JMSException                if the session fails to create a
     *                                     browser due to some internal error.
     * @throws InvalidDestinationException if an invalid destination is
     *                                     specified
     */
    public QueueBrowser createBrowser(Queue queue) throws JMSException {
        return createBrowser(queue, null);
    }

    /**
     * Creates a <code>QueueBrowser</code> object to peek at the messages on the
     * specified queue using a message selector.
     *
     * @param queue           the <code>queue</code> to access
     * @param 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.
     * @throws InvalidDestinationException if an invalid destination is
     *                                     specified
     * @throws InvalidSelectorException    if the message selector is invalid.
     */
    public QueueBrowser createBrowser(Queue queue, String messageSelector)
            throws JMSException {
        ensureOpen();
        if (!(queue instanceof JmsQueue)) {
            throw new InvalidDestinationException("Cannot create QueueBrowser for destination="
                                                  + queue);
        }

        JmsQueue dest = (JmsQueue) queue;
        // check to see if the queue is temporary. A temporary queue
        // can only be used within the context of the owning connection
        if (!checkForValidTemporaryDestination(dest)) {
            throw new InvalidDestinationException(
                    "Cannot create a queue browser for a temporary queue "
                    + "that is not bound to this connection");
        }

        long consumerId = _session.createBrowser(dest, messageSelector);