GH-3506: No array for poller messaging anns attr

Fixes #3506

Revise the `@Poller` usage in the messaging annotations from an array value
to a single entry with a `ValueConstants.DEFAULT_NONE` for default value

Code review feedback

- Make annotation utils check for NONE more generic
- Move docs to whats-new.adoc
- Polish javadoc

Code review feedback
- simplify docs
- simplify isProvided checks

Author: onobc

spring-integration-core/src/main/java/org/springframework/integration/annotation/Aggregator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -34,6 +34,7 @@
  * @author Marius Bogoevici
  * @author Oleg Zhurakousky
  * @author Artem Bilan
+ * @author Chris Bono
  */
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -105,10 +106,9 @@
 	/**
 	 * @return the {@link Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
 	 * Mutually exclusive with {@link #reactive()}.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 	/**
 	 * @return the {@link Reactive} marker for a consumer endpoint.

spring-integration-core/src/main/java/org/springframework/integration/annotation/BridgeFrom.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2021 the original author or authors.
+ * Copyright 2014-2022 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.
@@ -38,6 +38,7 @@
  * is used as the {@code outputChannel} of the {@link org.springframework.integration.handler.BridgeHandler}.
  *
  * @author Artem Bilan
+ * @author Chris Bono
  *
  * @since 4.0
  */
@@ -70,10 +71,9 @@
 	/**
 	 * @return the {@link Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
 	 * Mutually exclusive with {@link #reactive()}.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 	/**
 	 * @return the {@link Reactive} marker for a consumer endpoint.

spring-integration-core/src/main/java/org/springframework/integration/annotation/BridgeTo.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2021 the original author or authors.
+ * Copyright 2014-2022 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.
@@ -43,6 +43,7 @@
  * If no output channel is provided and no reply-channel exists, an exception is thrown.
  *
  * @author Artem Bilan
+ * @author Chris Bono
  *
  * @since 4.0
  */
@@ -77,10 +78,9 @@
 	/**
 	 * @return the {@link Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
 	 * Mutually exclusive with {@link #reactive()}.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 	/**
 	 * @return the {@link Reactive} marker for a consumer endpoint.

spring-integration-core/src/main/java/org/springframework/integration/annotation/Filter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -40,6 +40,7 @@
  * @author Mark Fisher
  * @author Gary Russell
  * @author Artem Bilan
+ * @author Chris Bono
  *
  * @since 2.0
  */
@@ -128,10 +129,9 @@
 	/**
 	 * @return the {@link Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
 	 * Mutually exclusive with {@link #reactive()}.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 	/**
 	 * @return the {@link Reactive} marker for a consumer endpoint.

spring-integration-core/src/main/java/org/springframework/integration/annotation/InboundChannelAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2019 the original author or authors.
+ * Copyright 2014-2022 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.
@@ -23,6 +23,7 @@
 import java.lang.annotation.Target;
 
 import org.springframework.core.annotation.AliasFor;
+import org.springframework.messaging.handler.annotation.ValueConstants;
 
 /**
  * Indicates that a method is capable of producing a {@link org.springframework.messaging.Message}
@@ -45,6 +46,7 @@
  *
  * @author Artem Bilan
  * @author Gary Russell
+ * @author Chris Bono
  *
  * @since 4.0
  */
@@ -86,10 +88,8 @@
 	/**
 	 * @return the {@link org.springframework.integration.annotation.Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
-	 * Only one {@link org.springframework.integration.annotation.Poller} element is allowed.
 	 * NOTE: a {@link Poller} here has {@link Poller#maxMessagesPerPoll()} set to 1 by default.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 }

spring-integration-core/src/main/java/org/springframework/integration/annotation/Router.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -45,6 +45,7 @@
  *
  * @author Mark Fisher
  * @author Artem Bilan
+ * @author Chris Bono
  */
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -151,10 +152,9 @@
 	/**
 	 * @return the {@link Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
 	 * Mutually exclusive with {@link #reactive()}.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 	/**
 	 * @return the {@link Reactive} marker for a consumer endpoint.

spring-integration-core/src/main/java/org/springframework/integration/annotation/ServiceActivator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -43,6 +43,7 @@
  * @author Gary Russell
  * @author Artem Bilan
  * @author Yilin Wei
+ * @author Chris Bono
  */
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -121,11 +122,9 @@
 	/**
 	 * @return the {@link Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
-	 * Only one {@link Poller} element is allowed.
 	 * Mutually exclusive with {@link #reactive()}.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 	/**
 	 * @return the {@link Reactive} marker for a consumer endpoint.

spring-integration-core/src/main/java/org/springframework/integration/annotation/Splitter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -43,6 +43,7 @@
  * @author Mark Fisher
  * @author Gary Russell
  * @author Artem Bilan
+ * @author Chris Bono
  */
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -116,10 +117,9 @@
 	/**
 	 * @return the {@link Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
 	 * Mutually exclusive with {@link #reactive()}.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 	/**
 	 * @return the {@link Reactive} marker for a consumer endpoint.

spring-integration-core/src/main/java/org/springframework/integration/annotation/Transformer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -31,6 +31,7 @@
  * @author Mark Fisher
  * @author Gary Russell
  * @author Artem Bilan
+ * @author Chris Bono
  */
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -92,10 +93,9 @@
 	/**
 	 * @return the {@link Poller} options for a polled endpoint
 	 * ({@link org.springframework.integration.scheduling.PollerMetadata}).
-	 * This attribute is an {@code array} just to allow an empty default (no poller).
 	 * Mutually exclusive with {@link #reactive()}.
 	 */
