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>MessageProducer</CODE> object to send messages to a
025: * destination. A <CODE>MessageProducer</CODE> object is created by passing a
026: * <CODE>Destination</CODE> object to a message-producer creation method
027: * supplied by a session.
028: *
029: * <P><CODE>MessageProducer</CODE> is the parent interface for all message
030: * producers.
031: *
032: * <P>A client also has the option of creating a message producer without
033: * supplying a destination. In this case, a destination must be provided with
034: * every send operation. A typical use for this kind of message producer is
035: * to send replies to requests using the request's <CODE>JMSReplyTo</CODE>
036: * destination.
037: *
038: * <P>A client can specify a default delivery mode, priority, and time to live
039: * for messages sent by a message producer. It can also specify the delivery
040: * mode, priority, and time to live for an individual message.
041: *
042: * <P>A client can specify a time-to-live value in milliseconds for each
043: * message it sends. This value defines a message expiration time that
044: * is the sum of the message's time-to-live and the GMT when it is sent (for
045: * transacted sends, this is the time the client sends the message, not
046: * the time the transaction is committed).
047: *
048: * <P>A JMS provider should do its best to expire messages accurately;
049: * however, the JMS API does not define the accuracy provided.
050: *
051: * @see javax.jms.TopicPublisher
052: * @see javax.jms.QueueSender
053: * @see javax.jms.Session#createProducer
054: */
055:
056: public interface MessageProducer {
057:
058: /** Sets whether message IDs are disabled.
059: *
060: * <P>Since message IDs take some effort to create and increase a
061: * message's size, some JMS providers may be able to optimize message
062: * overhead if they are given a hint that the message ID is not used by
063: * an application. By calling the <CODE>setDisableMessageID</CODE>
064: * method on this message producer, a JMS client enables this potential
065: * optimization for all messages sent by this message producer. If the JMS
066: * provider accepts this hint,
067: * these messages must have the message ID set to null; if the provider
068: * ignores the hint, the message ID must be set to its normal unique value.
069: *
070: * <P>Message IDs are enabled by default.
071: *
072: * @param value indicates if message IDs are disabled
073: *
074: * @exception JMSException if the JMS provider fails to set message ID to
075: * disabled due to some internal error.
076: */
077: public void setDisableMessageID(boolean value) throws JMSException;
078:
079: /** Gets an indication of whether message IDs are disabled.
080: *
081: * @return an indication of whether message IDs are disabled
082: *
083: * @exception JMSException if the JMS provider fails to determine if
084: * message IDs are disabled due to some internal
085: * error.
086: */
087: public boolean getDisableMessageID() throws JMSException;
088:
089: /** Sets whether message timestamps are disabled.
090: *
091: * <P>Since timestamps take some effort to create and increase a
092: * message's size, some JMS providers may be able to optimize message
093: * overhead if they are given a hint that the timestamp is not used by an
094: * application. By calling the <CODE>setDisableMessageTimestamp</CODE>
095: * method on this message producer, a JMS client enables this potential
096: * optimization for all messages sent by this message producer. If the
097: * JMS provider accepts this hint,
098: * these messages must have the timestamp set to zero; if the provider
099: * ignores the hint, the timestamp must be set to its normal value.
100: *
101: * <P>Message timestamps are enabled by default.
102: *
103: * @param value indicates if message timestamps are disabled
104: *
105: * @exception JMSException if the JMS provider fails to set timestamps to
106: * disabled due to some internal error.
107: */
108: public void setDisableMessageTimestamp(boolean value)
109: throws JMSException;
110:
111: /** Gets an indication of whether message timestamps are disabled.
112: *
113: * @return an indication of whether message timestamps are disabled
114: *
115: * @exception JMSException if the JMS provider fails to determine if
116: * timestamps are disabled due to some internal
117: * error.
118: */
119: public boolean getDisableMessageTimestamp() throws JMSException;
120:
121: /** Sets the producer's default delivery mode.
122: *
123: * <P>Delivery mode is set to <CODE>PERSISTENT</CODE> by default.
124: *
125: * @param deliveryMode the message delivery mode for this message
126: * producer; legal values are <code>DeliveryMode.NON_PERSISTENT</code>
127: * and <code>DeliveryMode.PERSISTENT</code>
128: *
129: * @exception JMSException if the JMS provider fails to set the delivery
130: * mode due to some internal error.
131: *
132: * @see javax.jms.MessageProducer#getDeliveryMode
133: * @see javax.jms.DeliveryMode#NON_PERSISTENT
134: * @see javax.jms.DeliveryMode#PERSISTENT
135: * @see javax.jms.Message#DEFAULT_DELIVERY_MODE
136: */
137: public void setDeliveryMode(int deliveryMode) throws JMSException;
138:
139: /** Gets the producer's default delivery mode.
140: *
141: * @return the message delivery mode for this message producer
142: *
143: * @exception JMSException if the JMS provider fails to get the delivery
144: * mode due to some internal error.
145: *
146: * @see javax.jms.MessageProducer#setDeliveryMode
147: */
148: public int getDeliveryMode() throws JMSException;
149:
150: /** Sets the producer's default priority.
151: *
152: * <P>The JMS API defines ten levels of priority value, with 0 as the
153: * lowest priority and 9 as the highest. Clients should consider priorities
154: * 0-4 as gradations of normal priority and priorities 5-9 as gradations
155: * of expedited priority. Priority is set to 4 by default.
156: *
157: * @param defaultPriority the message priority for this message producer;
158: * must be a value between 0 and 9
159: *
160: *
161: * @exception JMSException if the JMS provider fails to set the priority
162: * due to some internal error.
163: *
164: * @see javax.jms.MessageProducer#getPriority
165: * @see javax.jms.Message#DEFAULT_PRIORITY
166: */
167: public void setPriority(int defaultPriority) throws JMSException;
168:
169: /** Gets the producer's default priority.
170: *
171: * @return the message priority for this message producer
172: *
173: * @exception JMSException if the JMS provider fails to get the priority
174: * due to some internal error.
175: *
176: * @see javax.jms.MessageProducer#setPriority
177: */
178: public int getPriority() throws JMSException;
179:
180: /** Sets the default length of time in milliseconds from its dispatch time
181: * that a produced message should be retained by the message system.
182: *
183: * <P>Time to live is set to zero by default.
184: *
185: * @param timeToLive the message time to live in milliseconds; zero is
186: * unlimited
187: *
188: * @exception JMSException if the JMS provider fails to set the time to
189: * live due to some internal error.
190: *
191: * @see javax.jms.MessageProducer#getTimeToLive
192: * @see javax.jms.Message#DEFAULT_TIME_TO_LIVE
193: */
194: public void setTimeToLive(long timeToLive) throws JMSException;
195:
196: /** Gets the default length of time in milliseconds from its dispatch time
197: * that a produced message should be retained by the message system.
198: *
199: * @return the message time to live in milliseconds; zero is unlimited
200: *
201: * @exception JMSException if the JMS provider fails to get the time to
202: * live due to some internal error.
203: *
204: * @see javax.jms.MessageProducer#setTimeToLive
205: */
206: public long getTimeToLive() throws JMSException;
207:
208: /** Gets the destination associated with this <CODE>MessageProducer</CODE>.
209: *
210: * @return this producer's <CODE>Destination/<CODE>
211: *
212: * @exception JMSException if the JMS provider fails to get the destination for
213: * this <CODE>MessageProducer</CODE>
214: * due to some internal error.
215: *@since 1.1
216: */
217: public Destination getDestination() throws JMSException;
218:
219: /** Closes the message producer.
220: *
221: * <P>Since a provider may allocate some resources on behalf of a
222: * <CODE>MessageProducer</CODE> outside the Java virtual machine, clients
223: * should close them when they
224: * are not needed. Relying on garbage collection to eventually reclaim
225: * these resources may not be timely enough.
226: *
227: * @exception JMSException if the JMS provider fails to close the producer
228: * due to some internal error.
229: */
230: public void close() throws JMSException;
231:
232: /** Sends a message using the <CODE>MessageProducer</CODE>'s
233: * default delivery mode, priority, and time to live.
234: *
235: * @param message the message to send
236: *
237: * @exception JMSException if the JMS provider fails to send the message
238: * due to some internal error.
239: * @exception MessageFormatException if an invalid message is specified.
240: * @exception InvalidDestinationException if a client uses
241: * this method with a <CODE>MessageProducer</CODE> with
242: * an invalid destination.
243: * @exception java.lang.UnsupportedOperationException if a client uses this
244: * method with a <CODE>MessageProducer</CODE> that did
245: * not specify a destination at creation time.
246: *
247: * @see javax.jms.Session#createProducer
248: * @see javax.jms.MessageProducer
249: *
250: * @since 1.1
251: */
252: public void send(Message message) throws JMSException;
253:
254: /** Sends a message to the destination, specifying delivery mode, priority, and
255: * time to live.
256: *
257: * @param message the message to send
258: * @param deliveryMode the delivery mode to use
259: * @param priority the priority for this message
260: * @param timeToLive the message's lifetime (in milliseconds)
261: *
262: * @exception JMSException if the JMS provider fails to send the message
263: * due to some internal error.
264: * @exception MessageFormatException if an invalid message is specified.
265: * @exception InvalidDestinationException if a client uses
266: * this method with a <CODE>MessageProducer</CODE> with
267: * an invalid destination.
268: * @exception java.lang.UnsupportedOperationException if a client uses this
269: * method with a <CODE>MessageProducer</CODE> that did
270: * not specify a destination at creation time.
271: *
272: * @see javax.jms.Session#createProducer
273: * @since 1.1
274: */
275: public void send(Message message, int deliveryMode, int priority,
276: long timeToLive) throws JMSException;
277:
278: /**Sends a message to a destination for an unidentified message producer.
279: * Uses the <CODE>MessageProducer</CODE>'s default delivery mode, priority,
280: * and time to live.
281: *
282: * <P>Typically, a message producer is assigned a destination at creation
283: * time; however, the JMS API also supports unidentified message producers,
284: * which require that the destination be supplied every time a message is
285: * sent.
286: *
287: * @param destination the destination to send this message to
288: * @param message the message to send
289: *
290: * @exception JMSException if the JMS provider fails to send the message
291: * due to some internal error.
292: * @exception MessageFormatException if an invalid message is specified.
293: * @exception InvalidDestinationException if a client uses
294: * this method with an invalid destination.
295: * @exception java.lang.UnsupportedOperationException if a client uses this
296: * method with a <CODE>MessageProducer</CODE> that
297: * specified a destination at creation time.
298: *
299: * @see javax.jms.Session#createProducer
300: * @see javax.jms.MessageProducer
301: * @since 1.1
302: */
303: public void send(Destination destination, Message message)
304: throws JMSException;
305:
306: /** Sends a message to a destination for an unidentified message producer,
307: * specifying delivery mode, priority and time to live.
308: *
309: * <P>Typically, a message producer is assigned a destination at creation
310: * time; however, the JMS API also supports unidentified message producers,
311: * which require that the destination be supplied every time a message is
312: * sent.
313: *
314: * @param destination the destination to send this message to
315: * @param message the message to send
316: * @param deliveryMode the delivery mode to use
317: * @param priority the priority for this message
318: * @param timeToLive the message's lifetime (in milliseconds)
319: *
320: * @exception JMSException if the JMS provider fails to send the message
321: * due to some internal error.
322: * @exception MessageFormatException if an invalid message is specified.
323: * @exception InvalidDestinationException if a client uses
324: * this method with an invalid destination.
325: *
326: * @see javax.jms.Session#createProducer
327: * @since 1.1
328: */
329: public void send(Destination destination, Message message,
330: int deliveryMode, int priority, long timeToLive)
331: throws JMSException;
332: }
|