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 java.util.Map;
020import javax.jms.Destination;
021
022import org.springframework.messaging.Message;
023import org.springframework.messaging.MessagingException;
024import org.springframework.messaging.core.MessagePostProcessor;
025import org.springframework.messaging.core.MessageReceivingOperations;
026import org.springframework.messaging.core.MessageRequestReplyOperations;
027import org.springframework.messaging.core.MessageSendingOperations;
028
029/**
030 * A specialization of {@link MessageSendingOperations}, {@link MessageReceivingOperations}
031 * and {@link MessageRequestReplyOperations} for JMS related operations that allow to specify
032 * a destination name rather than the actual {@link javax.jms.Destination}
033 *
034 * @author Stephane Nicoll
035 * @since 4.1
036 * @see org.springframework.jms.core.JmsTemplate
037 * @see org.springframework.messaging.core.MessageSendingOperations
038 * @see org.springframework.messaging.core.MessageReceivingOperations
039 * @see org.springframework.messaging.core.MessageRequestReplyOperations
040 */
041public interface JmsMessageOperations extends MessageSendingOperations<Destination>,
042                MessageReceivingOperations<Destination>, MessageRequestReplyOperations<Destination> {
043
044        /**
045         * Send a message to the given destination.
046         * @param destinationName the name of the target destination
047         * @param message the message to send
048         */
049        void send(String destinationName, Message<?> message) throws MessagingException;
050
051        /**
052         * Convert the given Object to serialized form, possibly using a
053         * {@link org.springframework.messaging.converter.MessageConverter},
054         * wrap it as a message and send it to the given destination.
055         * @param destinationName the name of the target destination
056         * @param payload the Object to use as payload
057         */
058        void convertAndSend(String destinationName, Object payload) throws MessagingException;
059
060        /**
061         * Convert the given Object to serialized form, possibly using a
062         * {@link org.springframework.messaging.converter.MessageConverter},
063         * wrap it as a message with the given headers and send it to
064         * the given destination.
065         * @param destinationName the name of the target destination
066         * @param payload the Object to use as payload
067         * @param headers headers for the message to send
068         */
069        void convertAndSend(String destinationName, Object payload, Map<String, Object> headers)
070                        throws MessagingException;
071
072        /**
073         * Convert the given Object to serialized form, possibly using a
074         * {@link org.springframework.messaging.converter.MessageConverter},
075         * wrap it as a message, apply the given post processor, and send
076         * the resulting message to the given destination.
077         * @param destinationName the name of the target destination
078         * @param payload the Object to use as payload
079         * @param postProcessor the post processor to apply to the message
080         */
081        void convertAndSend(String destinationName, Object payload, MessagePostProcessor postProcessor)
082                        throws MessagingException;
083
084        /**
085         * Convert the given Object to serialized form, possibly using a
086         * {@link org.springframework.messaging.converter.MessageConverter},
087         * wrap it as a message with the given headers, apply the given post processor,
088         * and send the resulting message to the given destination.
089         * @param destinationName the name of the target destination
090         * @param payload the Object to use as payload
091         * @param headers headers for the message to send
092         * @param postProcessor the post processor to apply to the message
093         */
094        void convertAndSend(String destinationName, Object payload, Map<String,
095                        Object> headers, MessagePostProcessor postProcessor) throws MessagingException;
096
097        /**
098         * Receive a message from the given destination.
099         * @param destinationName the name of the target destination
100         * @return the received message, possibly {@code null} if the message could not
101         * be received, for example due to a timeout
102         */
103        Message<?> receive(String destinationName) throws MessagingException;
104
105        /**
106         * Receive a message from the given destination and convert its payload to the
107         * specified target class.
108         * @param destinationName the name of the target destination
109         * @param targetClass the target class to convert the payload to
110         * @return the converted payload of the reply message, possibly {@code null} if
111         * the message could not be received, for example due to a timeout
112         */
113        <T> T receiveAndConvert(String destinationName, Class<T> targetClass) throws MessagingException;
114
115        /**
116         * Send a request message and receive the reply from the given destination.
117         * @param destinationName the name of the target destination
118         * @param requestMessage the message to send
119         * @return the reply, possibly {@code null} if the message could not be received,
120         * for example due to a timeout
121         */
122        Message<?> sendAndReceive(String destinationName, Message<?> requestMessage) throws MessagingException;
123
124        /**
125         * Convert the given request Object to serialized form, possibly using a
126         * {@link org.springframework.messaging.converter.MessageConverter}, send
127         * it as a {@link Message} to the given destination, receive the reply and convert
128         * its body of the specified target class.
129         * @param destinationName the name of the target destination
130         * @param request payload for the request message to send
131         * @param targetClass the target type to convert the payload of the reply to
132         * @return the payload of the reply message, possibly {@code null} if the message
133         * could not be received, for example due to a timeout
134         */
135        <T> T convertSendAndReceive(String destinationName, Object request, Class<T> targetClass) throws MessagingException;
136
137        /**
138         * Convert the given request Object to serialized form, possibly using a
139         * {@link org.springframework.messaging.converter.MessageConverter}, send
140         * it as a {@link Message} with the given headers, to the specified destination,
141         * receive the reply and convert its body of the specified target class.
142         * @param destinationName the name of the target destination
143         * @param request payload for the request message to send
144         * @param headers headers for the request message to send
145         * @param targetClass the target type to convert the payload of the reply to
146         * @return the payload of the reply message, possibly {@code null} if the message
147         * could not be received, for example due to a timeout
148         */
149        <T> T convertSendAndReceive(String destinationName, Object request, Map<String, Object> headers, Class<T> targetClass)
150                        throws MessagingException;
151
152        /**
153         * Convert the given request Object to serialized form, possibly using a
154         * {@link org.springframework.messaging.converter.MessageConverter},
155         * apply the given post processor and send the resulting {@link Message} to the
156         * given destination, receive the reply and convert its body of the given
157         * target class.
158         * @param destinationName the name of the target destination
159         * @param request payload for the request message to send
160         * @param targetClass the target type to convert the payload of the reply to
161         * @param requestPostProcessor post process to apply to the request message
162         * @return the payload of the reply message, possibly {@code null} if the message
163         * could not be received, for example due to a timeout
164         */
165        <T> T convertSendAndReceive(String destinationName, Object request, Class<T> targetClass,
166                        MessagePostProcessor requestPostProcessor) throws MessagingException;
167
168        /**
169         * Convert the given request Object to serialized form, possibly using a
170         * {@link org.springframework.messaging.converter.MessageConverter},
171         * wrap it as a message with the given headers, apply the given post processor
172         * and send the resulting {@link Message} to the specified destination, receive
173         * the reply and convert its body of the given target class.
174         * @param destinationName the name of the target destination
175         * @param request payload for the request message to send
176         * @param targetClass the target type to convert the payload of the reply to
177         * @param requestPostProcessor post process to apply to the request message
178         * @return the payload of the reply message, possibly {@code null} if the message
179         * could not be received, for example due to a timeout
180         */
181        <T> T convertSendAndReceive(String destinationName, Object request, Map<String, Object> headers,
182                        Class<T> targetClass, MessagePostProcessor requestPostProcessor) throws MessagingException;
183
184}