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 }