Explicit notes on programmatic Executor setup in @Bean methods

Issue: SPR-8131

spring-context/src/main/java/org/springframework/scheduling/concurrent/ScheduledExecutorFactoryBean.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -42,7 +42,14 @@ import org.springframework.util.ObjectUtils;
  * cancelling it on destruction of the context. In scenarios that only require static
  * registration of tasks at startup, there is no need to access the
  * {@link ScheduledExecutorService} instance itself in application code at all;
- * ScheduledExecutorFactoryBean is then just being used for lifecycle integration.
+ * {@code ScheduledExecutorFactoryBean} is then just being used for lifecycle integration.
+ *
+ * <p>For an alternative, you may set up a {@link ScheduledThreadPoolExecutor} instance
+ * directly using constructor injection, or use a factory method definition that points
+ * to the {@link java.util.concurrent.Executors} class.
+ * <b>This is strongly recommended in particular for common {@code @Bean} methods in
+ * configuration classes, where this {@code FactoryBean} variant would force you to
+ * return the {@code FactoryBean} type instead of {@code ScheduledExecutorService}.</b>
  *
  * <p>Note that {@link java.util.concurrent.ScheduledExecutorService}
  * uses a {@link Runnable} instance that is shared between repeated executions,

spring-context/src/main/java/org/springframework/scheduling/concurrent/ThreadPoolExecutorFactoryBean.java

@@ -36,12 +36,15 @@ import org.springframework.beans.factory.InitializingBean;
  * "queueCapacity" properties) and exposing it as a bean reference of its native
  * {@link java.util.concurrent.ExecutorService} type.
  *
- * <p>For an alternative, you may set up a ThreadPoolExecutor instance directly using
- * constructor injection, or use a factory method definition that points to the
+ * <p>For an alternative, you may set up a {@link ThreadPoolExecutor} instance directly
+ * using constructor injection, or use a factory method definition that points to the
  * {@link java.util.concurrent.Executors} class.
+ * <b>This is strongly recommended in particular for common {@code @Bean} methods in
+ * configuration classes, where this {@code FactoryBean} variant would force you to
+ * return the {@code FactoryBean} type instead of the actual {@code Executor} type.</b>
  *
- * <p><b>If you need a timing-based {@link java.util.concurrent.ScheduledExecutorService}
- * instead, consider {@link ScheduledExecutorFactoryBean}.</b>
+ * <p>If you need a timing-based {@link java.util.concurrent.ScheduledExecutorService}
+ * instead, consider {@link ScheduledExecutorFactoryBean}.
 
  * @author Juergen Hoeller
  * @since 3.0