Consistent nullability and exception declarations

Closes gh-35159

Author: jhoeller

spring-jms/src/main/java/org/springframework/jms/core/JmsMessageOperations.java

@@ -30,8 +30,12 @@
 
 /**
  * A specialization of {@link MessageSendingOperations}, {@link MessageReceivingOperations}
- * and {@link MessageRequestReplyOperations} for JMS related operations that allow to specify
- * a destination name rather than the actual {@link jakarta.jms.Destination}.
+ * and {@link MessageRequestReplyOperations} for JMS related operations that allow to
+ * specify a destination name rather than the actual {@link jakarta.jms.Destination}.
+ *
+ * <p>Note: Operations in this interface throw {@link MessagingException} instead of
+ * the JMS-specific {@link org.springframework.jms.JmsException}, aligning with the
+ * {@code spring-messaging} module and its other client operation handles.
  *
  * @author Stephane Nicoll
  * @since 4.1
@@ -68,30 +72,30 @@ public interface JmsMessageOperations extends MessageSendingOperations<Destinati
 	 * @param payload the Object to use as payload
 	 * @param headers the headers for the message to send
 	 */
-	void convertAndSend(String destinationName, Object payload, Map<String, Object> headers)
+	void convertAndSend(String destinationName, Object payload, @Nullable Map<String, Object> headers)
 			throws MessagingException;
 
 	/**
 	 * Convert the given Object to serialized form, possibly using a
 	 * {@link org.springframework.messaging.converter.MessageConverter},
-	 * wrap it as a message, apply the given post processor, and send
+	 * wrap it as a message, apply the given post-processor, and send
 	 * the resulting message to the given destination.
 	 * @param destinationName the name of the target destination
 	 * @param payload the Object to use as payload
-	 * @param postProcessor the post processor to apply to the message
+	 * @param postProcessor the post-processor to apply to the message
 	 */
-	void convertAndSend(String destinationName, Object payload, MessagePostProcessor postProcessor)
+	void convertAndSend(String destinationName, Object payload, @Nullable MessagePostProcessor postProcessor)
 			throws MessagingException;
 
 	/**
 	 * Convert the given Object to serialized form, possibly using a
 	 * {@link org.springframework.messaging.converter.MessageConverter},
-	 * wrap it as a message with the given headers, apply the given post processor,
+	 * wrap it as a message with the given headers, apply the given post-processor,
 	 * and send the resulting message to the given destination.
 	 * @param destinationName the name of the target destination
 	 * @param payload the Object to use as payload
 	 * @param headers the headers for the message to send
-	 * @param postProcessor the post processor to apply to the message
+	 * @param postProcessor the post-processor to apply to the message
 	 */
 	void convertAndSend(String destinationName, Object payload, @Nullable Map<String, Object> headers,
 			@Nullable MessagePostProcessor postProcessor) throws MessagingException;
