View Javadoc

    1   /***
    2    *
    3    * Copyright 2004 Protique Ltd
    4    *
    5    * Licensed under the Apache License, Version 2.0 (the "License");
    6    * you may not use this file except in compliance with the License.
    7    * You may obtain a copy of the License at
    8    *
    9    * http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   *
    17   **/
    18
    19  package org.codehaus.activemq;
    20
    21  import org.codehaus.activemq.message.ActiveMQDestination;
    22
    23  import javax.jms.Destination;
    24  import javax.jms.InvalidDestinationException;
    25  import javax.jms.JMSException;
    26  import javax.jms.Message;
    27  import javax.jms.MessageFormatException;
    28  import javax.jms.Queue;
    29  import javax.jms.QueueSender;
    30
    31  /***
    32   * A client uses a <CODE>QueueSender</CODE> object to send messages to a
    33   * queue.
    34   * <p/>
    35   * <P>
    36   * Normally, the <CODE>Queue</CODE> is specified when a <CODE>QueueSender
    37   * </CODE> is created. In this case, an attempt to use the <CODE>send</CODE>
    38   * methods for an unidentified <CODE>QueueSender</CODE> will throw a <CODE>
    39   * java.lang.UnsupportedOperationException</CODE>.
    40   * <p/>
    41   * <P>
    42   * If the <CODE>QueueSender</CODE> is created with an unidentified <CODE>
    43   * Queue</CODE>, an attempt to use the <CODE>send</CODE> methods that
    44   * assume that the <CODE>Queue</CODE> has been identified will throw a <CODE>
    45   * java.lang.UnsupportedOperationException</CODE>.
    46   * <p/>
    47   * <P>
    48   * During the execution of its <CODE>send</CODE> method, a message must not
    49   * be changed by other threads within the client. If the message is modified,
    50   * the result of the <CODE>send</CODE> is undefined.
    51   * <p/>
    52   * <P>
    53   * After sending a message, a client may retain and modify it without affecting
    54   * the message that has been sent. The same message object may be sent multiple
    55   * times.
    56   * <p/>
    57   * <P>
    58   * The following message headers are set as part of sending a message: <code>JMSDestination</code>,
    59   * <code>JMSDeliveryMode</code>,<code>JMSExpiration</code>,<code>JMSPriority</code>,
    60   * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>. When the
    61   * message is sent, the values of these headers are ignored. After the
    62   * completion of the <CODE>send</CODE>, the headers hold the values
    63   * specified by the method sending the message. It is possible for the <code>send</code>
    64   * method not to set <code>JMSMessageID</code> and <code>JMSTimeStamp</code>
    65   * if the setting of these headers is explicitly disabled by the <code>MessageProducer.setDisableMessageID</code>
    66   * or <code>MessageProducer.setDisableMessageTimestamp</code> method.
    67   * <p/>
    68   * <P>
    69   * Creating a <CODE>MessageProducer</CODE> provides the same features as
    70   * creating a <CODE>QueueSender</CODE>. A <CODE>MessageProducer</CODE>
    71   * object is recommended when creating new code. The <CODE>QueueSender</CODE>
    72   * is provided to support existing code.
    73   *
    74   * @see javax.jms.MessageProducer
    75   * @see javax.jms.Session#createProducer(Destination)
    76   * @see javax.jms.QueueSession#createSender(Queue)
    77   */
    78
    79  public class ActiveMQQueueSender extends ActiveMQMessageProducer implements
    80          QueueSender {
    81
    82      protected ActiveMQQueueSender(ActiveMQSession session,
    83                                    ActiveMQDestination destination) throws JMSException {
    84          super(session, destination);
    85      }
    86
    87      /***
    88       * Gets the queue associated with this <CODE>QueueSender</CODE>.
    89       *
    90       * @return this sender's queue
    91       * @throws JMSException if the JMS provider fails to get the queue for this
    92       *                      <CODE>QueueSender</CODE> due to some internal error.
    93       */
    94
    95      public Queue getQueue() throws JMSException {
    96          return (Queue) super.getDestination();
    97      }
    98
    99      /***
    100      * Sends a message to a queue for an unidentified message producer. Uses
    101      * the <CODE>QueueSender</CODE>'s default delivery mode, priority, and
    102      * time to live.
    103      * <p/>
    104      * <P>
    105      * Typically, a message producer is assigned a queue at creation time;
    106      * however, the JMS API also supports unidentified message producers, which
    107      * require that the queue be supplied every time a message is sent.
    108      *
    109      * @param queue   the queue to send this message to
    110      * @param message the message to send
    111      * @throws JMSException                if the JMS provider fails to send the message due to some
    112      *                                     internal error.
    113      * @throws MessageFormatException      if an invalid message is specified.
    114      * @throws InvalidDestinationException if a client uses this method with an invalid queue.
    115      * @see javax.jms.MessageProducer#getDeliveryMode()
    116      * @see javax.jms.MessageProducer#getTimeToLive()
    117      * @see javax.jms.MessageProducer#getPriority()
    118      */
    119
    120     public void send(Queue queue, Message message) throws JMSException {
    121         super.send(queue, message);
    122     }
    123
    124     /***
    125      * Sends a message to a queue for an unidentified message producer,
    126      * specifying delivery mode, priority and time to live.
    127      * <p/>
    128      * <P>
    129      * Typically, a message producer is assigned a queue at creation time;
    130      * however, the JMS API also supports unidentified message producers, which
    131      * require that the queue be supplied every time a message is sent.
    132      *
    133      * @param queue        the queue to send this message to
    134      * @param message      the message to send
    135      * @param deliveryMode the delivery mode to use
    136      * @param priority     the priority for this message
    137      * @param timeToLive   the message's lifetime (in milliseconds)
    138      * @throws JMSException                if the JMS provider fails to send the message due to some
    139      *                                     internal error.
    140      * @throws MessageFormatException      if an invalid message is specified.
    141      * @throws InvalidDestinationException if a client uses this method with an invalid queue.
    142      */
    143
    144     public void send(Queue queue, Message message, int deliveryMode,
    145                      int priority, long timeToLive) throws JMSException {
    146         super.send(queue, message, deliveryMode, priority, timeToLive);
    147     }
    148 }