Spring Framework example source code file (JmsOperations.java)

This example Spring Framework source code file (JmsOperations.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Spring Framework tags/keywords

browsercallback, jmsexception, jmsexception, jmsoperations, message, message, messagecreator, messagepostprocessor, object, object, producercallback, string, string

The Spring Framework JmsOperations.java source code

/*
 * Copyright 2002-2008 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.jms.core;

import javax.jms.Destination;
import javax.jms.Message;
import javax.jms.Queue;

import org.springframework.jms.JmsException;

/**
 * Specifies a basic set of JMS operations.
 * 
 * <p>Implemented by {@link JmsTemplate}. Not often used but a useful option
 * to enhance testability, as it can easily be mocked or stubbed.
 *
 * <p>Provides JmsTemplate's send(..) and
 * <code>receive(..) methods that mirror various JMS API methods.
 * See the JMS specification and javadocs for details on those methods.
 *
 * @author Mark Pollack
 * @author Juergen Hoeller
 * @since 1.1
 * @see JmsTemplate
 * @see javax.jms.Destination
 * @see javax.jms.Session
 * @see javax.jms.MessageProducer
 * @see javax.jms.MessageConsumer
 */
public interface JmsOperations {

	/**
	 * Execute the action specified by the given action object within a JMS Session.
	 * <p>When used with a 1.0.2 provider, you may need to downcast
	 * to the appropriate domain implementation, either QueueSession or
	 * TopicSession in the action objects doInJms callback method.
	 * @param action callback object that exposes the session
	 * @return the result object from working with the session
	 * @throws JmsException if there is any problem
	 */
	Object execute(SessionCallback action) throws JmsException;

	/**
	 * Send messages to the default JMS destination (or one specified
	 * for each send operation). The callback gives access to the JMS Session
	 * and MessageProducer in order to perform complex send operations.
	 * @param action callback object that exposes the session/producer pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object execute(ProducerCallback action) throws JmsException;

	/**
	 * Send messages to a JMS destination. The callback gives access to the JMS Session
	 * and MessageProducer in order to perform complex send operations.
	 * @param destination the destination to send messages to
	 * @param action callback object that exposes the session/producer pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object execute(Destination destination, ProducerCallback action) throws JmsException;

	/**
	 * Send messages to a JMS destination. The callback gives access to the JMS Session
	 * and MessageProducer in order to perform complex send operations.
	 * @param destinationName the name of the destination to send messages to
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @param action callback object that exposes the session/producer pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object execute(String destinationName, ProducerCallback action) throws JmsException;


	//-------------------------------------------------------------------------
	// Convenience methods for sending messages
	//-------------------------------------------------------------------------

	/**
	 * Send a message to the default destination.
	 * <p>This will only work with a default destination specified!
	 * @param messageCreator callback to create a message
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	void send(MessageCreator messageCreator) throws JmsException;

	/**
	 * Send a message to the specified destination.
	 * The MessageCreator callback creates the message given a Session.
	 * @param destination the destination to send this message to
	 * @param messageCreator callback to create a message
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	void send(Destination destination, MessageCreator messageCreator) throws JmsException;

	/**
	 * Send a message to the specified destination.
	 * The MessageCreator callback creates the message given a Session.
	 * @param destinationName the name of the destination to send this message to
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @param messageCreator callback to create a message
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	void send(String destinationName, MessageCreator messageCreator) throws JmsException;


	//-------------------------------------------------------------------------
	// Convenience methods for sending auto-converted messages
	//-------------------------------------------------------------------------

	/**
	 * Send the given object to the default destination, converting the object
	 * to a JMS message with a configured MessageConverter.
	 * <p>This will only work with a default destination specified!
	 * @param message the object to convert to a message
	 * @throws JmsException converted checked JMSException to unchecked
	 */
	void convertAndSend(Object message) throws JmsException;

	/**
	 * Send the given object to the specified destination, converting the object
	 * to a JMS message with a configured MessageConverter.
	 * @param destination the destination to send this message to
	 * @param message the object to convert to a message
	 * @throws JmsException converted checked JMSException to unchecked
	 */
	void convertAndSend(Destination destination, Object message) throws JmsException;

	/**
	 * Send the given object to the specified destination, converting the object
	 * to a JMS message with a configured MessageConverter.
	 * @param destinationName the name of the destination to send this message to
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @param message the object to convert to a message
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	void convertAndSend(String destinationName, Object message) throws JmsException;

	/**
	 * Send the given object to the default destination, converting the object
	 * to a JMS message with a configured MessageConverter. The MessagePostProcessor
	 * callback allows for modification of the message after conversion.
	 * <p>This will only work with a default destination specified!
	 * @param message the object to convert to a message
	 * @param postProcessor the callback to modify the message
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	void convertAndSend(Object message, MessagePostProcessor postProcessor)
	    throws JmsException;

	/**
	 * Send the given object to the specified destination, converting the object
	 * to a JMS message with a configured MessageConverter. The MessagePostProcessor
	 * callback allows for modification of the message after conversion.
	 * @param destination the destination to send this message to
	 * @param message the object to convert to a message
	 * @param postProcessor the callback to modify the message
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	void convertAndSend(Destination destination, Object message, MessagePostProcessor postProcessor)
	    throws JmsException;

	/**
	 * Send the given object to the specified destination, converting the object
	 * to a JMS message with a configured MessageConverter. The MessagePostProcessor
	 * callback allows for modification of the message after conversion.
	 * @param destinationName the name of the destination to send this message to
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @param message the object to convert to a message.
	 * @param postProcessor the callback to modify the message
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	void convertAndSend(String destinationName, Object message, MessagePostProcessor postProcessor)
	    throws JmsException;


	//-------------------------------------------------------------------------
	// Convenience methods for receiving messages
	//-------------------------------------------------------------------------

	/**
	 * Receive a message synchronously from the default destination, but only
	 * wait up to a specified time for delivery.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * <p>This will only work with a default destination specified!
	 * @return the message received by the consumer, or <code>null if the timeout expires
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Message receive() throws JmsException;

	/**
	 * Receive a message synchronously from the specified destination, but only
	 * wait up to a specified time for delivery.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * @param destination the destination to receive a message from
	 * @return the message received by the consumer, or <code>null if the timeout expires
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Message receive(Destination destination) throws JmsException;

	/**
	 * Receive a message synchronously from the specified destination, but only
	 * wait up to a specified time for delivery.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * @param destinationName the name of the destination to send this message to
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @return the message received by the consumer, or <code>null if the timeout expires
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Message receive(String destinationName) throws JmsException;

	/**
	 * Receive a message synchronously from the default destination, but only
	 * wait up to a specified time for delivery.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * <p>This will only work with a default destination specified!
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @return the message received by the consumer, or <code>null if the timeout expires
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Message receiveSelected(String messageSelector) throws JmsException;

	/**
	 * Receive a message synchronously from the specified destination, but only
	 * wait up to a specified time for delivery.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * @param destination the destination to receive a message from
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @return the message received by the consumer, or <code>null if the timeout expires
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Message receiveSelected(Destination destination, String messageSelector) throws JmsException;

	/**
	 * Receive a message synchronously from the specified destination, but only
	 * wait up to a specified time for delivery.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * @param destinationName the name of the destination to send this message to
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @return the message received by the consumer, or <code>null if the timeout expires
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Message receiveSelected(String destinationName, String messageSelector) throws JmsException;


	//-------------------------------------------------------------------------
	// Convenience methods for receiving auto-converted messages
	//-------------------------------------------------------------------------

	/**
	 * Receive a message synchronously from the default destination, but only
	 * wait up to a specified time for delivery. Convert the message into an
	 * object with a configured MessageConverter.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * <p>This will only work with a default destination specified!
	 * @return the message produced for the consumer or <code>null if the timeout expires.
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object receiveAndConvert() throws JmsException;

	/**
	 * Receive a message synchronously from the specified destination, but only
	 * wait up to a specified time for delivery. Convert the message into an
	 * object with a configured MessageConverter.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * @param destination the destination to receive a message from
	 * @return the message produced for the consumer or <code>null if the timeout expires.
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object receiveAndConvert(Destination destination) throws JmsException;

	/**
	 * Receive a message synchronously from the specified destination, but only
	 * wait up to a specified time for delivery. Convert the message into an
	 * object with a configured MessageConverter.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * @param destinationName the name of the destination to send this message to
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @return the message produced for the consumer or <code>null if the timeout expires.
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object receiveAndConvert(String destinationName) throws JmsException;

	/**
	 * Receive a message synchronously from the default destination, but only
	 * wait up to a specified time for delivery. Convert the message into an
	 * object with a configured MessageConverter.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * <p>This will only work with a default destination specified!
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @return the message produced for the consumer or <code>null if the timeout expires.
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object receiveSelectedAndConvert(String messageSelector) throws JmsException;

	/**
	 * Receive a message synchronously from the specified destination, but only
	 * wait up to a specified time for delivery. Convert the message into an
	 * object with a configured MessageConverter.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * @param destination the destination to receive a message from
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @return the message produced for the consumer or <code>null if the timeout expires.
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object receiveSelectedAndConvert(Destination destination, String messageSelector) throws JmsException;

	/**
	 * Receive a message synchronously from the specified destination, but only
	 * wait up to a specified time for delivery. Convert the message into an
	 * object with a configured MessageConverter.
	 * <p>This method should be used carefully, since it will block the thread
	 * until the message becomes available or until the timeout value is exceeded.
	 * @param destinationName the name of the destination to send this message to
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @return the message produced for the consumer or <code>null if the timeout expires.
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object receiveSelectedAndConvert(String destinationName, String messageSelector) throws JmsException;


	//-------------------------------------------------------------------------
	// Convenience methods for browsing messages
	//-------------------------------------------------------------------------

	/**
	 * Browse messages in the default JMS queue. The callback gives access to the JMS
	 * Session and QueueBrowser in order to browse the queue and react to the contents.
	 * @param action callback object that exposes the session/browser pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object browse(BrowserCallback action) throws JmsException;

	/**
	 * Browse messages in a JMS queue. The callback gives access to the JMS Session
	 * and QueueBrowser in order to browse the queue and react to the contents.
	 * @param queue the queue to browse
	 * @param action callback object that exposes the session/browser pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object browse(Queue queue, BrowserCallback action) throws JmsException;

	/**
	 * Browse messages in a JMS queue. The callback gives access to the JMS Session
	 * and QueueBrowser in order to browse the queue and react to the contents.
	 * @param queueName the name of the queue to browse
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @param action callback object that exposes the session/browser pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object browse(String queueName, BrowserCallback action) throws JmsException;

	/**
	 * Browse selected messages in a JMS queue. The callback gives access to the JMS
	 * Session and QueueBrowser in order to browse the queue and react to the contents.
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @param action callback object that exposes the session/browser pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object browseSelected(String messageSelector, BrowserCallback action) throws JmsException;

	/**
	 * Browse selected messages in a JMS queue. The callback gives access to the JMS
	 * Session and QueueBrowser in order to browse the queue and react to the contents.
	 * @param queue the queue to browse
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @param action callback object that exposes the session/browser pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object browseSelected(Queue queue, String messageSelector, BrowserCallback action) throws JmsException;

	/**
	 * Browse selected messages in a JMS queue. The callback gives access to the JMS
	 * Session and QueueBrowser in order to browse the queue and react to the contents.
	 * @param queueName the name of the queue to browse
	 * (to be resolved to an actual destination by a DestinationResolver)
	 * @param messageSelector the JMS message selector expression (or <code>null if none).
	 * See the JMS specification for a detailed definition of selector expressions.
	 * @param action callback object that exposes the session/browser pair
	 * @return the result object from working with the session
	 * @throws JmsException checked JMSException converted to unchecked
	 */
	Object browseSelected(String queueName, String messageSelector, BrowserCallback action) throws JmsException;

}