001    /** 
002     * 
003     * Copyright 2004 Protique Ltd
004     * 
005     * Licensed under the Apache License, Version 2.0 (the "License"); 
006     * you may not use this file except in compliance with the License. 
007     * You may obtain a copy of the License at 
008     * 
009     * http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS, 
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
014     * See the License for the specific language governing permissions and 
015     * limitations under the License. 
016     * 
017     **/
018    
019    package org.activemq;
020    
021    import javax.jms.JMSException;
022    import javax.jms.Message;
023    import javax.jms.Queue;
024    import javax.jms.QueueSender;
025    
026    import org.activemq.message.ActiveMQDestination;
027    
028    /**
029     * A client uses a <CODE>QueueSender</CODE> object to send messages to a
030     * queue.
031     * <p/>
032     * <P>
033     * Normally, the <CODE>Queue</CODE> is specified when a <CODE>QueueSender
034     * </CODE> is created. In this case, an attempt to use the <CODE>send</CODE>
035     * methods for an unidentified <CODE>QueueSender</CODE> will throw a <CODE>
036     * java.lang.UnsupportedOperationException</CODE>.
037     * <p/>
038     * <P>
039     * If the <CODE>QueueSender</CODE> is created with an unidentified <CODE>
040     * Queue</CODE>, an attempt to use the <CODE>send</CODE> methods that
041     * assume that the <CODE>Queue</CODE> has been identified will throw a <CODE>
042     * java.lang.UnsupportedOperationException</CODE>.
043     * <p/>
044     * <P>
045     * During the execution of its <CODE>send</CODE> method, a message must not
046     * be changed by other threads within the client. If the message is modified,
047     * the result of the <CODE>send</CODE> is undefined.
048     * <p/>
049     * <P>
050     * After sending a message, a client may retain and modify it without affecting
051     * the message that has been sent. The same message object may be sent multiple
052     * times.
053     * <p/>
054     * <P>
055     * The following message headers are set as part of sending a message: <code>JMSDestination</code>,
056     * <code>JMSDeliveryMode</code>,<code>JMSExpiration</code>,<code>JMSPriority</code>,
057     * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>. When the
058     * message is sent, the values of these headers are ignored. After the
059     * completion of the <CODE>send</CODE>, the headers hold the values
060     * specified by the method sending the message. It is possible for the <code>send</code>
061     * method not to set <code>JMSMessageID</code> and <code>JMSTimeStamp</code>
062     * if the setting of these headers is explicitly disabled by the <code>MessageProducer.setDisableMessageID</code>
063     * or <code>MessageProducer.setDisableMessageTimestamp</code> method.
064     * <p/>
065     * <P>
066     * Creating a <CODE>MessageProducer</CODE> provides the same features as
067     * creating a <CODE>QueueSender</CODE>. A <CODE>MessageProducer</CODE>
068     * object is recommended when creating new code. The <CODE>QueueSender</CODE>
069     * is provided to support existing code.
070     *
071     * @see javax.jms.MessageProducer
072     * @see javax.jms.Session#createProducer(Destination)
073     * @see javax.jms.QueueSession#createSender(Queue)
074     */
075    
076    public class ActiveMQQueueSender extends ActiveMQMessageProducer implements
077            QueueSender {
078    
079        protected ActiveMQQueueSender(ActiveMQSession session,
080                                      ActiveMQDestination destination) throws JMSException {
081            super(session, destination);
082        }
083    
084        /**
085         * Gets the queue associated with this <CODE>QueueSender</CODE>.
086         *
087         * @return this sender's queue
088         * @throws JMSException if the JMS provider fails to get the queue for this
089         *                      <CODE>QueueSender</CODE> due to some internal error.
090         */
091    
092        public Queue getQueue() throws JMSException {
093            return (Queue) super.getDestination();
094        }
095    
096        /**
097         * Sends a message to a queue for an unidentified message producer. Uses
098         * the <CODE>QueueSender</CODE>'s default delivery mode, priority, and
099         * time to live.
100         * <p/>
101         * <P>
102         * Typically, a message producer is assigned a queue at creation time;
103         * however, the JMS API also supports unidentified message producers, which
104         * require that the queue be supplied every time a message is sent.
105         *
106         * @param queue   the queue to send this message to
107         * @param message the message to send
108         * @throws JMSException                if the JMS provider fails to send the message due to some
109         *                                     internal error.
110         * @throws MessageFormatException      if an invalid message is specified.
111         * @throws InvalidDestinationException if a client uses this method with an invalid queue.
112         * @see javax.jms.MessageProducer#getDeliveryMode()
113         * @see javax.jms.MessageProducer#getTimeToLive()
114         * @see javax.jms.MessageProducer#getPriority()
115         */
116    
117        public void send(Queue queue, Message message) throws JMSException {
118            super.send(queue, message);
119        }
120    
121        /**
122         * Sends a message to a queue for an unidentified message producer,
123         * specifying delivery mode, priority and time to live.
124         * <p/>
125         * <P>
126         * Typically, a message producer is assigned a queue at creation time;
127         * however, the JMS API also supports unidentified message producers, which
128         * require that the queue be supplied every time a message is sent.
129         *
130         * @param queue        the queue to send this message to
131         * @param message      the message to send
132         * @param deliveryMode the delivery mode to use
133         * @param priority     the priority for this message
134         * @param timeToLive   the message's lifetime (in milliseconds)
135         * @throws JMSException                if the JMS provider fails to send the message due to some
136         *                                     internal error.
137         * @throws MessageFormatException      if an invalid message is specified.
138         * @throws InvalidDestinationException if a client uses this method with an invalid queue.
139         */
140    
141        public void send(Queue queue, Message message, int deliveryMode,
142                         int priority, long timeToLive) throws JMSException {
143            super.send(queue, message, deliveryMode, priority, timeToLive);
144        }
145    }