From 0d14c3bc1a4d445ea5b1e1b339c6f9a7cc11344c Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Mon, 16 Jan 2023 19:13:23 +0100 Subject: [PATCH] Polish Javadoc in spring-jms --- .../jms/annotation/EnableJms.java | 40 +++++++++---------- .../annotation/JmsBootstrapConfiguration.java | 9 +++-- .../jms/annotation/JmsListener.java | 4 +- .../jms/annotation/JmsListenerConfigurer.java | 4 +- .../jms/annotation/JmsListeners.java | 2 +- .../DefaultJmsListenerContainerFactory.java | 4 +- .../config/JmsListenerEndpointRegistrar.java | 4 +- .../springframework/jms/support/JmsUtils.java | 17 ++++---- 8 files changed, 43 insertions(+), 41 deletions(-) diff --git a/spring-jms/src/main/java/org/springframework/jms/annotation/EnableJms.java b/spring-jms/src/main/java/org/springframework/jms/annotation/EnableJms.java index 40dae6f97e7..90c04e58b7d 100644 --- a/spring-jms/src/main/java/org/springframework/jms/annotation/EnableJms.java +++ b/spring-jms/src/main/java/org/springframework/jms/annotation/EnableJms.java @@ -28,7 +28,7 @@ import org.springframework.context.annotation.Import; * Enable JMS listener annotated endpoints that are created under the cover * by a {@link org.springframework.jms.config.JmsListenerContainerFactory * JmsListenerContainerFactory}. To be used on - * {@link org.springframework.context.annotation.Configuration Configuration} + * {@link org.springframework.context.annotation.Configuration @Configuration} * classes as follows: * * 
@@ -49,14 +49,14 @@ import org.springframework.context.annotation.Import;
  *     // other @Bean definitions
  * }
* - * The {@code JmsListenerContainerFactory} is responsible to create the listener container - * responsible for a particular endpoint. Typical implementations, as the + *

The {@code JmsListenerContainerFactory} is responsible for creating the listener + * container responsible for a particular endpoint. Typical implementations, as the * {@link org.springframework.jms.config.DefaultJmsListenerContainerFactory DefaultJmsListenerContainerFactory} - * used in the sample above, provides the necessary configuration options that are supported by + * used in the sample above, provide the necessary configuration options that are supported by * the underlying {@link org.springframework.jms.listener.MessageListenerContainer MessageListenerContainer}. * - *

{@code @EnableJms} enables detection of {@link JmsListener} annotations on any - * Spring-managed bean in the container. For example, given a class {@code MyService}: + *

{@code @EnableJms} enables detection of {@link JmsListener @JmsListener} annotations + * on any Spring-managed bean in the container. For example, given a class {@code MyService}: * * 

  * package com.acme.foo;
@@ -69,14 +69,14 @@ import org.springframework.context.annotation.Import;
  *     }
  * }
* - * The container factory to use is identified by the {@link JmsListener#containerFactory() containerFactory} + *

The container factory to use is identified by the {@link JmsListener#containerFactory() containerFactory} * attribute defining the name of the {@code JmsListenerContainerFactory} bean to use. When none * is set a {@code JmsListenerContainerFactory} bean with name {@code jmsListenerContainerFactory} is * assumed to be present. * - *

the following configuration would ensure that every time a {@link jakarta.jms.Message} + *

The following configuration would ensure that every time a {@link jakarta.jms.Message} * is received on the {@link jakarta.jms.Destination} named "myQueue", {@code MyService.process()} - * is called with the content of the message: + * is invoked with the content of the message: * * 

  * @Configuration
@@ -91,7 +91,7 @@ import org.springframework.context.annotation.Import;
  *     // JMS infrastructure setup
  * }
* - * Alternatively, if {@code MyService} were annotated with {@code @Component}, the + *

Alternatively, if {@code MyService} were annotated with {@code @Component}, the * following configuration would ensure that its {@code @JmsListener} annotated * method is invoked with a matching incoming message: * @@ -102,7 +102,7 @@ import org.springframework.context.annotation.Import; * public class AppConfig { * } * - * Note that the created containers are not registered against the application context + *

Note that the created containers are not registered against the application context * but can be easily located for management purposes using the * {@link org.springframework.jms.config.JmsListenerEndpointRegistry JmsListenerEndpointRegistry}. * @@ -117,8 +117,8 @@ import org.springframework.context.annotation.Import; * // process incoming message * } * - * These features are abstracted by the {@link org.springframework.messaging.handler.annotation.support.MessageHandlerMethodFactory} - * that is responsible to build the necessary invoker to process the annotated method. By default, + *

These features are abstracted by the {@link org.springframework.messaging.handler.annotation.support.MessageHandlerMethodFactory} + * that is responsible for building the necessary invoker to process the annotated method. By default, * {@link org.springframework.messaging.handler.annotation.support.DefaultMessageHandlerMethodFactory} is used. * *

When more control is desired, a {@code @Configuration} class may implement @@ -165,8 +165,8 @@ import org.springframework.context.annotation.Import; * </beans> * } * - * It is also possible to specify a custom {@link org.springframework.jms.config.JmsListenerEndpointRegistry - * JmsListenerEndpointRegistry} in case you need more control on the way the containers + *

