001: /*
002: * @(#)QueueSender.java 1.29 02/04/09
003: *
004: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * SUN PROPRIETARY/CONFIDENTIAL.
007: * This software is the proprietary information of Sun Microsystems, Inc.
008: * Use is subject to license terms.
009: *
010: */
011:
012: package javax.jms;
013:
014: /** A client uses a <CODE>QueueSender</CODE> object to send messages to a queue.
015: *
016: * <P>Normally, the <CODE>Queue</CODE> is specified when a
017: * <CODE>QueueSender</CODE> is created. In this case, an attempt to use
018: * the <CODE>send</CODE> methods for an unidentified
019: * <CODE>QueueSender</CODE> will throw a
020: * <CODE>java.lang.UnsupportedOperationException</CODE>.
021: *
022: * <P>If the <CODE>QueueSender</CODE> is created with an unidentified
023: * <CODE>Queue</CODE>, an attempt to use the <CODE>send</CODE> methods that
024: * assume that the <CODE>Queue</CODE> has been identified will throw a
025: * <CODE>java.lang.UnsupportedOperationException</CODE>.
026: *
027: * <P>During the execution of its <CODE>send</CODE> method, a message
028: * must not be changed by other threads within the client.
029: * If the message is modified, the result of the <CODE>send</CODE> is
030: * undefined.
031: *
032: * <P>After sending a message, a client may retain and modify it
033: * without affecting the message that has been sent. The same message
034: * object may be sent multiple times.
035: *
036: * <P>The following message headers are set as part of sending a
037: * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
038: * <code>JMSExpiration</code>, <code>JMSPriority</code>,
039: * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
040: * When the message is sent, the values of these headers are ignored.
041: * After the completion of the <CODE>send</CODE>, the headers hold the values
042: * specified by the method sending the message. It is possible for the
043: * <code>send</code> method not to set <code>JMSMessageID</code> and
044: * <code>JMSTimeStamp</code> if the
045: * setting of these headers is explicitly disabled by the
046: * <code>MessageProducer.setDisableMessageID</code> or
047: * <code>MessageProducer.setDisableMessageTimestamp</code> method.
048: *
049: * <P>Creating a <CODE>MessageProducer</CODE> provides the same features as
050: * creating a <CODE>QueueSender</CODE>. A <CODE>MessageProducer</CODE> object is
051: * recommended when creating new code. The <CODE>QueueSender</CODE> is
052: * provided to support existing code.
053: *
054: *
055: * @version 1.1 - February 2, 2002
056: * @author Mark Hapner
057: * @author Rich Burridge
058: * @author Kate Stout
059: *
060: * @see javax.jms.MessageProducer
061: * @see javax.jms.Session#createProducer(Destination)
062: * @see javax.jms.QueueSession#createSender(Queue)
063: */
064:
065: public interface QueueSender extends MessageProducer {
066:
067: /** Gets the queue associated with this <CODE>QueueSender</CODE>.
068: *
069: * @return this sender's queue
070: *
071: * @exception JMSException if the JMS provider fails to get the queue for
072: * this <CODE>QueueSender</CODE>
073: * due to some internal error.
074: */
075:
076: Queue getQueue() throws JMSException;
077:
078: /** Sends a message to the queue. Uses the <CODE>QueueSender</CODE>'s
079: * default delivery mode, priority, and time to live.
080: *
081: * @param message the message to send
082: *
083: * @exception JMSException if the JMS provider fails to send the message
084: * due to some internal error.
085: * @exception MessageFormatException if an invalid message is specified.
086: * @exception InvalidDestinationException if a client uses
087: * this method with a <CODE>QueueSender</CODE> with
088: * an invalid queue.
089: * @exception java.lang.UnsupportedOperationException if a client uses this
090: * method with a <CODE>QueueSender</CODE> that did
091: * not specify a queue at creation time.
092: *
093: * @see javax.jms.MessageProducer#getDeliveryMode()
094: * @see javax.jms.MessageProducer#getTimeToLive()
095: * @see javax.jms.MessageProducer#getPriority()
096: */
097:
098: void send(Message message) throws JMSException;
099:
100: /** Sends a message to the queue, specifying delivery mode, priority, and
101: * time to live.
102: *
103: * @param message the message to send
104: * @param deliveryMode the delivery mode to use
105: * @param priority the priority for this message
106: * @param timeToLive the message's lifetime (in milliseconds)
107: *
108: * @exception JMSException if the JMS provider fails to send the message
109: * due to some internal error.
110: * @exception MessageFormatException if an invalid message is specified.
111: * @exception InvalidDestinationException if a client uses
112: * this method with a <CODE>QueueSender</CODE> with
113: * an invalid queue.
114: * @exception java.lang.UnsupportedOperationException if a client uses this
115: * method with a <CODE>QueueSender</CODE> that did
116: * not specify a queue at creation time.
117: */
118:
119: void send(Message message, int deliveryMode, int priority,
120: long timeToLive) throws JMSException;
121:
122: /** Sends a message to a queue for an unidentified message producer.
123: * Uses the <CODE>QueueSender</CODE>'s default delivery mode, priority,
124: * and time to live.
125: *
126: * <P>Typically, a message producer is assigned a queue at creation
127: * time; however, the JMS API also supports unidentified message producers,
128: * which require that the queue be supplied every time a message is
129: * sent.
130: *
131: * @param queue the queue to send this message to
132: * @param message the message to send
133: *
134: * @exception JMSException if the JMS provider fails to send the message
135: * due to some internal error.
136: * @exception MessageFormatException if an invalid message is specified.
137: * @exception InvalidDestinationException if a client uses
138: * this method with an invalid queue.
139: *
140: * @see javax.jms.MessageProducer#getDeliveryMode()
141: * @see javax.jms.MessageProducer#getTimeToLive()
142: * @see javax.jms.MessageProducer#getPriority()
143: */
144:
145: void send(Queue queue, Message message) throws JMSException;
146:
147: /** Sends a message to a queue for an unidentified message producer,
148: * specifying delivery mode, priority and time to live.
149: *
150: * <P>Typically, a message producer is assigned a queue at creation
151: * time; however, the JMS API also supports unidentified message producers,
152: * which require that the queue be supplied every time a message is
153: * sent.
154: *
155: * @param queue the queue to send this message to
156: * @param message the message to send
157: * @param deliveryMode the delivery mode to use
158: * @param priority the priority for this message
159: * @param timeToLive the message's lifetime (in milliseconds)
160: *
161: * @exception JMSException if the JMS provider fails to send the message
162: * due to some internal error.
163: * @exception MessageFormatException if an invalid message is specified.
164: * @exception InvalidDestinationException if a client uses
165: * this method with an invalid queue.
166: */
167:
168: void send(Queue queue, Message message, int deliveryMode,
169: int priority, long timeToLive) throws JMSException;
170: }
|