001: /*
002: * Copyright 2002-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.jms.core;
018:
019: import javax.jms.Destination;
020: import javax.jms.Message;
021:
022: import org.springframework.jms.JmsException;
023:
024: /**
025: * Specifies a basic set of JMS operations.
026: *
027: * <p>Implemented by {@link JmsTemplate}. Not often used but a useful option
028: * to enhance testability, as it can easily be mocked or stubbed.
029: *
030: * <p>Provides <code>JmsTemplate's</code> <code>send(..)</code> and
031: * <code>receive(..)</code> methods that mirror various JMS API methods.
032: * See the JMS specification and javadocs for details on those methods.
033: *
034: * @author Mark Pollack
035: * @author Juergen Hoeller
036: * @since 1.1
037: * @see JmsTemplate
038: * @see javax.jms.Destination
039: * @see javax.jms.Session
040: * @see javax.jms.MessageProducer
041: * @see javax.jms.MessageConsumer
042: */
043: public interface JmsOperations {
044:
045: /**
046: * Execute the action specified by the given action object within
047: * a JMS Session.
048: * <p>When used with a 1.0.2 provider, you may need to downcast
049: * to the appropriate domain implementation, either QueueSession or
050: * TopicSession in the action objects doInJms callback method.
051: * <p>Note: The value of isPubSubDomain affects the behavior of this method.
052: * If isPubSubDomain equals true, then a TopicSession is passed to the callback.
053: * If false, then a QueueSession is passed to the callback.
054: * @param action callback object that exposes the session
055: * @return the result object from working with the session
056: * @throws JmsException if there is any problem
057: */
058: Object execute(SessionCallback action) throws JmsException;
059:
060: /**
061: * Send a message to a JMS destination. The callback gives access to
062: * the JMS session and MessageProducer in order to do more complex
063: * send operations.
064: * @param action callback object that exposes the session/producer pair
065: * @return the result object from working with the session
066: * @throws JmsException checked JMSException converted to unchecked
067: */
068: Object execute(ProducerCallback action) throws JmsException;
069:
070: //-------------------------------------------------------------------------
071: // Convenience methods for sending messages
072: //-------------------------------------------------------------------------
073:
074: /**
075: * Send a message to the default destination.
076: * <p>This will only work with a default destination specified!
077: * @param messageCreator callback to create a message
078: * @throws JmsException checked JMSException converted to unchecked
079: */
080: void send(MessageCreator messageCreator) throws JmsException;
081:
082: /**
083: * Send a message to the specified destination.
084: * The MessageCreator callback creates the message given a Session.
085: * @param destination the destination to send this message to
086: * @param messageCreator callback to create a message
087: * @throws JmsException checked JMSException converted to unchecked
088: */
089: void send(Destination destination, MessageCreator messageCreator)
090: throws JmsException;
091:
092: /**
093: * Send a message to the specified destination.
094: * The MessageCreator callback creates the message given a Session.
095: * @param destinationName the name of the destination to send this message to
096: * (to be resolved to an actual destination by a DestinationResolver)
097: * @param messageCreator callback to create a message
098: * @throws JmsException checked JMSException converted to unchecked
099: */
100: void send(String destinationName, MessageCreator messageCreator)
101: throws JmsException;
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)
124: throws JmsException;
125:
126: /**
127: * Send the given object to the specified destination, converting the object
128: * to a JMS message with a configured MessageConverter.
129: * @param destinationName the name of the destination to send this message to
130: * (to be resolved to an actual destination by a DestinationResolver)
131: * @param message the object to convert to a message
132: * @throws JmsException checked JMSException converted to unchecked
133: */
134: void convertAndSend(String destinationName, Object message)
135: throws JmsException;
136:
137: /**
138: * Send the given object to the default destination, converting the object
139: * to a JMS message with a configured MessageConverter. The MessagePostProcessor
140: * callback allows for modification of the message after conversion.
141: * <p>This will only work with a default destination specified!
142: * @param message the object to convert to a message
143: * @param postProcessor the callback to modify the message
144: * @throws JmsException checked JMSException converted to unchecked
145: */
146: void convertAndSend(Object message,
147: MessagePostProcessor postProcessor) throws JmsException;
148:
149: /**
150: * Send the given object to the specified destination, converting the object
151: * to a JMS message with a configured MessageConverter. The MessagePostProcessor
152: * callback allows for modification of the message after conversion.
153: * @param destination the destination to send this message to
154: * @param message the object to convert to a message
155: * @param postProcessor the callback to modify the message
156: * @throws JmsException checked JMSException converted to unchecked
157: */
158: void convertAndSend(Destination destination, Object message,
159: MessagePostProcessor postProcessor) throws JmsException;
160:
161: /**
162: * Send the given object to the specified destination, converting the object
163: * to a JMS message with a configured MessageConverter. The MessagePostProcessor
164: * callback allows for modification of the message after conversion.
165: * @param destinationName the name of the destination to send this message to
166: * (to be resolved to an actual destination by a DestinationResolver)
167: * @param message the object to convert to a message.
168: * @param postProcessor the callback to modify the message
169: * @throws JmsException checked JMSException converted to unchecked
170: */
171: void convertAndSend(String destinationName, Object message,
172: MessagePostProcessor postProcessor) throws JmsException;
173:
174: //-------------------------------------------------------------------------
175: // Convenience methods for receiving messages
176: //-------------------------------------------------------------------------
177:
178: /**
179: * Receive a message synchronously from the default destination, but only
180: * wait up to a specified time for delivery.
181: * <p>This method should be used carefully, since it will block the thread
182: * until the message becomes available or until the timeout value is exceeded.
183: * <p>This will only work with a default destination specified!
184: * @return the message received by the consumer, or <code>null</code> if the timeout expires
185: * @throws JmsException checked JMSException converted to unchecked
186: */
187: Message receive() throws JmsException;
188:
189: /**
190: * Receive a message synchronously from the specified destination, but only
191: * wait up to a specified time for delivery.
192: * <p>This method should be used carefully, since it will block the thread
193: * until the message becomes available or until the timeout value is exceeded.
194: * @param destination the destination to receive a message from
195: * @return the message received by the consumer, or <code>null</code> if the timeout expires
196: * @throws JmsException checked JMSException converted to unchecked
197: */
198: Message receive(Destination destination) throws JmsException;
199:
200: /**
201: * Receive a message synchronously from the specified destination, but only
202: * wait up to a specified time for delivery.
203: * <p>This method should be used carefully, since it will block the thread
204: * until the message becomes available or until the timeout value is exceeded.
205: * @param destinationName the name of the destination to send this message to
206: * (to be resolved to an actual destination by a DestinationResolver)
207: * @return the message received by the consumer, or <code>null</code> if the timeout expires
208: * @throws JmsException checked JMSException converted to unchecked
209: */
210: Message receive(String destinationName) throws JmsException;
211:
212: /**
213: * Receive a message synchronously from the default destination, but only
214: * wait up to a specified time for delivery.
215: * <p>This method should be used carefully, since it will block the thread
216: * until the message becomes available or until the timeout value is exceeded.
217: * <p>This will only work with a default destination specified!
218: * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
219: * See the JMS specification for a detailed definition of selector expressions.
220: * @return the message received by the consumer, or <code>null</code> if the timeout expires
221: * @throws JmsException checked JMSException converted to unchecked
222: */
223: Message receiveSelected(String messageSelector) throws JmsException;
224:
225: /**
226: * Receive a message synchronously from the specified destination, but only
227: * wait up to a specified time for delivery.
228: * <p>This method should be used carefully, since it will block the thread
229: * until the message becomes available or until the timeout value is exceeded.
230: * @param destination the destination to receive a message from
231: * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
232: * See the JMS specification for a detailed definition of selector expressions.
233: * @return the message received by the consumer, or <code>null</code> if the timeout expires
234: * @throws JmsException checked JMSException converted to unchecked
235: */
236: Message receiveSelected(Destination destination,
237: String messageSelector) throws JmsException;
238:
239: /**
240: * Receive a message synchronously from the specified destination, but only
241: * wait up to a specified time for delivery.
242: * <p>This method should be used carefully, since it will block the thread
243: * until the message becomes available or until the timeout value is exceeded.
244: * @param destinationName the name of the destination to send this message to
245: * (to be resolved to an actual destination by a DestinationResolver)
246: * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
247: * See the JMS specification for a detailed definition of selector expressions.
248: * @return the message received by the consumer, or <code>null</code> if the timeout expires
249: * @throws JmsException checked JMSException converted to unchecked
250: */
251: Message receiveSelected(String destinationName,
252: String messageSelector) throws JmsException;
253:
254: //-------------------------------------------------------------------------
255: // Convenience methods for receiving auto-converted messages
256: //-------------------------------------------------------------------------
257:
258: /**
259: * Receive a message synchronously from the default destination, but only
260: * wait up to a specified time for delivery. Convert the message into an
261: * object with a configured MessageConverter.
262: * <p>This method should be used carefully, since it will block the thread
263: * until the message becomes available or until the timeout value is exceeded.
264: * <p>This will only work with a default destination specified!
265: * @return the message produced for the consumer or <code>null</code> if the timeout expires.
266: * @throws JmsException checked JMSException converted to unchecked
267: */
268: Object receiveAndConvert() throws JmsException;
269:
270: /**
271: * Receive a message synchronously from the specified destination, but only
272: * wait up to a specified time for delivery. Convert the message into an
273: * object with a configured MessageConverter.
274: * <p>This method should be used carefully, since it will block the thread
275: * until the message becomes available or until the timeout value is exceeded.
276: * @param destination the destination to receive a message from
277: * @return the message produced for the consumer or <code>null</code> if the timeout expires.
278: * @throws JmsException checked JMSException converted to unchecked
279: */
280: Object receiveAndConvert(Destination destination)
281: throws JmsException;
282:
283: /**
284: * Receive a message synchronously from the specified destination, but only
285: * wait up to a specified time for delivery. Convert the message into an
286: * object with a configured MessageConverter.
287: * <p>This method should be used carefully, since it will block the thread
288: * until the message becomes available or until the timeout value is exceeded.
289: * @param destinationName the name of the destination to send this message to
290: * (to be resolved to an actual destination by a DestinationResolver)
291: * @return the message produced for the consumer or <code>null</code> if the timeout expires.
292: * @throws JmsException checked JMSException converted to unchecked
293: */
294: Object receiveAndConvert(String destinationName)
295: throws JmsException;
296:
297: /**
298: * Receive a message synchronously from the default destination, but only
299: * wait up to a specified time for delivery. Convert the message into an
300: * object with a configured MessageConverter.
301: * <p>This method should be used carefully, since it will block the thread
302: * until the message becomes available or until the timeout value is exceeded.
303: * <p>This will only work with a default destination specified!
304: * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
305: * See the JMS specification for a detailed definition of selector expressions.
306: * @return the message produced for the consumer or <code>null</code> if the timeout expires.
307: * @throws JmsException checked JMSException converted to unchecked
308: */
309: Object receiveSelectedAndConvert(String messageSelector)
310: throws JmsException;
311:
312: /**
313: * Receive a message synchronously from the specified destination, but only
314: * wait up to a specified time for delivery. Convert the message into an
315: * object with a configured MessageConverter.
316: * <p>This method should be used carefully, since it will block the thread
317: * until the message becomes available or until the timeout value is exceeded.
318: * @param destination the destination to receive a message from
319: * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
320: * See the JMS specification for a detailed definition of selector expressions.
321: * @return the message produced for the consumer or <code>null</code> if the timeout expires.
322: * @throws JmsException checked JMSException converted to unchecked
323: */
324: Object receiveSelectedAndConvert(Destination destination,
325: String messageSelector) throws JmsException;
326:
327: /**
328: * Receive a message synchronously from the specified destination, but only
329: * wait up to a specified time for delivery. Convert the message into an
330: * object with a configured MessageConverter.
331: * <p>This method should be used carefully, since it will block the thread
332: * until the message becomes available or until the timeout value is exceeded.
333: * @param destinationName the name of the destination to send this message to
334: * (to be resolved to an actual destination by a DestinationResolver)
335: * @param messageSelector the JMS message selector expression (or <code>null</code> if none).
336: * See the JMS specification for a detailed definition of selector expressions.
337: * @return the message produced for the consumer or <code>null</code> if the timeout expires.
338: * @throws JmsException checked JMSException converted to unchecked
339: */
340: Object receiveSelectedAndConvert(String destinationName,
341: String messageSelector) throws JmsException;
342:
343: }
|