1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
|
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the license at
* https://glassfish.dev.java.net/public/CDDLv1.0.html or
* glassfish/bootstrap/legal/CDDLv1.0.txt.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at glassfish/bootstrap/legal/CDDLv1.0.txt.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* you own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
*/
package javax.jms;
/** A client uses a <CODE>MessageProducer</CODE> object to send messages to a
* destination. A <CODE>MessageProducer</CODE> object is created by passing a
* <CODE>Destination</CODE> object to a message-producer creation method
* supplied by a session.
*
* <P><CODE>MessageProducer</CODE> is the parent interface for all message
* producers.
*
* <P>A client also has the option of creating a message producer without
* supplying a destination. In this case, a destination must be provided with
* every send operation. A typical use for this kind of message producer is
* to send replies to requests using the request's <CODE>JMSReplyTo</CODE>
* destination.
*
* <P>A client can specify a default delivery mode, priority, and time to live
* for messages sent by a message producer. It can also specify the delivery
* mode, priority, and time to live for an individual message.
*
* <P>A client can specify a time-to-live value in milliseconds for each
* message it sends. This value defines a message expiration time that
* is the sum of the message's time-to-live and the GMT when it is sent (for
* transacted sends, this is the time the client sends the message, not
* the time the transaction is committed).
*
* <P>A JMS provider should do its best to expire messages accurately;
* however, the JMS API does not define the accuracy provided.
*
* @version 1.1 - February 2, 2002
* @author Mark Hapner
* @author Rich Burridge
* @author Kate Stout
*
* @see javax.jms.TopicPublisher
* @see javax.jms.QueueSender
* @see javax.jms.Session#createProducer
*/
public interface MessageProducer {
/** Sets whether message IDs are disabled.
*
* <P>Since message IDs take some effort to create and increase a
* message's size, some JMS providers may be able to optimize message
* overhead if they are given a hint that the message ID is not used by
* an application. By calling the <CODE>setDisableMessageID</CODE>
* method on this message producer, a JMS client enables this potential
* optimization for all messages sent by this message producer. If the JMS
* provider accepts this hint,
* these messages must have the message ID set to null; if the provider
* ignores the hint, the message ID must be set to its normal unique value.
*
* <P>Message IDs are enabled by default.
*
* @param value indicates if message IDs are disabled
*
* @exception JMSException if the JMS provider fails to set message ID to
* disabled due to some internal error.
*/
void
setDisableMessageID(boolean value) throws JMSException;
/** Gets an indication of whether message IDs are disabled.
*
* @return an indication of whether message IDs are disabled
*
* @exception JMSException if the JMS provider fails to determine if
* message IDs are disabled due to some internal
* error.
*/
boolean
getDisableMessageID() throws JMSException;
/** Sets whether message timestamps are disabled.
*
* <P>Since timestamps take some effort to create and increase a
* message's size, some JMS providers may be able to optimize message
* overhead if they are given a hint that the timestamp is not used by an
* application. By calling the <CODE>setDisableMessageTimestamp</CODE>
* method on this message producer, a JMS client enables this potential
* optimization for all messages sent by this message producer. If the
* JMS provider accepts this hint,
* these messages must have the timestamp set to zero; if the provider
* ignores the hint, the timestamp must be set to its normal value.
*
* <P>Message timestamps are enabled by default.
*
* @param value indicates if message timestamps are disabled
*
* @exception JMSException if the JMS provider fails to set timestamps to
* disabled due to some internal error.
*/
void
setDisableMessageTimestamp(boolean value) throws JMSException;
/** Gets an indication of whether message timestamps are disabled.
*
* @return an indication of whether message timestamps are disabled
*
* @exception JMSException if the JMS provider fails to determine if
* timestamps are disabled due to some internal
* error.
*/
boolean
getDisableMessageTimestamp() throws JMSException;
/** Sets the producer's default delivery mode.
*
* <P>Delivery mode is set to <CODE>PERSISTENT</CODE> by default.
*
* @param deliveryMode the message delivery mode for this message
* producer; legal values are <code>DeliveryMode.NON_PERSISTENT</code>
* and <code>DeliveryMode.PERSISTENT</code>
*
* @exception JMSException if the JMS provider fails to set the delivery
* mode due to some internal error.
*
* @see javax.jms.MessageProducer#getDeliveryMode
* @see javax.jms.DeliveryMode#NON_PERSISTENT
* @see javax.jms.DeliveryMode#PERSISTENT
* @see javax.jms.Message#DEFAULT_DELIVERY_MODE
*/
void
setDeliveryMode(int deliveryMode) throws JMSException;
/** Gets the producer's default delivery mode.
*
* @return the message delivery mode for this message producer
*
* @exception JMSException if the JMS provider fails to get the delivery
* mode due to some internal error.
*
* @see javax.jms.MessageProducer#setDeliveryMode
*/
int
getDeliveryMode() throws JMSException;
/** Sets the producer's default priority.
*
* <P>The JMS API defines ten levels of priority value, with 0 as the
* lowest priority and 9 as the highest. Clients should consider priorities
* 0-4 as gradations of normal priority and priorities 5-9 as gradations
* of expedited priority. Priority is set to 4 by default.
*
* @param defaultPriority the message priority for this message producer;
* must be a value between 0 and 9
*
*
* @exception JMSException if the JMS provider fails to set the priority
* due to some internal error.
*
* @see javax.jms.MessageProducer#getPriority
* @see javax.jms.Message#DEFAULT_PRIORITY
*/
void
setPriority(int defaultPriority) throws JMSException;
/** Gets the producer's default priority.
*
* @return the message priority for this message producer
*
* @exception JMSException if the JMS provider fails to get the priority
* due to some internal error.
*
* @see javax.jms.MessageProducer#setPriority
*/
int
getPriority() throws JMSException;
/** Sets the default length of time in milliseconds from its dispatch time
* that a produced message should be retained by the message system.
*
* <P>Time to live is set to zero by default.
*
* @param timeToLive the message time to live in milliseconds; zero is
* unlimited
*
* @exception JMSException if the JMS provider fails to set the time to
* live due to some internal error.
*
* @see javax.jms.MessageProducer#getTimeToLive
* @see javax.jms.Message#DEFAULT_TIME_TO_LIVE
*/
void
setTimeToLive(long timeToLive) throws JMSException;
/** Gets the default length of time in milliseconds from its dispatch time
* that a produced message should be retained by the message system.
*
* @return the message time to live in milliseconds; zero is unlimited
*
* @exception JMSException if the JMS provider fails to get the time to
* live due to some internal error.
*
* @see javax.jms.MessageProducer#setTimeToLive
*/
long
getTimeToLive() throws JMSException;
/** Gets the destination associated with this <CODE>MessageProducer</CODE>.
*
* @return this producer's <CODE>Destination/<CODE>
*
* @exception JMSException if the JMS provider fails to get the destination for
* this <CODE>MessageProducer</CODE>
* due to some internal error.
*@since 1.1
*/
Destination
getDestination() throws JMSException;
/** Closes the message producer.
*
* <P>Since a provider may allocate some resources on behalf of a
* <CODE>MessageProducer</CODE> outside the Java virtual machine, clients
* should close them when they
* are not needed. Relying on garbage collection to eventually reclaim
* these resources may not be timely enough.
*
* @exception JMSException if the JMS provider fails to close the producer
* due to some internal error.
*/
void
close() throws JMSException;
/** Sends a message using the <CODE>MessageProducer</CODE>'s
* default delivery mode, priority, and time to live.
*
* @param message the message to send
*
* @exception JMSException if the JMS provider fails to send the message
* due to some internal error.
* @exception MessageFormatException if an invalid message is specified.
* @exception InvalidDestinationException if a client uses
* this method with a <CODE>MessageProducer</CODE> with
* an invalid destination.
* @exception java.lang.UnsupportedOperationException if a client uses this
* method with a <CODE>MessageProducer</CODE> that did
* not specify a destination at creation time.
*
* @see javax.jms.Session#createProducer
* @see javax.jms.MessageProducer
*
* @since 1.1
*/
void
send(Message message) throws JMSException;
/** Sends a message to the destination, specifying delivery mode, priority, and
* time to live.
*
* @param message the message to send
* @param deliveryMode the delivery mode to use
* @param priority the priority for this message
* @param timeToLive the message's lifetime (in milliseconds)
*
* @exception JMSException if the JMS provider fails to send the message
* due to some internal error.
* @exception MessageFormatException if an invalid message is specified.
* @exception InvalidDestinationException if a client uses
* this method with a <CODE>MessageProducer</CODE> with
* an invalid destination.
* @exception java.lang.UnsupportedOperationException if a client uses this
* method with a <CODE>MessageProducer</CODE> that did
* not specify a destination at creation time.
*
* @see javax.jms.Session#createProducer
* @since 1.1
*/
void
send(Message message,
int deliveryMode,
int priority,
long timeToLive) throws JMSException;
/**Sends a message to a destination for an unidentified message producer.
* Uses the <CODE>MessageProducer</CODE>'s default delivery mode, priority,
* and time to live.
*
* <P>Typically, a message producer is assigned a destination at creation
* time; however, the JMS API also supports unidentified message producers,
* which require that the destination be supplied every time a message is
* sent.
*
* @param destination the destination to send this message to
* @param message the message to send
*
* @exception JMSException if the JMS provider fails to send the message
* due to some internal error.
* @exception MessageFormatException if an invalid message is specified.
* @exception InvalidDestinationException if a client uses
* this method with an invalid destination.
* @exception java.lang.UnsupportedOperationException if a client uses this
* method with a <CODE>MessageProducer</CODE> that
* specified a destination at creation time.
*
* @see javax.jms.Session#createProducer
* @see javax.jms.MessageProducer
* @since 1.1
*/
void
send(Destination destination, Message message) throws JMSException;
/** Sends a message to a destination for an unidentified message producer,
* specifying delivery mode, priority and time to live.
*
* <P>Typically, a message producer is assigned a destination at creation
* time; however, the JMS API also supports unidentified message producers,
* which require that the destination be supplied every time a message is
* sent.
*
* @param destination the destination to send this message to
* @param message the message to send
* @param deliveryMode the delivery mode to use
* @param priority the priority for this message
* @param timeToLive the message's lifetime (in milliseconds)
*
* @exception JMSException if the JMS provider fails to send the message
* due to some internal error.
* @exception MessageFormatException if an invalid message is specified.
* @exception InvalidDestinationException if a client uses
* this method with an invalid destination.
*
* @see javax.jms.Session#createProducer
* @since 1.1
*/
void
send(Destination destination,
Message message,
int deliveryMode,
int priority,
long timeToLive) throws JMSException;
}
|
