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