001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.jms;
023:
024: /** A client uses a <CODE>QueueSender</CODE> object to send messages to a queue.
025: *
026: * <P>Normally, the <CODE>Queue</CODE> is specified when a
027: * <CODE>QueueSender</CODE> is created. In this case, an attempt to use
028: * the <CODE>send</CODE> methods for an unidentified
029: * <CODE>QueueSender</CODE> will throw a
030: * <CODE>java.lang.UnsupportedOperationException</CODE>.
031: *
032: * <P>If the <CODE>QueueSender</CODE> is created with an unidentified
033: * <CODE>Queue</CODE>, an attempt to use the <CODE>send</CODE> methods that
034: * assume that the <CODE>Queue</CODE> has been identified will throw a
035: * <CODE>java.lang.UnsupportedOperationException</CODE>.
036: *
037: * <P>During the execution of its <CODE>send</CODE> method, a message
038: * must not be changed by other threads within the client.
039: * If the message is modified, the result of the <CODE>send</CODE> is
040: * undefined.
041: *
042: * <P>After sending a message, a client may retain and modify it
043: * without affecting the message that has been sent. The same message
044: * object may be sent multiple times.
045: *
046: * <P>The following message headers are set as part of sending a
047: * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
048: * <code>JMSExpiration</code>, <code>JMSPriority</code>,
049: * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
050: * When the message is sent, the values of these headers are ignored.
051: * After the completion of the <CODE>send</CODE>, the headers hold the values
052: * specified by the method sending the message. It is possible for the
053: * <code>send</code> method not to set <code>JMSMessageID</code> and
054: * <code>JMSTimeStamp</code> if the
055: * setting of these headers is explicitly disabled by the
056: * <code>MessageProducer.setDisableMessageID</code> or
057: * <code>MessageProducer.setDisableMessageTimestamp</code> method.
058: *
059: * <P>Creating a <CODE>MessageProducer</CODE> provides the same features as
060: * creating a <CODE>QueueSender</CODE>. A <CODE>MessageProducer</CODE> object is
061: * recommended when creating new code. The <CODE>QueueSender</CODE> is
062: * provided to support existing code.
063: *
064: * @see javax.jms.MessageProducer
065: * @see javax.jms.Session#createProducer(Destination)
066: * @see javax.jms.QueueSession#createSender(Queue)
067: */
068:
069: public interface QueueSender extends MessageProducer {
070:
071: /** Gets the queue associated with this <CODE>QueueSender</CODE>.
072: *
073: * @return this sender's queue
074: *
075: * @exception JMSException if the JMS provider fails to get the queue for
076: * this <CODE>QueueSender</CODE>
077: * due to some internal error.
078: */
079:
080: Queue getQueue() throws JMSException;
081:
082: /** Sends a message to the queue. Uses the <CODE>QueueSender</CODE>'s
083: * default delivery mode, priority, and time to live.
084: *
085: * @param message the message to send
086: *
087: * @exception JMSException if the JMS provider fails to send the message
088: * due to some internal error.
089: * @exception MessageFormatException if an invalid message is specified.
090: * @exception InvalidDestinationException if a client uses
091: * this method with a <CODE>QueueSender</CODE> with
092: * an invalid queue.
093: * @exception java.lang.UnsupportedOperationException if a client uses this
094: * method with a <CODE>QueueSender</CODE> that did
095: * not specify a queue at creation time.
096: *
097: * @see javax.jms.MessageProducer#getDeliveryMode()
098: * @see javax.jms.MessageProducer#getTimeToLive()
099: * @see javax.jms.MessageProducer#getPriority()
100: */
101:
102: void send(Message message) throws JMSException;
103:
104: /** Sends a message to the queue, specifying delivery mode, priority, and
105: * time to live.
106: *
107: * @param message the message to send
108: * @param deliveryMode the delivery mode to use
109: * @param priority the priority for this message
110: * @param timeToLive the message's lifetime (in milliseconds)
111: *
112: * @exception JMSException if the JMS provider fails to send the message
113: * due to some internal error.
114: * @exception MessageFormatException if an invalid message is specified.
115: * @exception InvalidDestinationException if a client uses
116: * this method with a <CODE>QueueSender</CODE> with
117: * an invalid queue.
118: * @exception java.lang.UnsupportedOperationException if a client uses this
119: * method with a <CODE>QueueSender</CODE> that did
120: * not specify a queue at creation time.
121: */
122:
123: void send(Message message, int deliveryMode, int priority,
124: 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,
173: int priority, long timeToLive) throws JMSException;
174: }
|