@@ -159,13 +163,13 @@ <T> T convertSendAndReceive(String destinationName, Object request, @Nullable Ma
 	/**
 	 * Convert the given request Object to serialized form, possibly using a
 	 * {@link org.springframework.messaging.converter.MessageConverter},
-	 * apply the given post processor and send the resulting {@link Message} to the
+	 * apply the given post-processor and send the resulting {@link Message} to the
 	 * given destination, receive the reply and convert its body of the given
 	 * target class.
 	 * @param destinationName the name of the target destination
 	 * @param request payload for the request message to send
 	 * @param targetClass the target type to convert the payload of the reply to
-	 * @param requestPostProcessor post process to apply to the request message
+	 * @param requestPostProcessor post-process to apply to the request message
 	 * @return the payload of the reply message, possibly {@code null} if the message
 	 * could not be received, for example due to a timeout
 	 */
@@ -176,13 +180,13 @@ <T> T convertSendAndReceive(String destinationName, Object request, Class<T> tar
 	/**
 	 * Convert the given request Object to serialized form, possibly using a
 	 * {@link org.springframework.messaging.converter.MessageConverter},
-	 * wrap it as a message with the given headers, apply the given post processor
+	 * wrap it as a message with the given headers, apply the given post-processor
 	 * and send the resulting {@link Message} to the specified destination, receive
 	 * the reply and convert its body of the given target class.
 	 * @param destinationName the name of the target destination
 	 * @param request payload for the request message to send
 	 * @param targetClass the target type to convert the payload of the reply to
-	 * @param requestPostProcessor post process to apply to the request message
+	 * @param requestPostProcessor post-process to apply to the request message
 	 * @return the payload of the reply message, possibly {@code null} if the message
 	 * could not be received, for example due to a timeout
 	 */

spring-messaging/src/main/java/org/springframework/messaging/core/AbstractDestinationResolvingMessagingTemplate.java

@@ -20,6 +20,7 @@
 
 import org.springframework.lang.Nullable;
 import org.springframework.messaging.Message;
+import org.springframework.messaging.MessagingException;
 import org.springframework.util.Assert;
 
 /**
@@ -65,74 +66,82 @@ public DestinationResolver<D> getDestinationResolver() {
 		return this.destinationResolver;
 	}
 
+	protected final D resolveDestination(String destinationName) throws DestinationResolutionException {
+		Assert.state(this.destinationResolver != null,
+				"DestinationResolver is required to resolve destination names");
+		return this.destinationResolver.resolveDestination(destinationName);
+	}
+
 
 	@Override
-	public void send(String destinationName, Message<?> message) {
+	public void send(String destinationName, Message<?> message) throws MessagingException {
 		D destination = resolveDestination(destinationName);
 		doSend(destination, message);
 	}
 
-	protected final D resolveDestination(String destinationName) {
-
-		Assert.state(this.destinationResolver != null, "DestinationResolver is required to resolve destination names");
-		return this.destinationResolver.resolveDestination(destinationName);
-	}
-
 	@Override
-	public <T> void convertAndSend(String destinationName, T payload) {
+	public <T> void convertAndSend(String destinationName, T payload) throws MessagingException {
 		convertAndSend(destinationName, payload, null, null);
 	}
 
 	@Override
-	public <T> void convertAndSend(String destinationName, T payload, @Nullable Map<String, Object> headers) {
+	public <T> void convertAndSend(String destinationName, T payload, @Nullable Map<String, Object> headers)
+			throws MessagingException {
+
 		convertAndSend(destinationName, payload, headers, null);
 	}
 
 	@Override
-	public <T> void convertAndSend(String destinationName, T payload, @Nullable MessagePostProcessor postProcessor) {
+	public <T> void convertAndSend(String destinationName, T payload, @Nullable MessagePostProcessor postProcessor)
+			throws MessagingException {
+
 		convertAndSend(destinationName, payload, null, postProcessor);
 	}
 
 	@Override
-	public <T> void convertAndSend(String destinationName, T payload,
-			@Nullable Map<String, Object> headers, @Nullable MessagePostProcessor postProcessor) {
+	public <T> void convertAndSend(String destinationName, T payload, @Nullable Map<String, Object> headers,
+			@Nullable MessagePostProcessor postProcessor) throws MessagingException {
 
 		D destination = resolveDestination(destinationName);
 		super.convertAndSend(destination, payload, headers, postProcessor);
 	}
 
 	@Override
 	@Nullable
-	public Message<?> receive(String destinationName) {
+	public Message<?> receive(String destinationName) throws MessagingException {
 		D destination = resolveDestination(destinationName);
 		return super.receive(destination);
 	}
 
 	@Override
 	@Nullable
-	public <T> T receiveAndConvert(String destinationName, Class<T> targetClass) {
+	public <T> T receiveAndConvert(String destinationName, Class<T> targetClass) throws MessagingException {
 		D destination = resolveDestination(destinationName);
 		return super.receiveAndConvert(destination, targetClass);
 	}
 
 	@Override
 	@Nullable
-	public Message<?> sendAndReceive(String destinationName, Message<?> requestMessage) {
+	public Message<?> sendAndReceive(String destinationName, Message<?> requestMessage)
+			throws MessagingException {
+
 		D destination = resolveDestination(destinationName);
 		return super.sendAndReceive(destination, requestMessage);
 	}
 
 	@Override
 	@Nullable
-	public <T> T convertSendAndReceive(String destinationName, Object request, Class<T> targetClass) {
+	public <T> T convertSendAndReceive(String destinationName, Object request, Class<T> targetClass)
+			throws MessagingException {
+
 		D destination = resolveDestination(destinationName);
 		return super.convertSendAndReceive(destination, request, targetClass);
 	}
 
 	@Override
 	@Nullable
 	public <T> T convertSendAndReceive(String destinationName, Object request,
-			@Nullable Map<String, Object> headers, Class<T> targetClass) {
+			@Nullable Map<String, Object> headers, Class<T> targetClass) throws MessagingException {
 
 		D destination = resolveDestination(destinationName);
 		return super.convertSendAndReceive(destination, request, headers, targetClass);
@@ -141,7 +150,7 @@ public <T> T convertSendAndReceive(String destinationName, Object request,
 	@Override
 	@Nullable
 	public <T> T convertSendAndReceive(String destinationName, Object request, Class<T> targetClass,
-			@Nullable MessagePostProcessor postProcessor) {
+			@Nullable MessagePostProcessor postProcessor) throws MessagingException {
 
 		D destination = resolveDestination(destinationName);
 		return super.convertSendAndReceive(destination, request, targetClass, postProcessor);
@@ -151,7 +160,7 @@ public <T> T convertSendAndReceive(String destinationName, Object request, Class
 	@Nullable
 	public <T> T convertSendAndReceive(String destinationName, Object request,
 			@Nullable Map<String, Object> headers, Class<T> targetClass,
-			@Nullable MessagePostProcessor postProcessor) {
+			@Nullable MessagePostProcessor postProcessor) throws MessagingException {
 
 		D destination = resolveDestination(destinationName);
 		return super.convertSendAndReceive(destination, request, headers, targetClass, postProcessor);

spring-messaging/src/main/java/org/springframework/messaging/core/AbstractMessageReceivingTemplate.java

@@ -18,6 +18,7 @@
 
 import org.springframework.lang.Nullable;
 import org.springframework.messaging.Message;
+import org.springframework.messaging.MessagingException;
 import org.springframework.messaging.converter.MessageConversionException;
 import org.springframework.messaging.converter.MessageConverter;
 
@@ -36,35 +37,25 @@ public abstract class AbstractMessageReceivingTemplate<D> extends AbstractMessag
 
 	@Override
 	@Nullable
-	public Message<?> receive() {
+	public Message<?> receive() throws MessagingException {
 		return doReceive(getRequiredDefaultDestination());
 	}
 
 	@Override
 	@Nullable
-	public Message<?> receive(D destination) {
+	public Message<?> receive(D destination) throws MessagingException {
 		return doReceive(destination);
 	}
 
-	/**
-	 * Actually receive a message from the given destination.
-	 * @param destination the target destination
-	 * @return the received message, possibly {@code null} if the message could not
-	 * be received, for example due to a timeout
-	 */
-	@Nullable
-	protected abstract Message<?> doReceive(D destination);
-
-
 	@Override
 	@Nullable
-	public <T> T receiveAndConvert(Class<T> targetClass) {
+	public <T> T receiveAndConvert(Class<T> targetClass) throws MessagingException {
 		return receiveAndConvert(getRequiredDefaultDestination(), targetClass);
 	}
 
 	@Override
 	@Nullable
-	public <T> T receiveAndConvert(D destination, Class<T> targetClass) {
+	public <T> T receiveAndConvert(D destination, Class<T> targetClass) throws MessagingException {
 		Message<?> message = doReceive(destination);
 		if (message != null) {
 			return doConvert(message, targetClass);
@@ -92,4 +83,13 @@ protected <T> T doConvert(Message<?> message, Class<T> targetClass) {
 		return value;
 	}
 
+	/**
+	 * Actually receive a message from the given destination.
+	 * @param destination the target destination
+	 * @return the received message, possibly {@code null} if the
+	 * message could not be received, for example due to a timeout
+	 */
+	@Nullable
+	protected abstract Message<?> doReceive(D destination);
+
 }

spring-messaging/src/main/java/org/springframework/messaging/core/AbstractMessageSendingTemplate.java

@@ -109,9 +109,6 @@ public void send(D destination, Message<?> message) {
 		doSend(destination, message);
 	}
 
-	protected abstract void doSend(D destination, Message<?> message);
-
-
 	@Override
 	public void convertAndSend(Object payload) throws MessagingException {
 		convertAndSend(payload, null);
@@ -151,13 +148,14 @@ public void convertAndSend(D destination, Object payload, @Nullable Map<String,
 		send(destination, message);
 	}
 
+
 	/**
 	 * Convert the given Object to serialized form, possibly using a
 	 * {@link MessageConverter}, wrap it as a message with the given
-	 * headers and apply the given post processor.
+	 * headers and apply the given post-processor.
 	 * @param payload the Object to use as payload
 	 * @param headers the headers for the message to send
-	 * @param postProcessor the post processor to apply to the message
+	 * @param postProcessor the post-processor to apply to the message
 	 * @return the converted message
 	 */
 	protected Message<?> doConvert(Object payload, @Nullable Map<String, Object> headers,
@@ -199,4 +197,11 @@ protected Map<String, Object> processHeadersToSend(@Nullable Map<String, Object>
 		return headers;
 	}
 
+	/**
+	 * Actually send the given message to the given destination.
+	 * @param destination the target destination
+	 * @param message the message to send
+	 */
+	protected abstract void doSend(D destination, Message<?> message);
+
 }