-	Poller[] poller() default { };
+	Poller poller() default @Poller(ValueConstants.DEFAULT_NONE);
 
 	/**
 	 * @return the {@link Reactive} marker for a consumer endpoint.

spring-integration-core/src/main/java/org/springframework/integration/config/annotation/AbstractMethodAnnotationPostProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -84,7 +84,6 @@
 import org.springframework.messaging.SubscribableChannel;
 import org.springframework.messaging.core.DestinationResolutionException;
 import org.springframework.messaging.core.DestinationResolver;
-import org.springframework.messaging.handler.annotation.ValueConstants;
 import org.springframework.scheduling.Trigger;
 import org.springframework.scheduling.support.CronTrigger;
 import org.springframework.scheduling.support.PeriodicTrigger;
@@ -103,6 +102,7 @@
  * @author Mark Fisher
  * @author Artem Bilan
  * @author Gary Russell
+ * @author Chris Bono
  */
 public abstract class AbstractMethodAnnotationPostProcessor<T extends Annotation>
 		implements MethodAnnotationPostProcessor<T> {
@@ -363,24 +363,24 @@ protected AbstractEndpoint createEndpoint(MessageHandler handler, @SuppressWarni
 	protected AbstractEndpoint doCreateEndpoint(MessageHandler handler, MessageChannel inputChannel,
 			List<Annotation> annotations) {
 
-		Poller[] pollers = MessagingAnnotationUtils.resolveAttribute(annotations, "poller", Poller[].class);
+		Poller poller = MessagingAnnotationUtils.resolveAttribute(annotations, "poller", Poller.class);
+
 		Reactive reactive = MessagingAnnotationUtils.resolveAttribute(annotations, "reactive", Reactive.class);
-		boolean reactiveProvided = reactive != null && !ValueConstants.DEFAULT_NONE.equals(reactive.value());
 
-		Assert.state(!reactiveProvided || ObjectUtils.isEmpty(pollers),
+		Assert.state(reactive == null || poller == null,
 				"The 'poller' and 'reactive' are mutually exclusive.");
 
-		if (inputChannel instanceof Publisher || handler instanceof ReactiveMessageHandlerAdapter || reactiveProvided) {
-			return reactiveStreamsConsumer(inputChannel, handler, reactiveProvided ? reactive : null);
+		if (inputChannel instanceof Publisher || handler instanceof ReactiveMessageHandlerAdapter || reactive != null) {
+			return reactiveStreamsConsumer(inputChannel, handler, reactive);
 		}
 		else if (inputChannel instanceof SubscribableChannel) {
-			Assert.state(ObjectUtils.isEmpty(pollers), () ->
+			Assert.state(poller == null, () ->
 					"A '@Poller' should not be specified for Annotation-based " +
 							"endpoint, since '" + inputChannel + "' is a SubscribableChannel (not pollable).");
 			return new EventDrivenConsumer((SubscribableChannel) inputChannel, handler);
 		}
 		else if (inputChannel instanceof PollableChannel) {
-			return pollingConsumer(inputChannel, handler, pollers);
+			return pollingConsumer(inputChannel, handler, poller);
 		}
 		else {
 			throw new IllegalArgumentException("Unsupported 'inputChannel' type: '"
@@ -414,19 +414,15 @@ private ReactiveStreamsConsumer reactiveStreamsConsumer(MessageChannel channel,
 		return reactiveStreamsConsumer;
 	}
 
-	private PollingConsumer pollingConsumer(MessageChannel inputChannel, MessageHandler handler, Poller[] pollers) {
+	private PollingConsumer pollingConsumer(MessageChannel inputChannel, MessageHandler handler, Poller poller) {
 		PollingConsumer pollingConsumer = new PollingConsumer((PollableChannel) inputChannel, handler);
-		configurePollingEndpoint(pollingConsumer, pollers);
+		configurePollingEndpoint(pollingConsumer, poller);
 		return pollingConsumer;
 	}
 
-	protected void configurePollingEndpoint(AbstractPollingEndpoint pollingEndpoint, Poller[] pollers) {
+	protected void configurePollingEndpoint(AbstractPollingEndpoint pollingEndpoint, Poller poller) {
 		PollerMetadata pollerMetadata;
-		if (!ObjectUtils.isEmpty(pollers)) {
-			Assert.state(pollers.length == 1,
-					"The 'poller' for an Annotation-based endpoint can have only one '@Poller'.");
-			Poller poller = pollers[0];
-
+		if (poller != null) {
 			String ref = poller.value();
 			String triggerRef = poller.trigger();
 			String executorRef = poller.taskExecutor();

spring-integration-core/src/main/java/org/springframework/integration/config/annotation/InboundChannelAdapterAnnotationPostProcessor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2021 the original author or authors.
+ * Copyright 2014-2022 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.
@@ -44,6 +44,7 @@
  * @author Artem Bilan
  * @author Gary Russell
  * @author Oleg Zhurakousky
+ * @author Chris Bono
  *
  * @since 4.0
  */
@@ -82,8 +83,8 @@ public Object postProcess(Object bean, String beanName, Method method, List<Anno
 		SourcePollingChannelAdapter adapter = new SourcePollingChannelAdapter();
 		adapter.setOutputChannelName(channelName);
 		adapter.setSource(messageSource);
-		Poller[] pollers = MessagingAnnotationUtils.resolveAttribute(annotations, "poller", Poller[].class);
-		configurePollingEndpoint(adapter, pollers);
+		Poller poller = MessagingAnnotationUtils.resolveAttribute(annotations, "poller", Poller.class);
+		configurePollingEndpoint(adapter, poller);
 
 		return adapter;
 	}