001/* 002 * Copyright 2002-2014 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 * https://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 017package org.springframework.jms.core; 018 019import javax.jms.Destination; 020import javax.jms.Message; 021import javax.jms.Queue; 022 023import org.springframework.jms.JmsException; 024 025/** 026 * Specifies a basic set of JMS operations. 027 * 028 * <p>Implemented by {@link JmsTemplate}. Not often used but a useful option 029 * to enhance testability, as it can easily be mocked or stubbed. 030 * 031 * <p>Provides {@code JmsTemplate's} {@code send(..)} and 032 * {@code receive(..)} methods that mirror various JMS API methods. 033 * See the JMS specification and javadocs for details on those methods. 034 * 035 * <p>Provides also basic request reply operation using a temporary 036 * queue to collect the reply. 037 * 038 * @author Mark Pollack 039 * @author Juergen Hoeller 040 * @author Stephane Nicoll 041 * @since 1.1 042 * @see JmsTemplate 043 * @see javax.jms.Destination 044 * @see javax.jms.Session 045 * @see javax.jms.MessageProducer 046 * @see javax.jms.MessageConsumer 047 */ 048public interface JmsOperations { 049 050 /** 051 * Execute the action specified by the given action object within a JMS Session. 052 * @param action callback object that exposes the session 053 * @return the result object from working with the session 054 * @throws JmsException if there is any problem 055 */ 056 <T> T execute(SessionCallback<T> action) throws JmsException; 057 058 /** 059 * Send messages to the default JMS destination (or one specified 060 * for each send operation). The callback gives access to the JMS Session 061 * and MessageProducer in order to perform complex send operations. 062 * @param action callback object that exposes the session/producer pair 063 * @return the result object from working with the session 064 * @throws JmsException checked JMSException converted to unchecked 065 */ 066 <T> T execute(ProducerCallback<T> action) throws JmsException; 067 068 /** 069 * Send messages to a JMS destination. The callback gives access to the JMS Session 070 * and MessageProducer in order to perform complex send operations. 071 * @param destination the destination to send messages to 072 * @param action callback object that exposes the session/producer pair 073 * @return the result object from working with the session 074 * @throws JmsException checked JMSException converted to unchecked 075 */ 076 <T> T execute(Destination destination, ProducerCallback<T> action) throws JmsException; 077 078 /** 079 * Send messages to a JMS destination. The callback gives access to the JMS Session 080 * and MessageProducer in order to perform complex send operations. 081 * @param destinationName the name of the destination to send messages to 082 * (to be resolved to an actual destination by a DestinationResolver) 083 * @param action callback object that exposes the session/producer pair 084 * @return the result object from working with the session 085 * @throws JmsException checked JMSException converted to unchecked 086 */ 087 <T> T execute(String destinationName, ProducerCallback<T> action) throws JmsException; 088 089 090 //--------------------------------------------------------------------------------------- 091 // Convenience methods for sending messages 092 //--------------------------------------------------------------------------------------- 093 094 /** 095 * Send a message to the default destination. 096 * <p>This will only work with a default destination specified! 097 * @param messageCreator callback to create a message 098 * @throws JmsException checked JMSException converted to unchecked 099 */ 100 void send(MessageCreator messageCreator) throws JmsException; 101 102 /** 103 * Send a message to the specified destination. 104 * The MessageCreator callback creates the message given a Session. 105 * @param destination the destination to send this message to 106 * @param messageCreator callback to create a message 107 * @throws JmsException checked JMSException converted to unchecked 108 */ 109 void send(Destination destination, MessageCreator messageCreator) throws JmsException; 110 111 /** 112 * Send a message to the specified destination. 113 * The MessageCreator callback creates the message given a Session. 114 * @param destinationName the name of the destination to send this message to 115 * (to be resolved to an actual destination by a DestinationResolver) 116 * @param messageCreator callback to create a message 117 * @throws JmsException checked JMSException converted to unchecked 118 */ 119 void send(String destinationName, MessageCreator messageCreator) throws JmsException; 120 121 122 //--------------------------------------------------------------------------------------- 123 // Convenience methods for sending auto-converted messages 124 //--------------------------------------------------------------------------------------- 125 126 /** 127 * Send the given object to the default destination, converting the object 128 * to a JMS message with a configured MessageConverter. 129 * <p>This will only work with a default destination specified! 130 * @param message the object to convert to a message 131 * @throws JmsException converted checked JMSException to unchecked 132 */ 133 void convertAndSend(Object message) throws JmsException; 134 135 /** 136 * Send the given object to the specified destination, converting the object 137 * to a JMS message with a configured MessageConverter. 138 * @param destination the destination to send this message to 139 * @param message the object to convert to a message 140 * @throws JmsException converted checked JMSException to unchecked 141 */ 142 void convertAndSend(Destination destination, Object message) throws JmsException; 143 144 /** 145 * Send the given object to the specified destination, converting the object 146 * to a JMS message with a configured MessageConverter. 147 * @param destinationName the name of the destination to send this message to 148 * (to be resolved to an actual destination by a DestinationResolver) 149 * @param message the object to convert to a message 150 * @throws JmsException checked JMSException converted to unchecked 151 */ 152 void convertAndSend(String destinationName, Object message) throws JmsException; 153 154 /** 155 * Send the given object to the default destination, converting the object 156 * to a JMS message with a configured MessageConverter. The MessagePostProcessor 157 * callback allows for modification of the message after conversion. 158 * <p>This will only work with a default destination specified! 159 * @param message the object to convert to a message 160 * @param postProcessor the callback to modify the message 161 * @throws JmsException checked JMSException converted to unchecked 162 */ 163 void convertAndSend(Object message, MessagePostProcessor postProcessor) 164 throws JmsException; 165 166 /** 167 * Send the given object to the specified destination, converting the object 168 * to a JMS message with a configured MessageConverter. The MessagePostProcessor 169 * callback allows for modification of the message after conversion. 170 * @param destination the destination to send this message to 171 * @param message the object to convert to a message 172 * @param postProcessor the callback to modify the message 173 * @throws JmsException checked JMSException converted to unchecked 174 */ 175 void convertAndSend(Destination destination, Object message, MessagePostProcessor postProcessor) 176 throws JmsException; 177 178 /** 179 * Send the given object to the specified destination, converting the object 180 * to a JMS message with a configured MessageConverter. The MessagePostProcessor 181 * callback allows for modification of the message after conversion. 182 * @param destinationName the name of the destination to send this message to 183 * (to be resolved to an actual destination by a DestinationResolver) 184 * @param message the object to convert to a message. 185 * @param postProcessor the callback to modify the message 186 * @throws JmsException checked JMSException converted to unchecked 187 */ 188 void convertAndSend(String destinationName, Object message, MessagePostProcessor postProcessor) 189 throws JmsException; 190 191 192 //--------------------------------------------------------------------------------------- 193 // Convenience methods for receiving messages 194 //--------------------------------------------------------------------------------------- 195 196 /** 197 * Receive a message synchronously from the default destination, but only 198 * wait up to a specified time for delivery. 199 * <p>This method should be used carefully, since it will block the thread 200 * until the message becomes available or until the timeout value is exceeded. 201 * <p>This will only work with a default destination specified! 202 * @return the message received by the consumer, or {@code null} if the timeout expires 203 * @throws JmsException checked JMSException converted to unchecked 204 */ 205 Message receive() throws JmsException; 206 207 /** 208 * Receive a message synchronously from the specified destination, but only 209 * wait up to a specified time for delivery. 210 * <p>This method should be used carefully, since it will block the thread 211 * until the message becomes available or until the timeout value is exceeded. 212 * @param destination the destination to receive a message from 213 * @return the message received by the consumer, or {@code null} if the timeout expires 214 * @throws JmsException checked JMSException converted to unchecked 215 */ 216 Message receive(Destination destination) throws JmsException; 217 218 /** 219 * Receive a message synchronously from the specified destination, but only 220 * wait up to a specified time for delivery. 221 * <p>This method should be used carefully, since it will block the thread 222 * until the message becomes available or until the timeout value is exceeded. 223 * @param destinationName the name of the destination to send this message to 224 * (to be resolved to an actual destination by a DestinationResolver) 225 * @return the message received by the consumer, or {@code null} if the timeout expires 226 * @throws JmsException checked JMSException converted to unchecked 227 */ 228 Message receive(String destinationName) throws JmsException; 229 230 /** 231 * Receive a message synchronously from the default destination, but only 232 * wait up to a specified time for delivery. 233 * <p>This method should be used carefully, since it will block the thread 234 * until the message becomes available or until the timeout value is exceeded. 235 * <p>This will only work with a default destination specified! 236 * @param messageSelector the JMS message selector expression (or {@code null} if none). 237 * See the JMS specification for a detailed definition of selector expressions. 238 * @return the message received by the consumer, or {@code null} if the timeout expires 239 * @throws JmsException checked JMSException converted to unchecked 240 */ 241 Message receiveSelected(String messageSelector) throws JmsException; 242 243 /** 244 * Receive a message synchronously from the specified destination, but only 245 * wait up to a specified time for delivery. 246 * <p>This method should be used carefully, since it will block the thread 247 * until the message becomes available or until the timeout value is exceeded. 248 * @param destination the destination to receive a message from 249 * @param messageSelector the JMS message selector expression (or {@code null} if none). 250 * See the JMS specification for a detailed definition of selector expressions. 251 * @return the message received by the consumer, or {@code null} if the timeout expires 252 * @throws JmsException checked JMSException converted to unchecked 253 */ 254 Message receiveSelected(Destination destination, String messageSelector) throws JmsException; 255 256 /** 257 * Receive a message synchronously from the specified destination, but only 258 * wait up to a specified time for delivery. 259 * <p>This method should be used carefully, since it will block the thread 260 * until the message becomes available or until the timeout value is exceeded. 261 * @param destinationName the name of the destination to send this message to 262 * (to be resolved to an actual destination by a DestinationResolver) 263 * @param messageSelector the JMS message selector expression (or {@code null} if none). 264 * See the JMS specification for a detailed definition of selector expressions. 265 * @return the message received by the consumer, or {@code null} if the timeout expires 266 * @throws JmsException checked JMSException converted to unchecked 267 */ 268 Message receiveSelected(String destinationName, String messageSelector) throws JmsException; 269 270 271 //--------------------------------------------------------------------------------------- 272 // Convenience methods for receiving auto-converted messages 273 //--------------------------------------------------------------------------------------- 274 275 /** 276 * Receive a message synchronously from the default destination, but only 277 * wait up to a specified time for delivery. Convert the message into an 278 * object with a configured MessageConverter. 279 * <p>This method should be used carefully, since it will block the thread 280 * until the message becomes available or until the timeout value is exceeded. 281 * <p>This will only work with a default destination specified! 282 * @return the message produced for the consumer or {@code null} if the timeout expires. 283 * @throws JmsException checked JMSException converted to unchecked 284 */ 285 Object receiveAndConvert() throws JmsException; 286 287 /** 288 * Receive a message synchronously from the specified destination, but only 289 * wait up to a specified time for delivery. Convert the message into an 290 * object with a configured MessageConverter. 291 * <p>This method should be used carefully, since it will block the thread 292 * until the message becomes available or until the timeout value is exceeded. 293 * @param destination the destination to receive a message from 294 * @return the message produced for the consumer or {@code null} if the timeout expires. 295 * @throws JmsException checked JMSException converted to unchecked 296 */ 297 Object receiveAndConvert(Destination destination) throws JmsException; 298 299 /** 300 * Receive a message synchronously from the specified destination, but only 301 * wait up to a specified time for delivery. Convert the message into an 302 * object with a configured MessageConverter. 303 * <p>This method should be used carefully, since it will block the thread 304 * until the message becomes available or until the timeout value is exceeded. 305 * @param destinationName the name of the destination to send this message to 306 * (to be resolved to an actual destination by a DestinationResolver) 307 * @return the message produced for the consumer or {@code null} if the timeout expires. 308 * @throws JmsException checked JMSException converted to unchecked 309 */ 310 Object receiveAndConvert(String destinationName) throws JmsException; 311 312 /** 313 * Receive a message synchronously from the default 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 * <p>This will only work with a default destination specified! 319 * @param messageSelector the JMS message selector expression (or {@code null} 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} if the timeout expires. 322 * @throws JmsException checked JMSException converted to unchecked 323 */ 324 Object receiveSelectedAndConvert(String messageSelector) throws JmsException; 325 326 /** 327 * Receive a message synchronously from the specified destination, but only 328 * wait up to a specified time for delivery. Convert the message into an 329 * object with a configured MessageConverter. 330 * <p>This method should be used carefully, since it will block the thread 331 * until the message becomes available or until the timeout value is exceeded. 332 * @param destination the destination to receive a message from 333 * @param messageSelector the JMS message selector expression (or {@code null} if none). 334 * See the JMS specification for a detailed definition of selector expressions. 335 * @return the message produced for the consumer or {@code null} if the timeout expires. 336 * @throws JmsException checked JMSException converted to unchecked 337 */ 338 Object receiveSelectedAndConvert(Destination destination, String messageSelector) throws JmsException; 339 340 /** 341 * Receive a message synchronously from the specified destination, but only 342 * wait up to a specified time for delivery. Convert the message into an 343 * object with a configured MessageConverter. 344 * <p>This method should be used carefully, since it will block the thread 345 * until the message becomes available or until the timeout value is exceeded. 346 * @param destinationName the name of the destination to send this message to 347 * (to be resolved to an actual destination by a DestinationResolver) 348 * @param messageSelector the JMS message selector expression (or {@code null} if none). 349 * See the JMS specification for a detailed definition of selector expressions. 350 * @return the message produced for the consumer or {@code null} if the timeout expires. 351 * @throws JmsException checked JMSException converted to unchecked 352 */ 353 Object receiveSelectedAndConvert(String destinationName, String messageSelector) throws JmsException; 354 355 356 //--------------------------------------------------------------------------------------- 357 // Convenience methods for sending messages to and receiving the reply from a destination 358 //--------------------------------------------------------------------------------------- 359 360 /** 361 * Send a request message and receive the reply from a default destination. The 362 * {@link MessageCreator} callback creates the message given a Session. A temporary 363 * queue is created as part of this operation and is set in the {@code JMSReplyTO} 364 * header of the message. 365 * <p>This will only work with a default destination specified! 366 * @param messageCreator callback to create a request message 367 * @return the reply, possibly {@code null} if the message could not be received, 368 * for example due to a timeout 369 * @throws JmsException checked JMSException converted to unchecked 370 * @since 4.1 371 */ 372 Message sendAndReceive(MessageCreator messageCreator) throws JmsException; 373 374 /** 375 * Send a message and receive the reply from the specified destination. The 376 * {@link MessageCreator} callback creates the message given a Session. A temporary 377 * queue is created as part of this operation and is set in the {@code JMSReplyTO} 378 * header of the message. 379 * @param destination the destination to send this message to 380 * @param messageCreator callback to create a message 381 * @return the reply, possibly {@code null} if the message could not be received, 382 * for example due to a timeout 383 * @throws JmsException checked JMSException converted to unchecked 384 * @since 4.1 385 */ 386 Message sendAndReceive(Destination destination, MessageCreator messageCreator) throws JmsException; 387 388 /** 389 * Send a message and receive the reply from the specified destination. The 390 * {@link MessageCreator} callback creates the message given a Session. A temporary 391 * queue is created as part of this operation and is set in the {@code JMSReplyTO} 392 * header of the message. 393 * @param destinationName the name of the destination to send this message to 394 * (to be resolved to an actual destination by a DestinationResolver) 395 * @param messageCreator callback to create a message 396 * @return the reply, possibly {@code null} if the message could not be received, 397 * for example due to a timeout 398 * @throws JmsException checked JMSException converted to unchecked 399 * @since 4.1 400 */ 401 Message sendAndReceive(String destinationName, MessageCreator messageCreator) throws JmsException; 402 403 404 //--------------------------------------------------------------------------------------- 405 // Convenience methods for browsing messages 406 //--------------------------------------------------------------------------------------- 407 408 /** 409 * Browse messages in the default JMS queue. The callback gives access to the JMS 410 * Session and QueueBrowser in order to browse the queue and react to the contents. 411 * @param action callback object that exposes the session/browser pair 412 * @return the result object from working with the session 413 * @throws JmsException checked JMSException converted to unchecked 414 */ 415 <T> T browse(BrowserCallback<T> action) throws JmsException; 416 417 /** 418 * Browse messages in a JMS queue. The callback gives access to the JMS Session 419 * and QueueBrowser in order to browse the queue and react to the contents. 420 * @param queue the queue to browse 421 * @param action callback object that exposes the session/browser pair 422 * @return the result object from working with the session 423 * @throws JmsException checked JMSException converted to unchecked 424 */ 425 <T> T browse(Queue queue, BrowserCallback<T> action) throws JmsException; 426 427 /** 428 * Browse messages in a JMS queue. The callback gives access to the JMS Session 429 * and QueueBrowser in order to browse the queue and react to the contents. 430 * @param queueName the name of the queue to browse 431 * (to be resolved to an actual destination by a DestinationResolver) 432 * @param action callback object that exposes the session/browser pair 433 * @return the result object from working with the session 434 * @throws JmsException checked JMSException converted to unchecked 435 */ 436 <T> T browse(String queueName, BrowserCallback<T> action) throws JmsException; 437 438 /** 439 * Browse selected messages in a JMS queue. The callback gives access to the JMS 440 * Session and QueueBrowser in order to browse the queue and react to the contents. 441 * @param messageSelector the JMS message selector expression (or {@code null} if none). 442 * See the JMS specification for a detailed definition of selector expressions. 443 * @param action callback object that exposes the session/browser pair 444 * @return the result object from working with the session 445 * @throws JmsException checked JMSException converted to unchecked 446 */ 447 <T> T browseSelected(String messageSelector, BrowserCallback<T> action) throws JmsException; 448 449 /** 450 * Browse selected messages in a JMS queue. The callback gives access to the JMS 451 * Session and QueueBrowser in order to browse the queue and react to the contents. 452 * @param queue the queue to browse 453 * @param messageSelector the JMS message selector expression (or {@code null} if none). 454 * See the JMS specification for a detailed definition of selector expressions. 455 * @param action callback object that exposes the session/browser pair 456 * @return the result object from working with the session 457 * @throws JmsException checked JMSException converted to unchecked 458 */ 459 <T> T browseSelected(Queue queue, String messageSelector, BrowserCallback<T> action) throws JmsException; 460 461 /** 462 * Browse selected messages in a JMS queue. The callback gives access to the JMS 463 * Session and QueueBrowser in order to browse the queue and react to the contents. 464 * @param queueName the name of the queue to browse 465 * (to be resolved to an actual destination by a DestinationResolver) 466 * @param messageSelector the JMS message selector expression (or {@code null} if none). 467 * See the JMS specification for a detailed definition of selector expressions. 468 * @param action callback object that exposes the session/browser pair 469 * @return the result object from working with the session 470 * @throws JmsException checked JMSException converted to unchecked 471 */ 472 <T> T browseSelected(String queueName, String messageSelector, BrowserCallback<T> action) throws JmsException; 473 474}