INT-3519 Add Poll Skip Advice

JIRA: https://jira.spring.io/browse/INT-3519

Add a mechanism to allow skipping polls, perhaps
because of some downstream condition.

INT-3519: Polishing

spring-integration-core/src/main/java/org/springframework/integration/scheduling/PollSkipAdvice.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2014 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.scheduling;
+
+import org.aopalliance.intercept.MethodInterceptor;
+import org.aopalliance.intercept.MethodInvocation;
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
+/**
+ * An advice that can be added to a poller's advice chain that determines
+ * whether a poll should be skipped or not. May be used to temporarily suspend
+ * polling when some downstream condition exists in the flow.
+ *
+ * @author Gary Russell
+ * @since 4.1
+ *
+ */
+public class PollSkipAdvice implements MethodInterceptor {
+
+	private static final Log logger = LogFactory.getLog(PollSkipAdvice.class);
+
+	private final PollSkipStrategy pollSkipStrategy;
+
+	public PollSkipAdvice() {
+		this(new DefaultPollSkipStrategy());
+	}
+
+
+	public PollSkipAdvice(PollSkipStrategy strategy) {
+		this.pollSkipStrategy = strategy;
+	}
+
+
+	@Override
+	public Object invoke(MethodInvocation invocation) throws Throwable {
+		if ("call".equals(invocation.getMethod().getName()) && this.pollSkipStrategy.skipPoll()) {
+			if (logger.isDebugEnabled()) {
+				logger.debug("Skipping poll because "
+						+ this.pollSkipStrategy.getClass().getName()
+						+ ".skipPoll() returned true");
+			}
+			return Boolean.FALSE;
+		}
+		else {
+			return invocation.proceed();
+		}
+	}
+
+
+	private static class DefaultPollSkipStrategy implements PollSkipStrategy {
+
+		@Override
+		public boolean skipPoll() {
+			return false;
+		}
+
+	}
+
+}

spring-integration-core/src/main/java/org/springframework/integration/scheduling/PollSkipStrategy.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2014 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.scheduling;
+
+/**
+ * Implementations determine whether a particular poll should be skipped.
+ *
+ * @author Gary Russell
+ * @since 4.1
+ *
+ */
+public interface PollSkipStrategy {
+
+	/**
+	 * Return true if this poll should be skipped.
+	 * @return true to skip.
+	 */
+	boolean skipPoll();
+
+}

spring-integration-core/src/test/java/org/springframework/integration/endpoint/PollerAdviceTests.java