It is also possible to specify a custom {@link org.springframework.jms.config.JmsListenerEndpointRegistry + * JmsListenerEndpointRegistry} in case you need more control over the way the containers * are created and managed. The example below also demonstrates how to customize the * {@code JmsHandlerMethodFactory} to use with a custom {@link org.springframework.validation.Validator * Validator} so that payloads annotated with {@link org.springframework.validation.annotation.Validated @@ -201,7 +201,7 @@ import org.springframework.context.annotation.Import; * } * } * - * For reference, the example above can be compared to the following Spring XML + *

For reference, the example above can be compared to the following Spring XML * configuration: * 

  * <beans>
@@ -224,8 +224,8 @@ import org.springframework.context.annotation.Import;
  * </beans>
  *
* - * Implementing {@code JmsListenerConfigurer} also allows for fine-grained - * control over endpoints registration via the {@code JmsListenerEndpointRegistrar}. + *

Implementing {@code JmsListenerConfigurer} also allows for fine-grained + * control over endpoint registration via the {@code JmsListenerEndpointRegistrar}. * For example, the following configures an extra endpoint: * * 

@@ -253,8 +253,8 @@ import org.springframework.context.annotation.Import;
  *     // JMS infrastructure setup
  * }
* - * Note that all beans implementing {@code JmsListenerConfigurer} will be detected and - * invoked in a similar fashion. The example above can be translated in a regular bean + *

