JmsOperations


1   /*
2    * Copyright 2002-2006 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.jms.core;
18  
19  import javax.jms.Destination  ;
20  import javax.jms.Message  ;
21  
22  import org.springframework.jms.JmsException;
23  
24  /**
25   * Specifies a basic set of JMS operations.
26   * 
27   * <p>Implemented by {@link JmsTemplate}. Not often used but a useful option
28   * to enhance testability, as it can easily be mocked or stubbed.
29   *
30   * <p>Provides <code>JmsTemplate's</code> <code>send(..)</code> and
31   * <code>receive(..)</code> methods that mirror various JMS API methods.
32   * See the JMS specification and javadocs for details on those methods.
33   *
34   * @author Mark Pollack
35   * @author Juergen Hoeller
36   * @since 1.1
37   * @see JmsTemplate
38   * @see javax.jms.Destination
39   * @see javax.jms.Session
40   * @see javax.jms.MessageProducer
41   * @see javax.jms.MessageConsumer
42   */
43  public interface JmsOperations {
44  
45      /**
46       * Execute the action specified by the given action object within
47       * a JMS Session.
48       * <p>When used with a 1.0.2 provider, you may need to downcast
49       * to the appropriate domain implementation, either QueueSession or
50       * TopicSession in the action objects doInJms callback method.
51       * <p>Note: The value of isPubSubDomain affects the behavior of this method.
52       * If isPubSubDomain equals true, then a TopicSession is passed to the callback.
53       * If false, then a QueueSession is passed to the callback.
54       * @param action callback object that exposes the session
55       * @return the result object from working with the session
56       * @throws JmsException if there is any problem
57       */
58      Object   execute(SessionCallback action) throws JmsException;
59  
60      /**
61       * Send a message to a JMS destination. The callback gives access to
62       * the JMS session and MessageProducer in order to do more complex
63       * send operations.
64       * @param action callback object that exposes the session/producer pair
65       * @return the result object from working with the session
66       * @throws JmsException checked JMSException converted to unchecked
67       */
68      Object   execute(ProducerCallback action) throws JmsException;
69  
70  
71      //-------------------------------------------------------------------------
72      // Convenience methods for sending messages
73      //-------------------------------------------------------------------------
74  
75      /**
76       * Send a message to the default destination.
77       * <p>This will only work with a default destination specified!
78       * @param messageCreator callback to create a message
79       * @throws JmsException checked JMSException converted to unchecked
80       */
81      void send(MessageCreator messageCreator) throws JmsException;
82  
83      /**
84       * Send a message to the specified destination.
85       * The MessageCreator callback creates the message given a Session.
86       * @param destination the destination to send this message to
87       * @param messageCreator callback to create a message
88       * @throws JmsException checked JMSException converted to unchecked
89       */
90      void send(Destination   destination, MessageCreator messageCreator) throws JmsException;
91  
92      /**
93       * Send a message to the specified destination.
94       * The MessageCreator callback creates the message given a Session.
95       * @param destinationName the name of the destination to send this message to
96       * (to be resolved to an actual destination by a DestinationResolver)
97       * @param messageCreator callback to create a message
98       * @throws JmsException checked JMSException converted to unchecked
99       */
100     void send(String   destinationName, MessageCreator messageCreator) throws JmsException;
101 
102 
103     //-------------------------------------------------------------------------
104     // Convenience methods for sending auto-converted messages
105     //-------------------------------------------------------------------------
106 
107     /**
108      * Send the given object to the default destination, converting the object
109      * to a JMS message with a configured MessageConverter.
110      * <p>This will only work with a default destination specified!
111      * @param message the object to convert to a message
112      * @throws JmsException converted checked JMSException to unchecked
113      */
114     void convertAndSend(Object   message) throws JmsException;
115 
116     /**
117      * Send the given object to the specified destination, converting the object
118      * to a JMS message with a configured MessageConverter.
119      * @param destination the destination to send this message to
120      * @param message the object to convert to a message
121      * @throws JmsException converted checked JMSException to unchecked
122      */
123     void convertAndSend(Destination   destination, Object   message) throws JmsException;
124 
125     /**
126      * Send the given object to the specified destination, converting the object
127      * to a JMS message with a configured MessageConverter.
128      * @param destinationName the name of the destination to send this message to
129      * (to be resolved to an actual destination by a DestinationResolver)
130      * @param message the object to convert to a message
131      * @throws JmsException checked JMSException converted to unchecked
132      */
133     void convertAndSend(String   destinationName, Object   message) throws JmsException;
134 
135     /**
136      * Send the given object to the default destination, converting the object
137      * to a JMS message with a configured MessageConverter. The MessagePostProcessor
138      * callback allows for modification of the message after conversion.
139      * <p>This will only work with a default destination specified!
140      * @param message the object to convert to a message
141      * @param postProcessor the callback to modify the message
142      * @throws JmsException checked JMSException converted to unchecked
143      */
144     void convertAndSend(Object   message, MessagePostProcessor postProcessor)
145         throws JmsException;
146 
147     /**
148      * Send the given object to the specified destination, converting the object
149      * to a JMS message with a configured MessageConverter. The MessagePostProcessor
150      * callback allows for modification of the message after conversion.
151      * @param destination the destination to send this message to
152      * @param message the object to convert to a message
153      * @param postProcessor the callback to modify the message
154      * @throws JmsException checked JMSException converted to unchecked
155      */
156     void convertAndSend(Destination   destination, Object   message, MessagePostProcessor postProcessor)
157         throws JmsException;
158 
159     /**
160      * Send the given object to the specified destination, converting the object
161      * to a JMS message with a configured MessageConverter. The MessagePostProcessor
162      * callback allows for modification of the message after conversion.
163      * @param destinationName the name of the destination to send this message to
164      * (to be resolved to an actual destination by a DestinationResolver)
165      * @param message the object to convert to a message.
166      * @param postProcessor the callback to modify the message
167      * @throws JmsException checked JMSException converted to unchecked
168      */
169     void convertAndSend(String   destinationName, Object   message, MessagePostProcessor postProcessor)
170         throws JmsException;
171 
172 
173     //-------------------------------------------------------------------------
174     // Convenience methods for receiving messages
175     //-------------------------------------------------------------------------
176 
177     /**
178      * Receive a message synchronously from the default destination, but only
179      * wait up to a specified time for delivery.
180      * <p>This method should be used carefully, since it will block the thread
181      * until the message becomes available or until the timeout value is exceeded.
182      * <p>This will only work with a default destination specified!
183      * @return the message received by the consumer, or <code>null</code> if the timeout expires
184      * @throws JmsException checked JMSException converted to unchecked
185      */
186     Message   receive() throws JmsException;
187 
188     /**
189      * Receive a message synchronously from the specified destination, but only
190      * wait up to a specified time for delivery.
191      * <p>This method should be used carefully, since it will block the thread
192      * until the message becomes available or until the timeout value is exceeded.
193      * @param destination the destination to receive a message from
194      * @return the message received by the consumer, or <code>null</code> if the timeout expires
195      * @throws JmsException checked JMSException converted to unchecked
196      */
197     Message   receive(Destination   destination) throws JmsException;
198 
199     /**
200      * Receive a message synchronously from the specified destination, but only
201      * wait up to a specified time for delivery.
202      * <p>This method should be used carefully, since it will block the thread
203      * until the message becomes available or until the timeout value is exceeded.
204      * @param destinationName the name of the destination to send this message to
205      * (to be resolved to an actual destination by a DestinationResolver)
206      * @return the message received by the consumer, or <code>null</code> if the timeout expires
207      * @throws JmsException checked JMSException converted to unchecked
208      */
209     Message   receive(String   destinationName) throws JmsException;
210 
211     /**
212      * Receive a message synchronously from the default destination, but only
213      * wait up to a specified time for delivery.
214      * <p>This method should be used carefully, since it will block the thread
215      * until the message becomes available or until the timeout value is exceeded.
216      * <p>This will only work with a default destination specified!
217      * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
218      * See the JMS specification for a detailed definition of selector expressions.
219      * @return the message received by the consumer, or <code>null</code> if the timeout expires
220      * @throws JmsException checked JMSException converted to unchecked
221      */
222     Message   receiveSelected(String   messageSelector) throws JmsException;
223 
224     /**
225      * Receive a message synchronously from the specified destination, but only
226      * wait up to a specified time for delivery.
227      * <p>This method should be used carefully, since it will block the thread
228      * until the message becomes available or until the timeout value is exceeded.
229      * @param destination the destination to receive a message from
230      * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
231      * See the JMS specification for a detailed definition of selector expressions.
232      * @return the message received by the consumer, or <code>null</code> if the timeout expires
233      * @throws JmsException checked JMSException converted to unchecked
234      */
235     Message   receiveSelected(Destination   destination, String   messageSelector) throws JmsException;
236 
237     /**
238      * Receive a message synchronously from the specified destination, but only
239      * wait up to a specified time for delivery.
240      * <p>This method should be used carefully, since it will block the thread
241      * until the message becomes available or until the timeout value is exceeded.
242      * @param destinationName the name of the destination to send this message to
243      * (to be resolved to an actual destination by a DestinationResolver)
244      * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
245      * See the JMS specification for a detailed definition of selector expressions.
246      * @return the message received by the consumer, or <code>null</code> if the timeout expires
247      * @throws JmsException checked JMSException converted to unchecked
248      */
249     Message   receiveSelected(String   destinationName, String   messageSelector) throws JmsException;
250 
251 
252     //-------------------------------------------------------------------------
253     // Convenience methods for receiving auto-converted messages
254     //-------------------------------------------------------------------------
255 
256     /**
257      * Receive a message synchronously from the default destination, but only
258      * wait up to a specified time for delivery. Convert the message into an
259      * object with a configured MessageConverter.
260      * <p>This method should be used carefully, since it will block the thread
261      * until the message becomes available or until the timeout value is exceeded.
262      * <p>This will only work with a default destination specified!
263      * @return the message produced for the consumer or <code>null</code> if the timeout expires.
264      * @throws JmsException checked JMSException converted to unchecked
265      */
266     Object   receiveAndConvert() throws JmsException;
267 
268     /**
269      * Receive a message synchronously from the specified destination, but only
270      * wait up to a specified time for delivery. Convert the message into an
271      * object with a configured MessageConverter.
272      * <p>This method should be used carefully, since it will block the thread
273      * until the message becomes available or until the timeout value is exceeded.
274      * @param destination the destination to receive a message from
275      * @return the message produced for the consumer or <code>null</code> if the timeout expires.
276      * @throws JmsException checked JMSException converted to unchecked
277      */
278     Object   receiveAndConvert(Destination   destination) throws JmsException;
279 
280     /**
281      * Receive a message synchronously from the specified destination, but only
282      * wait up to a specified time for delivery. Convert the message into an
283      * object with a configured MessageConverter.
284      * <p>This method should be used carefully, since it will block the thread
285      * until the message becomes available or until the timeout value is exceeded.
286      * @param destinationName the name of the destination to send this message to
287      * (to be resolved to an actual destination by a DestinationResolver)
288      * @return the message produced for the consumer or <code>null</code> if the timeout expires.
289      * @throws JmsException checked JMSException converted to unchecked
290      */
291     Object   receiveAndConvert(String   destinationName) throws JmsException;
292 
293     /**
294      * Receive a message synchronously from the default destination, but only
295      * wait up to a specified time for delivery. Convert the message into an
296      * object with a configured MessageConverter.
297      * <p>This method should be used carefully, since it will block the thread
298      * until the message becomes available or until the timeout value is exceeded.
299      * <p>This will only work with a default destination specified!
300      * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
301      * See the JMS specification for a detailed definition of selector expressions.
302      * @return the message produced for the consumer or <code>null</code> if the timeout expires.
303      * @throws JmsException checked JMSException converted to unchecked
304      */
305     Object   receiveSelectedAndConvert(String   messageSelector) throws JmsException;
306 
307     /**
308      * Receive a message synchronously from the specified destination, but only
309      * wait up to a specified time for delivery. Convert the message into an
310      * object with a configured MessageConverter.
311      * <p>This method should be used carefully, since it will block the thread
312      * until the message becomes available or until the timeout value is exceeded.
313      * @param destination the destination to receive a message from
314      * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
315      * See the JMS specification for a detailed definition of selector expressions.
316      * @return the message produced for the consumer or <code>null</code> if the timeout expires.
317      * @throws JmsException checked JMSException converted to unchecked
318      */
319     Object   receiveSelectedAndConvert(Destination   destination, String   messageSelector) throws JmsException;
320 
321     /**
322      * Receive a message synchronously from the specified destination, but only
323      * wait up to a specified time for delivery. Convert the message into an
324      * object with a configured MessageConverter.
325      * <p>This method should be used carefully, since it will block the thread
326      * until the message becomes available or until the timeout value is exceeded.
327      * @param destinationName the name of the destination to send this message to
328      * (to be resolved to an actual destination by a DestinationResolver)
329      * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
330      * See the JMS specification for a detailed definition of selector expressions.
331      * @return the message produced for the consumer or <code>null</code> if the timeout expires.
332      * @throws JmsException checked JMSException converted to unchecked
333      */
334     Object   receiveSelectedAndConvert(String   destinationName, String   messageSelector) throws JmsException;
335 
336 }
337
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags