From dd92eac3ad6facfd41f80781f1e832aec6e4b6c9 Mon Sep 17 00:00:00 2001 From: Sam Brannen <104798+sbrannen@users.noreply.github.com> Date: Tue, 19 Nov 2024 13:17:42 +0100 Subject: [PATCH] Refer to message "receipt" instead of "reception" --- .../modules/ROOT/pages/integration/jms.adoc | 2 +- .../ROOT/pages/integration/jms/receiving.adoc | 8 ++++---- .../modules/ROOT/pages/integration/jms/using.adoc | 14 ++++++++------ .../ROOT/pages/integration/observability.adoc | 2 +- .../context/event/test/EventCollector.java | 4 ++-- .../listener/AbstractMessageListenerContainer.java | 4 ++-- .../AbstractPollingMessageListenerContainer.java | 8 ++++---- .../listener/DefaultMessageListenerContainer.java | 8 ++++---- .../listener/SimpleMessageListenerContainer.java | 2 +- .../springframework/jms/support/JmsHeaders.java | 4 ++-- .../springframework/messaging/PollableChannel.java | 6 +++--- 11 files changed, 32 insertions(+), 30 deletions(-) diff --git a/framework-docs/modules/ROOT/pages/integration/jms.adoc b/framework-docs/modules/ROOT/pages/integration/jms.adoc index ee207db0e088..d3ca79413b48 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms.adoc @@ -6,7 +6,7 @@ the same way as Spring's integration does for the JDBC API. JMS can be roughly divided into two areas of functionality, namely the production and consumption of messages. The `JmsTemplate` class is used for message production and -synchronous message reception. For asynchronous reception similar to Jakarta EE's +synchronous message receipt. For asynchronous receipt similar to Jakarta EE's message-driven bean style, Spring provides a number of message-listener containers that you can use to create Message-Driven POJOs (MDPs). Spring also provides a declarative way to create message listeners. diff --git a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc index fb9cb9aa1e7f..ddd9c43d2e86 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/receiving.adoc @@ -5,7 +5,7 @@ This describes how to receive messages with JMS in Spring. [[jms-receiving-sync]] -== Synchronous Reception +== Synchronous Receipt While JMS is typically associated with asynchronous processing, you can consume messages synchronously. The overloaded `receive(..)` methods provide this @@ -16,7 +16,7 @@ the receiver should wait before giving up waiting for a message. [[jms-receiving-async]] -== Asynchronous reception: Message-Driven POJOs +== Asynchronous Receipt: Message-Driven POJOs NOTE: Spring also supports annotated-listener endpoints through the use of the `@JmsListener` annotation and provides open infrastructure to register endpoints programmatically. @@ -154,7 +154,7 @@ listener container. You can activate local resource transactions through the `sessionTransacted` flag on the listener container definition. Each message listener invocation then operates -within an active JMS transaction, with message reception rolled back in case of listener +within an active JMS transaction, with message receipt rolled back in case of listener execution failure. Sending a response message (through `SessionAwareMessageListener`) is part of the same local transaction, but any other resource operations (such as database access) operate independently. This usually requires duplicate message @@ -173,7 +173,7 @@ To configure a message listener container for XA transaction participation, you to configure a `JtaTransactionManager` (which, by default, delegates to the Jakarta EE server's transaction subsystem). Note that the underlying JMS `ConnectionFactory` needs to be XA-capable and properly registered with your JTA transaction coordinator. (Check your -Jakarta EE server's configuration of JNDI resources.) This lets message reception as well +Jakarta EE server's configuration of JNDI resources.) This lets message receipt as well as (for example) database access be part of the same transaction (with unified commit semantics, at the expense of XA transaction log overhead). diff --git a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc index 027098cbc205..01babeefac6e 100644 --- a/framework-docs/modules/ROOT/pages/integration/jms/using.adoc +++ b/framework-docs/modules/ROOT/pages/integration/jms/using.adoc @@ -167,13 +167,15 @@ operations that do not refer to a specific destination. One of the most common uses of JMS messages in the EJB world is to drive message-driven beans (MDBs). Spring offers a solution to create message-driven POJOs (MDPs) in a way -that does not tie a user to an EJB container. (See xref:integration/jms/receiving.adoc#jms-receiving-async[Asynchronous reception: Message-Driven POJOs] for detailed -coverage of Spring's MDP support.) Since Spring Framework 4.1, endpoint methods can be -annotated with `@JmsListener` -- see xref:integration/jms/annotated.adoc[Annotation-driven Listener Endpoints] for more details. +that does not tie a user to an EJB container. (See +xref:integration/jms/receiving.adoc#jms-receiving-async[Asynchronous Receipt: Message-Driven POJOs] +for detailed coverage of Spring's MDP support.) Endpoint methods can be annotated with +`@JmsListener` -- see xref:integration/jms/annotated.adoc[Annotation-driven Listener Endpoints] +for more details. A message listener container is used to receive messages from a JMS message queue and drive the `MessageListener` that is injected into it. The listener container is -responsible for all threading of message reception and dispatches into the listener for +responsible for all threading of message receipt and dispatches into the listener for processing. A message listener container is the intermediary between an MDP and a messaging provider and takes care of registering to receive messages, participating in transactions, resource acquisition and release, exception conversion, and so on. This @@ -227,7 +229,7 @@ the JMS provider, advanced functionality (such as participation in externally ma transactions), and compatibility with Jakarta EE environments. You can customize the cache level of the container. Note that, when no caching is enabled, -a new connection and a new session is created for each message reception. Combining this +a new connection and a new session is created for each message receipt. Combining this with a non-durable subscription with high loads may lead to message loss. Make sure to use a proper cache level in such a case. @@ -246,7 +248,7 @@ in the form of a business entity existence check or a protocol table check. Any such arrangements are significantly more efficient than the alternative: wrapping your entire processing with an XA transaction (through configuring your `DefaultMessageListenerContainer` with an `JtaTransactionManager`) to cover the -reception of the JMS message as well as the execution of the business logic in your +receipt of the JMS message as well as the execution of the business logic in your message listener (including database operations, etc.). IMPORTANT: The default `AUTO_ACKNOWLEDGE` mode does not provide proper reliability guarantees. diff --git a/framework-docs/modules/ROOT/pages/integration/observability.adoc b/framework-docs/modules/ROOT/pages/integration/observability.adoc index 946aba1e3765..85af67d5d052 100644 --- a/framework-docs/modules/ROOT/pages/integration/observability.adoc +++ b/framework-docs/modules/ROOT/pages/integration/observability.adoc @@ -126,7 +126,7 @@ This instrumentation will create 2 types of observations: * `"jms.message.publish"` when a JMS message is sent to the broker, typically with `JmsTemplate`. * `"jms.message.process"` when a JMS message is processed by the application, typically with a `MessageListener` or a `@JmsListener` annotated method. -NOTE: Currently there is no instrumentation for `"jms.message.receive"` observations as there is little value in measuring the time spent waiting for the reception of a message. +NOTE: Currently there is no instrumentation for `"jms.message.receive"` observations as there is little value in measuring the time spent waiting for the receipt of a message. Such an integration would typically instrument `MessageConsumer#receive` method calls. But once those return, the processing time is not measured and the trace scope cannot be propagated to the application. By default, both observations share the same set of possible `KeyValues`: diff --git a/spring-context/src/test/java/org/springframework/context/event/test/EventCollector.java b/spring-context/src/test/java/org/springframework/context/event/test/EventCollector.java index 4e7da9e2c533..afe046b08514 100644 --- a/spring-context/src/test/java/org/springframework/context/event/test/EventCollector.java +++ b/spring-context/src/test/java/org/springframework/context/event/test/EventCollector.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2023 the original author or authors. + * Copyright 2002-2024 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. @@ -47,7 +47,7 @@ public void addEvent(Identifiable listener, Object event) { /** * Return the events that the specified listener has received. The list of events - * is ordered according to their reception order. + * is ordered according to the order in which they were received. */ public List getEvents(Identifiable listener) { return this.content.get(listener.getId()); diff --git a/spring-jms/src/main/java/org/springframework/jms/listener/AbstractMessageListenerContainer.java b/spring-jms/src/main/java/org/springframework/jms/listener/AbstractMessageListenerContainer.java index 77addbd76917..f803fc3aa11e 100644 --- a/spring-jms/src/main/java/org/springframework/jms/listener/AbstractMessageListenerContainer.java +++ b/spring-jms/src/main/java/org/springframework/jms/listener/AbstractMessageListenerContainer.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2023 the original author or authors. + * Copyright 2002-2024 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. @@ -102,7 +102,7 @@ * (i.e. after your business logic executed but before the JMS part got committed), * so duplicate message detection is just there to cover a corner case. *
  • Or wrap your entire processing with an XA transaction, covering the - * reception of the JMS message as well as the execution of the business logic in + * receipt of the JMS message as well as the execution of the business logic in * your message listener (including database operations etc). This is only * supported by {@link DefaultMessageListenerContainer}, through specifying * an external "transactionManager" (typically a diff --git a/spring-jms/src/main/java/org/springframework/jms/listener/AbstractPollingMessageListenerContainer.java b/spring-jms/src/main/java/org/springframework/jms/listener/AbstractPollingMessageListenerContainer.java index 46d3db64ee10..71c4ad360de3 100644 --- a/spring-jms/src/main/java/org/springframework/jms/listener/AbstractPollingMessageListenerContainer.java +++ b/spring-jms/src/main/java/org/springframework/jms/listener/AbstractPollingMessageListenerContainer.java @@ -45,7 +45,7 @@ * *

    This listener container variant is built for repeated polling attempts, * each invoking the {@link #receiveAndExecute} method. The MessageConsumer used - * may be reobtained fo reach attempt or cached in between attempts; this is up + * may be reobtained for each attempt or cached in between attempts; this is up * to the concrete implementation. The receive timeout for each attempt can be * configured through the {@link #setReceiveTimeout "receiveTimeout"} property. * @@ -56,7 +56,7 @@ * full control over the listening process, allowing for custom scaling and throttling * and of concurrent message processing (which is up to concrete subclasses). * - *

    Message reception and listener execution can automatically be wrapped + *

    Message receipt and listener execution can automatically be wrapped * in transactions through passing a Spring * {@link org.springframework.transaction.PlatformTransactionManager} into the * {@link #setTransactionManager "transactionManager"} property. This will usually @@ -105,7 +105,7 @@ public void setSessionTransacted(boolean sessionTransacted) { /** * Specify the Spring {@link org.springframework.transaction.PlatformTransactionManager} - * to use for transactional wrapping of message reception plus listener execution. + * to use for transactional wrapping of message receipt plus listener execution. *

    Default is none, not performing any transactional wrapping. * If specified, this will usually be a Spring * {@link org.springframework.transaction.jta.JtaTransactionManager} or one @@ -131,7 +131,7 @@ public void setTransactionManager(@Nullable PlatformTransactionManager transacti /** * Return the Spring PlatformTransactionManager to use for transactional - * wrapping of message reception plus listener execution. + * wrapping of message receipt plus listener execution. */ @Nullable protected final PlatformTransactionManager getTransactionManager() { diff --git a/spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java b/spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java index 5200e54e9c5d..91975cb88b71 100644 --- a/spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java +++ b/spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java @@ -47,7 +47,7 @@ /** * Message listener container variant that uses plain JMS client APIs, specifically * a loop of {@code MessageConsumer.receive()} calls that also allow for - * transactional reception of messages (registering them with XA transactions). + * transactional receipt of messages (registering them with XA transactions). * Designed to work in a native JMS environment as well as in a Jakarta EE environment, * with only minimal differences in configuration. * @@ -70,7 +70,7 @@ * {@code MessageConsumer} (only refreshed in case of failure), using the JMS provider's * resources as efficiently as possible. * - *

    Message reception and listener execution can automatically be wrapped + *

    Message receipt and listener execution can automatically be wrapped * in transactions by passing a Spring * {@link org.springframework.transaction.PlatformTransactionManager} into the * {@link #setTransactionManager "transactionManager"} property. This will usually @@ -474,7 +474,7 @@ public final int getMaxConcurrentConsumers() { /** * Specify the maximum number of messages to process in one task. - * More concretely, this limits the number of message reception attempts + * More concretely, this limits the number of message receipt attempts * per task, which includes receive iterations that did not actually * pick up a message until they hit their timeout (see the * {@link #setReceiveTimeout "receiveTimeout"} property). @@ -562,7 +562,7 @@ public final int getIdleConsumerLimit() { * The minimum number of consumers * (see {@link #setConcurrentConsumers "concurrentConsumers"}) * will be kept around until shutdown in any case. - *

    Within each task execution, a number of message reception attempts + *

    Within each task execution, a number of message receipt attempts * (according to the "maxMessagesPerTask" setting) will each wait for an incoming * message (according to the "receiveTimeout" setting). If all of those receive * attempts in a given task return without a message, the task is considered diff --git a/spring-jms/src/main/java/org/springframework/jms/listener/SimpleMessageListenerContainer.java b/spring-jms/src/main/java/org/springframework/jms/listener/SimpleMessageListenerContainer.java index 08881612ab71..e445eb34e1c4 100644 --- a/spring-jms/src/main/java/org/springframework/jms/listener/SimpleMessageListenerContainer.java +++ b/spring-jms/src/main/java/org/springframework/jms/listener/SimpleMessageListenerContainer.java @@ -56,7 +56,7 @@ * *

    For a different style of MessageListener handling, through looped * {@code MessageConsumer.receive()} calls that also allow for - * transactional reception of messages (registering them with XA transactions), + * transactional receipt of messages (registering them with XA transactions), * see {@link DefaultMessageListenerContainer}. * * @author Juergen Hoeller diff --git a/spring-jms/src/main/java/org/springframework/jms/support/JmsHeaders.java b/spring-jms/src/main/java/org/springframework/jms/support/JmsHeaders.java index a80ed7554273..c45264dd92b9 100644 --- a/spring-jms/src/main/java/org/springframework/jms/support/JmsHeaders.java +++ b/spring-jms/src/main/java/org/springframework/jms/support/JmsHeaders.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2017 the original author or authors. + * Copyright 2002-2024 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. @@ -89,7 +89,7 @@ public interface JmsHeaders { /** * Specify if the message was resent. This occurs when a message - * consumer fails to acknowledge the message reception. + * consumer fails to acknowledge receipt of the message. *

    Read-only value. * @see jakarta.jms.Message#getJMSRedelivered() */ diff --git a/spring-messaging/src/main/java/org/springframework/messaging/PollableChannel.java b/spring-messaging/src/main/java/org/springframework/messaging/PollableChannel.java index 78f1cfc10708..1dc0ba778074 100644 --- a/spring-messaging/src/main/java/org/springframework/messaging/PollableChannel.java +++ b/spring-messaging/src/main/java/org/springframework/messaging/PollableChannel.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 the original author or authors. + * Copyright 2002-2024 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. @@ -36,9 +36,9 @@ public interface PollableChannel extends MessageChannel { /** * Receive a message from this channel, blocking until either a message is available * or the specified timeout period elapses. - * @param timeout the timeout in milliseconds or {@link MessageChannel#INDEFINITE_TIMEOUT}. + * @param timeout the timeout in milliseconds or {@link MessageChannel#INDEFINITE_TIMEOUT} * @return the next available {@link Message} or {@code null} if the specified timeout - * period elapses or the message reception is interrupted + * period elapses or the message receipt is interrupted */ @Nullable Message receive(long timeout);