Note that all beans implementing {@code JmsListenerConfigurer} will be detected and + * invoked in a similar fashion. The example above can be translated into a regular bean * definition registered in the context in case you use the XML configuration. * * @author Stephane Nicoll diff --git a/spring-jms/src/main/java/org/springframework/jms/annotation/JmsBootstrapConfiguration.java b/spring-jms/src/main/java/org/springframework/jms/annotation/JmsBootstrapConfiguration.java index 95a7af78d61..7388e02caa6 100644 --- a/spring-jms/src/main/java/org/springframework/jms/annotation/JmsBootstrapConfiguration.java +++ b/spring-jms/src/main/java/org/springframework/jms/annotation/JmsBootstrapConfiguration.java @@ -25,11 +25,12 @@ import org.springframework.jms.config.JmsListenerEndpointRegistry; /** * {@code @Configuration} class that registers a {@link JmsListenerAnnotationBeanPostProcessor} - * bean capable of processing Spring's @{@link JmsListener} annotation. Also register - * a default {@link JmsListenerEndpointRegistry}. + * bean capable of processing Spring's {@link JmsListener @JmsListener} annotation. + * Also registers a default {@link JmsListenerEndpointRegistry}. * - *

This configuration class is automatically imported when using the @{@link EnableJms} - * annotation. See the {@link EnableJms} javadocs for complete usage details. + *

This configuration class is automatically imported when using the + * {@code @EnableJms} annotation. See the {@link EnableJms @EnableJms} + * for complete usage details. * * @author Stephane Nicoll * @since 4.1 diff --git a/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListener.java b/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListener.java index 72faf09e816..3c2226e155b 100644 --- a/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListener.java +++ b/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListener.java @@ -33,9 +33,9 @@ import org.springframework.messaging.handler.annotation.MessageMapping; * assumed to be available with a bean name of {@code jmsListenerContainerFactory} * unless an explicit default has been provided through configuration. * - *

Consider setting up a custom + *

Consider registering a custom * {@link org.springframework.jms.config.DefaultJmsListenerContainerFactory} bean. - * For production purposes, you'll typically fine-tune timeouts and recovery settings. + * For production purposes, you'll typically fine tune timeouts and recovery settings. * Most importantly, the default 'AUTO_ACKNOWLEDGE' mode does not provide reliability * guarantees, so make sure to use transacted sessions in case of reliability needs. * diff --git a/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListenerConfigurer.java b/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListenerConfigurer.java index e6680398f82..a7f960274fa 100644 --- a/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListenerConfigurer.java +++ b/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListenerConfigurer.java @@ -24,9 +24,9 @@ import org.springframework.jms.config.JmsListenerEndpointRegistrar; * used to define the default {@link org.springframework.jms.config.JmsListenerContainerFactory * JmsListenerContainerFactory} to use or for registering JMS endpoints * in a programmatic fashion as opposed to the declarative - * approach of using the @{@link JmsListener} annotation. + * approach of using the {@link JmsListener @JmsListener} annotation. * - *

See @{@link EnableJms} for detailed usage examples. + *

See {@link EnableJms @EnableJms} for detailed usage examples. * * @author Stephane Nicoll * @since 4.1 diff --git a/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListeners.java b/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListeners.java index 2e381724cf7..62880ae4aa5 100644 --- a/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListeners.java +++ b/spring-jms/src/main/java/org/springframework/jms/annotation/JmsListeners.java @@ -26,7 +26,7 @@ import java.lang.annotation.Target; * Container annotation that aggregates several {@link JmsListener} annotations. * *

Can be used natively, declaring several nested {@link JmsListener} annotations. - * Can also be used in conjunction with Java 8's support for repeatable annotations, + * Can also be used in conjunction with Java's support for repeatable annotations, * where {@link JmsListener} can simply be declared several times on the same method, * implicitly generating this container annotation. * diff --git a/spring-jms/src/main/java/org/springframework/jms/config/DefaultJmsListenerContainerFactory.java b/spring-jms/src/main/java/org/springframework/jms/config/DefaultJmsListenerContainerFactory.java index 16440c1e960..1ca0e93ca26 100644 --- a/spring-jms/src/main/java/org/springframework/jms/config/DefaultJmsListenerContainerFactory.java +++ b/spring-jms/src/main/java/org/springframework/jms/config/DefaultJmsListenerContainerFactory.java @@ -27,8 +27,8 @@ import org.springframework.util.backoff.BackOff; * A {@link JmsListenerContainerFactory} implementation to build a regular * {@link DefaultMessageListenerContainer}. * - *

This should be the default for most users and a good transition paths - * for those that are used to build such container definition manually. + *

This should be the default for most users and a good transition path + * for those who are used to building such a container definition manually. * * @author Stephane Nicoll * @since 4.1 diff --git a/spring-jms/src/main/java/org/springframework/jms/config/JmsListenerEndpointRegistrar.java b/spring-jms/src/main/java/org/springframework/jms/config/JmsListenerEndpointRegistrar.java index 32d033b1e82..a3d225b44fd 100644 --- a/spring-jms/src/main/java/org/springframework/jms/config/JmsListenerEndpointRegistrar.java +++ b/spring-jms/src/main/java/org/springframework/jms/config/JmsListenerEndpointRegistrar.java @@ -170,8 +170,8 @@ public class JmsListenerEndpointRegistrar implements BeanFactoryAware, Initializ /** * Register a new {@link JmsListenerEndpoint} alongside the * {@link JmsListenerContainerFactory} to use to create the underlying container. - *

The {@code factory} may be {@code null} if the default factory has to be - * used for that endpoint. + *

The {@code factory} may be {@code null} if the default factory should be + * used for the supplied endpoint. */ public void registerEndpoint(JmsListenerEndpoint endpoint, @Nullable JmsListenerContainerFactory factory) { Assert.notNull(endpoint, "Endpoint must not be null"); diff --git a/spring-jms/src/main/java/org/springframework/jms/support/JmsUtils.java b/spring-jms/src/main/java/org/springframework/jms/support/JmsUtils.java index a7795913cd6..b17ee2b372d 100644 --- a/spring-jms/src/main/java/org/springframework/jms/support/JmsUtils.java +++ b/spring-jms/src/main/java/org/springframework/jms/support/JmsUtils.java @@ -47,6 +47,7 @@ import org.springframework.util.Assert; * within the framework, but also useful for custom JMS access code. * * @author Juergen Hoeller + * @author Sam Brannen * @since 1.1 */ public abstract class JmsUtils { @@ -56,7 +57,7 @@ public abstract class JmsUtils { /** * Close the given JMS Connection and ignore any thrown exception. - * This is useful for typical {@code finally} blocks in manual JMS code. + *

This is useful for typical {@code finally} blocks in manual JMS code. * @param con the JMS Connection to close (may be {@code null}) */ public static void closeConnection(@Nullable Connection con) { @@ -65,7 +66,7 @@ public abstract class JmsUtils { /** * Close the given JMS Connection and ignore any thrown exception. - * This is useful for typical {@code finally} blocks in manual JMS code. + *

This is useful for typical {@code finally} blocks in manual JMS code. * @param con the JMS Connection to close (may be {@code null}) * @param stop whether to call {@code stop()} before closing */ @@ -99,7 +100,7 @@ public abstract class JmsUtils { /** * Close the given JMS Session and ignore any thrown exception. - * This is useful for typical {@code finally} blocks in manual JMS code. + *

This is useful for typical {@code finally} blocks in manual JMS code. * @param session the JMS Session to close (may be {@code null}) */ public static void closeSession(@Nullable Session session) { @@ -119,7 +120,7 @@ public abstract class JmsUtils { /** * Close the given JMS MessageProducer and ignore any thrown exception. - * This is useful for typical {@code finally} blocks in manual JMS code. + *

This is useful for typical {@code finally} blocks in manual JMS code. * @param producer the JMS MessageProducer to close (may be {@code null}) */ public static void closeMessageProducer(@Nullable MessageProducer producer) { @@ -139,7 +140,7 @@ public abstract class JmsUtils { /** * Close the given JMS MessageConsumer and ignore any thrown exception. - * This is useful for typical {@code finally} blocks in manual JMS code. + *

This is useful for typical {@code finally} blocks in manual JMS code. * @param consumer the JMS MessageConsumer to close (may be {@code null}) */ public static void closeMessageConsumer(@Nullable MessageConsumer consumer) { @@ -168,7 +169,7 @@ public abstract class JmsUtils { /** * Close the given JMS QueueBrowser and ignore any thrown exception. - * This is useful for typical {@code finally} blocks in manual JMS code. + *

This is useful for typical {@code finally} blocks in manual JMS code. * @param browser the JMS QueueBrowser to close (may be {@code null}) */ public static void closeQueueBrowser(@Nullable QueueBrowser browser) { @@ -188,7 +189,7 @@ public abstract class JmsUtils { /** * Close the given JMS QueueRequestor and ignore any thrown exception. - * This is useful for typical {@code finally} blocks in manual JMS code. + *

This is useful for typical {@code finally} blocks in manual JMS code. * @param requestor the JMS QueueRequestor to close (may be {@code null}) */ public static void closeQueueRequestor(@Nullable QueueRequestor requestor) { @@ -222,7 +223,7 @@ public abstract class JmsUtils { } /** - * Rollback the Session if not within a JTA transaction. + * Roll back the Session if not within a JTA transaction. * @param session the JMS Session to rollback * @throws JMSException if committing failed */