1 /*
2 * JBoss, Home of Professional Open Source
3 * Copyright 2005, JBoss Inc., and individual contributors as indicated
4 * by the @authors tag. See the copyright.txt in the distribution for a
5 * full listing of individual contributors.
6 *
7 * This is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU Lesser General Public License as
9 * published by the Free Software Foundation; either version 2.1 of
10 * the License, or (at your option) any later version.
11 *
12 * This software is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this software; if not, write to the Free
19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21 */
22 package javax.jms;
23
24 /** A client uses a <CODE>QueueSender</CODE> object to send messages to a queue.
25 *
26 * <P>Normally, the <CODE>Queue</CODE> is specified when a
27 * <CODE>QueueSender</CODE> is created. In this case, an attempt to use
28 * the <CODE>send</CODE> methods for an unidentified
29 * <CODE>QueueSender</CODE> will throw a
30 * <CODE>java.lang.UnsupportedOperationException</CODE>.
31 *
32 * <P>If the <CODE>QueueSender</CODE> is created with an unidentified
33 * <CODE>Queue</CODE>, an attempt to use the <CODE>send</CODE> methods that
34 * assume that the <CODE>Queue</CODE> has been identified will throw a
35 * <CODE>java.lang.UnsupportedOperationException</CODE>.
36 *
37 * <P>During the execution of its <CODE>send</CODE> method, a message
38 * must not be changed by other threads within the client.
39 * If the message is modified, the result of the <CODE>send</CODE> is
40 * undefined.
41 *
42 * <P>After sending a message, a client may retain and modify it
43 * without affecting the message that has been sent. The same message
44 * object may be sent multiple times.
45 *
46 * <P>The following message headers are set as part of sending a
47 * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
48 * <code>JMSExpiration</code>, <code>JMSPriority</code>,
49 * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
50 * When the message is sent, the values of these headers are ignored.
51 * After the completion of the <CODE>send</CODE>, the headers hold the values
52 * specified by the method sending the message. It is possible for the
53 * <code>send</code> method not to set <code>JMSMessageID</code> and
54 * <code>JMSTimeStamp</code> if the
55 * setting of these headers is explicitly disabled by the
56 * <code>MessageProducer.setDisableMessageID</code> or
57 * <code>MessageProducer.setDisableMessageTimestamp</code> method.
58 *
59 * <P>Creating a <CODE>MessageProducer</CODE> provides the same features as
60 * creating a <CODE>QueueSender</CODE>. A <CODE>MessageProducer</CODE> object is
61 * recommended when creating new code. The <CODE>QueueSender</CODE> is
62 * provided to support existing code.
63 *
64 * @see javax.jms.MessageProducer
65 * @see javax.jms.Session#createProducer(Destination)
66 * @see javax.jms.QueueSession#createSender(Queue)
67 */
68
69 public interface QueueSender extends MessageProducer
70 {
71
72 /** Gets the queue associated with this <CODE>QueueSender</CODE>.
73 *
74 * @return this sender's queue
75 *
76 * @exception JMSException if the JMS provider fails to get the queue for
77 * this <CODE>QueueSender</CODE>
78 * due to some internal error.
79 */
80
81 Queue getQueue() throws JMSException;
82
83 /** Sends a message to the queue. Uses the <CODE>QueueSender</CODE>'s
84 * default delivery mode, priority, and time to live.
85 *
86 * @param message the message to send
87 *
88 * @exception JMSException if the JMS provider fails to send the message
89 * due to some internal error.
90 * @exception MessageFormatException if an invalid message is specified.
91 * @exception InvalidDestinationException if a client uses
92 * this method with a <CODE>QueueSender</CODE> with
93 * an invalid queue.
94 * @exception java.lang.UnsupportedOperationException if a client uses this
95 * method with a <CODE>QueueSender</CODE> that did
96 * not specify a queue at creation time.
97 *
98 * @see javax.jms.MessageProducer#getDeliveryMode()
99 * @see javax.jms.MessageProducer#getTimeToLive()
100 * @see javax.jms.MessageProducer#getPriority()
101 */
102
103 void send(Message message) throws JMSException;
104
105 /** Sends a message to the queue, specifying delivery mode, priority, and
106 * time to live.
107 *
108 * @param message the message to send
109 * @param deliveryMode the delivery mode to use
110 * @param priority the priority for this message
111 * @param timeToLive the message's lifetime (in milliseconds)
112 *
113 * @exception JMSException if the JMS provider fails to send the message
114 * due to some internal error.
115 * @exception MessageFormatException if an invalid message is specified.
116 * @exception InvalidDestinationException if a client uses
117 * this method with a <CODE>QueueSender</CODE> with
118 * an invalid queue.
119 * @exception java.lang.UnsupportedOperationException if a client uses this
120 * method with a <CODE>QueueSender</CODE> that did
121 * not specify a queue at creation time.
122 */
123
124 void send(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
125
126 /** Sends a message to a queue for an unidentified message producer.
127 * Uses the <CODE>QueueSender</CODE>'s default delivery mode, priority,
128 * and time to live.
129 *
130 * <P>Typically, a message producer is assigned a queue at creation
131 * time; however, the JMS API also supports unidentified message producers,
132 * which require that the queue be supplied every time a message is
133 * sent.
134 *
135 * @param queue the queue to send this message to
136 * @param message the message to send
137 *
138 * @exception JMSException if the JMS provider fails to send the message
139 * due to some internal error.
140 * @exception MessageFormatException if an invalid message is specified.
141 * @exception InvalidDestinationException if a client uses
142 * this method with an invalid queue.
143 *
144 * @see javax.jms.MessageProducer#getDeliveryMode()
145 * @see javax.jms.MessageProducer#getTimeToLive()
146 * @see javax.jms.MessageProducer#getPriority()
147 */
148
149 void send(Queue queue, Message message) throws JMSException;
150
151 /** Sends a message to a queue for an unidentified message producer,
152 * specifying delivery mode, priority and time to live.
153 *
154 * <P>Typically, a message producer is assigned a queue at creation
155 * time; however, the JMS API also supports unidentified message producers,
156 * which require that the queue be supplied every time a message is
157 * sent.
158 *
159 * @param queue the queue to send this message to
160 * @param message the message to send
161 * @param deliveryMode the delivery mode to use
162 * @param priority the priority for this message
163 * @param timeToLive the message's lifetime (in milliseconds)
164 *
165 * @exception JMSException if the JMS provider fails to send the message
166 * due to some internal error.
167 * @exception MessageFormatException if an invalid message is specified.
168 * @exception InvalidDestinationException if a client uses
169 * this method with an invalid queue.
170 */
171
172 void send(Queue queue, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
173 }