MessageProducer


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