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