@@ -0,0 +1,124 @@
+/*
+ * Copyright 2014 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.endpoint;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+import static org.mockito.Mockito.mock;
+
+import java.util.ArrayList;
+import java.util.Date;
+import java.util.List;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
+import org.aopalliance.aop.Advice;
+import org.junit.Test;
+
+import org.springframework.beans.factory.BeanFactory;
+import org.springframework.integration.channel.NullChannel;
+import org.springframework.integration.core.MessageSource;
+import org.springframework.integration.scheduling.PollSkipAdvice;
+import org.springframework.integration.scheduling.PollSkipStrategy;
+import org.springframework.messaging.Message;
+import org.springframework.scheduling.Trigger;
+import org.springframework.scheduling.TriggerContext;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler;
+
+/**
+ * @author Gary Russell
+ * @since 4.1
+ *
+ */
+public class PollerAdviceTests {
+
+	@Test
+	public void testDefaultDontSkip() throws Exception {
+		SourcePollingChannelAdapter adapter = new SourcePollingChannelAdapter();
+		final CountDownLatch latch = new CountDownLatch(1);
+		adapter.setSource(new MessageSource<Object>() {
+
+			@Override
+			public Message<Object> receive() {
+				latch.countDown();
+				return null;
+			}
+		});
+		adapter.setTrigger(new Trigger() {
+
+			@Override
+			public Date nextExecutionTime(TriggerContext triggerContext) {
+				return new Date(System.currentTimeMillis() + 10);
+			}
+		});
+		configure(adapter);
+		List<Advice> adviceChain = new ArrayList<Advice>();
+		PollSkipAdvice advice = new PollSkipAdvice();
+		adviceChain.add(advice);
+		adapter.setAdviceChain(adviceChain);
+		adapter.afterPropertiesSet();
+		adapter.start();
+		assertTrue(latch.await(10, TimeUnit.SECONDS));
+		adapter.stop();
+	}
+
+	@Test
+	public void testSkipAll() throws Exception {
+		SourcePollingChannelAdapter adapter = new SourcePollingChannelAdapter();
+		final CountDownLatch latch = new CountDownLatch(1);
+		adapter.setSource(new MessageSource<Object>() {
+
+			@Override
+			public Message<Object> receive() {
+				latch.countDown();
+				return null;
+			}
+		});
+		adapter.setTrigger(new Trigger() {
+
+			@Override
+			public Date nextExecutionTime(TriggerContext triggerContext) {
+				return new Date(System.currentTimeMillis() + 10);
+			}
+		});
+		configure(adapter);
+		List<Advice> adviceChain = new ArrayList<Advice>();
+		PollSkipAdvice advice = new PollSkipAdvice(new PollSkipStrategy() {
+
+			@Override
+			public boolean skipPoll() {
+				return true;
+			}
+
+		});
+		adviceChain.add(advice);
+		adapter.setAdviceChain(adviceChain);
+		adapter.afterPropertiesSet();
+		adapter.start();
+		assertFalse(latch.await(1, TimeUnit.SECONDS));
+		adapter.stop();
+	}
+
+	private void configure(SourcePollingChannelAdapter adapter) {
+		adapter.setOutputChannel(new NullChannel());
+		adapter.setBeanFactory(mock(BeanFactory.class));
+		ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
+		scheduler.afterPropertiesSet();
+		adapter.setTaskScheduler(scheduler);
+	}
+
+}

src/reference/docbook/polling-consumer.xml

@@ -59,6 +59,15 @@
         <listitem>Polling internal (pollable) Message Channels</listitem>
         <listitem>Polling internal services (E.g. repeatedly execute methods on a Java class)</listitem>
     </itemizedlist>
+    <note>
+        AOP Advice classes can be applied to pollers, in an <code>advice-chain</code>. An example being a
+        transaction advice to start a transaction. Starting with <emphasis>version 4.1</emphasis> a
+        <classname>PollSkipAdvice</classname> is provided. Pollers use triggers to determine the time
+        of the next poll. The <classname>PollSkipAdvice</classname> can be used to suppress (skip) a
+        poll, perhaps because there is some downstream condition that would prevent the message to
+        be processed properly. To use this advice, you have to provide it with an implementation
+        of a <interfacename>PollSkipStrategy</interfacename>.
+    </note>
     <para>
         This chapter is meant to only give a high-level overview regarding Polling Consumers
         and how they fit into the concept of message channels - <xref linkend="channel"/> and

src/reference/docbook/whats-new.xml

@@ -34,6 +34,16 @@
 				for the JSON transformers. See <xref linkend="transformer"/> for more information.
 			</para>
 		</section>
+		<section id="4.1-PollSkipAdvice">
+			<title>PollSkipAdvice</title>
+			<para>
+				The <classname>PollSkipAdvice</classname> is now provided to be used within
+				<code>&lt;advice-chain&gt;</code> of the <code>&lt;poller&gt;</code> to determine if the current
+				<emphasis>poll</emphasis> should be suppressed (skipped) by some condition implemented with
+				<interfacename>PollSkipStrategy</interfacename>.
+				See <xref linkend="polling-consumer"/> for more information.
+			</para>
+		</section>
 	</section>
 	<section id="4.1-general">
 		<title>General Changes</title>