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