Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Up-to-date coverage of task executor and scheduler variants

Browse Source 
Includes a clarification of ThreadPoolExecutor configuration options and a note on early AsyncConfigurer initialization.

Issue: SPR-16944
Issue: SPR-16945

(cherry picked from commit d58c09b)
This commit is contained in:
Juergen Hoeller
2018-06-29 19:43:14 +02:00
parent ac48c64b1a
commit 5a111125c1
4 changed files with 84 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java
View File

@@ -76,6 +76,11 @@ import org.springframework.core.Ordered;
* method.</li>
* </ul>
*
* <p><b>NOTE: {@link AsyncConfigurer} configuration classes get initialized early
* in the application context bootstrap. If you need any dependencies on other beans
* there, make sure to declare them 'lazy' as far as possible in order to let them
* go through other post-processors as well.</b>
*
* <pre class="code">
* &#064;Configuration
* &#064;EnableAsync

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

@@ -1,5 +1,5 @@
/*
* Copyright 2002-2017 the original author or authors.
* Copyright 2002-2018 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.
@@ -37,6 +37,16 @@ import org.springframework.lang.Nullable;
* "queueCapacity" properties) and exposing it as a bean reference of its native
* {@link java.util.concurrent.ExecutorService} type.
*
* <p>The default configuration is a core pool size of 1, with unlimited max pool size
* and unlimited queue capacity. This is roughly equivalent to
* {@link java.util.concurrent.Executors#newSingleThreadExecutor()}, sharing a single
* thread for all tasks. Setting {@link #setQueueCapacity "queueCapacity"} to 0 mimics
* {@link java.util.concurrent.Executors#newCachedThreadPool()}, with immediate scaling
* of threads in the pool to a potentially very high number. Consider also setting a
* {@link #setMaxPoolSize "maxPoolSize"} at that point, as well as possibly a higher
* {@link #setCorePoolSize "corePoolSize"} (see also the
* {@link #setAllowCoreThreadTimeOut "allowCoreThreadTimeOut"} mode of scaling).
*
* <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.

22
spring-context/src/main/java/org/springframework/scheduling/concurrent/ThreadPoolTaskExecutor.java
View File

@@ -48,11 +48,15 @@ import org.springframework.util.concurrent.ListenableFutureTask;
* providing several useful attributes: "corePoolSize", "maxPoolSize", "keepAliveSeconds"
* (all supporting updates at runtime); "poolSize", "activeCount" (for introspection only).
*
* <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
* {@link java.util.concurrent.Executors} class. To expose such a raw Executor as a
* Spring {@link org.springframework.core.task.TaskExecutor}, simply wrap it with a
* {@link org.springframework.scheduling.concurrent.ConcurrentTaskExecutor} adapter.
* <p>The default configuration is a core pool size of 1, with unlimited max pool size
* and unlimited queue capacity. This is roughly equivalent to
* {@link java.util.concurrent.Executors#newSingleThreadExecutor()}, sharing a single
* thread for all tasks. Setting {@link #setQueueCapacity "queueCapacity"} to 0 mimics
* {@link java.util.concurrent.Executors#newCachedThreadPool()}, with immediate scaling
* of threads in the pool to a potentially very high number. Consider also setting a
* {@link #setMaxPoolSize "maxPoolSize"} at that point, as well as possibly a higher
* {@link #setCorePoolSize "corePoolSize"} (see also the
* {@link #setAllowCoreThreadTimeOut "allowCoreThreadTimeOut"} mode of scaling).
*
* <p><b>NOTE:</b> This class implements Spring's
* {@link org.springframework.core.task.TaskExecutor} interface as well as the
@@ -61,13 +65,17 @@ import org.springframework.util.concurrent.ListenableFutureTask;
* exception handling follows the TaskExecutor contract rather than the Executor contract,
* in particular regarding the {@link org.springframework.core.task.TaskRejectedException}.
*
* <p><b>If you prefer native {@link java.util.concurrent.ExecutorService} exposure instead,
* consider {@link ThreadPoolExecutorFactoryBean} as an alternative to this class.</b>
* <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
* {@link java.util.concurrent.Executors} class. To expose such a raw Executor as a
* Spring {@link org.springframework.core.task.TaskExecutor}, simply wrap it with a
* {@link org.springframework.scheduling.concurrent.ConcurrentTaskExecutor} adapter.
*
* @author Juergen Hoeller
* @since 2.0
* @see org.springframework.core.task.TaskExecutor
* @see java.util.concurrent.ThreadPoolExecutor
* @see ThreadPoolExecutorFactoryBean
* @see ConcurrentTaskExecutor
*/
@SuppressWarnings("serial")

112
src/docs/asciidoc/integration.adoc
View File

@@ -463,7 +463,7 @@ shown in this example:
<entry key="/remoting/AccountService" value-ref="accountExporter"/>
</util:map>
</property>
<property name="port" value="8080" />
<property name="port" value="8080"/>
</bean>
----
@@ -2061,13 +2061,13 @@ containers that ships with Spring (in this case the `DefaultMessageListenerConta
[subs="verbatim,quotes"]
----
<!-- this is the Message Driven POJO (MDP) -->
<bean id="messageListener" class="jmsexample.ExampleListener" />
<bean id="messageListener" class="jmsexample.ExampleListener"/>
<!-- and this is the message listener container -->
<bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
<property name="connectionFactory" ref="connectionFactory"/>
<property name="destination" ref="destination"/>
**<property name="messageListener" ref="messageListener" />**
**<property name="messageListener" ref="messageListener"/>**
</bean>
----
@@ -2163,7 +2163,7 @@ POJO that we will make into an MDP via the following configuration.
<bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
<property name="connectionFactory" ref="connectionFactory"/>
<property name="destination" ref="destination"/>
**<property name="messageListener" ref="messageListener" />**
**<property name="messageListener" ref="messageListener"/>**
</bean>
----
@@ -5930,49 +5930,37 @@ behavior, it is possible to use this abstraction for your own needs.
==== TaskExecutor types
There are a number of pre-built implementations of `TaskExecutor` included with the
Spring distribution. In all likelihood, you shouldn't ever need to implement your own.
Spring distribution. In all likelihood, you should never need to implement your own.
The common out-of-the-box variants are:
* `SyncTaskExecutor`
This implementation does not execute invocations asynchronously. Instead, each
invocation takes place in the calling thread. It is primarily used in situations
where multi-threading is not necessary such as in simple test cases.
* `SimpleAsyncTaskExecutor`
This implementation does not reuse any threads, rather it starts up a new thread
for each invocation. However, it does support a concurrency limit which will block
any invocations that are over the limit until a slot has been freed up. If you
are looking for true pooling, see the discussions of `SimpleThreadPoolTaskExecutor`
and `ThreadPoolTaskExecutor` below.
* `SyncTaskExecutor`
This implementation doesn't execute invocations asynchronously. Instead, each
invocation takes place in the calling thread. It is primarily used in situations
where multi-threading isn't necessary such as simple test cases.
are looking for true pooling, see `ThreadPoolTaskExecutor` below.
* `ConcurrentTaskExecutor`
This implementation is an adapter for a `java.util.concurrent.Executor` object.
This implementation is an adapter for a `java.util.concurrent.Executor` instance.
There is an alternative, `ThreadPoolTaskExecutor`, that exposes the `Executor`
configuration parameters as bean properties. It is rare to need to use the
`ConcurrentTaskExecutor`, but if the `ThreadPoolTaskExecutor` isn't flexible
enough for your needs, the `ConcurrentTaskExecutor` is an alternative.
* `SimpleThreadPoolTaskExecutor`
This implementation is actually a subclass of Quartz's `SimpleThreadPool` which
listens to Spring's lifecycle callbacks. This is typically used when you have a
thread pool that may need to be shared by both Quartz and non-Quartz components.
configuration parameters as bean properties. There is rarely a need to use
`ConcurrentTaskExecutor` directly, but if the `ThreadPoolTaskExecutor` is not
flexible enough for your needs, then `ConcurrentTaskExecutor` is an alternative.
* `ThreadPoolTaskExecutor`
This implementation is the most commonly used one. It exposes bean properties for
configuring a `java.util.concurrent.ThreadPoolExecutor` and wraps it in a `TaskExecutor`.
If you need to adapt to a different kind of `java.util.concurrent.Executor`, it is
recommended that you use a `ConcurrentTaskExecutor` instead.
* `WorkManagerTaskExecutor`
+
****
CommonJ is a set of specifications jointly developed between BEA and IBM. These
specifications are not Java EE standards, but are standard across BEA's and IBM's
Application Server implementations.
****
+
This implementation uses the CommonJ `WorkManager` as its backing implementation and is
the central convenience class for setting up a CommonJ `WorkManager` reference in a Spring
context. Similar to the `SimpleThreadPoolTaskExecutor`, this class implements the
`WorkManager` interface and therefore can be used directly as a `WorkManager` as well.
This implementation uses a CommonJ `WorkManager` as its backing service provider
and is the central convenience class for setting up CommonJ-based thread pool
integration on WebLogic/WebSphere within a Spring application context.
* `DefaultManagedTaskExecutor`
This implementation uses a JNDI-obtained `ManagedExecutorService` in a JSR-236
compatible runtime environment such as a Java EE 7+ application server,
replacing a CommonJ WorkManager for that purpose.
[[scheduling-task-executor-usage]]
@@ -6000,7 +5988,6 @@ out a set of messages.
public void run() {
System.out.println(message);
}
}
private TaskExecutor taskExecutor;
@@ -6014,7 +6001,6 @@ out a set of messages.
taskExecutor.execute(new MessagePrinterTask("Message" + i));
}
}
}
----
@@ -6029,13 +6015,13 @@ been exposed.
[subs="verbatim,quotes"]
----
<bean id="taskExecutor" class="org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor">
<property name="corePoolSize" value="5" />
<property name="maxPoolSize" value="10" />
<property name="queueCapacity" value="25" />
<property name="corePoolSize" value="5"/>
<property name="maxPoolSize" value="10"/>
<property name="queueCapacity" value="25"/>
</bean>
<bean id="taskExecutorExample" class="TaskExecutorExample">
<constructor-arg ref="taskExecutor" />
<constructor-arg ref="taskExecutor"/>
</bean>
----
@@ -6054,16 +6040,25 @@ with a variety of methods for scheduling tasks to run at some point in the futur
ScheduledFuture schedule(Runnable task, Trigger trigger);
ScheduledFuture schedule(Runnable task, Instant startTime);
ScheduledFuture schedule(Runnable task, Date startTime);
ScheduledFuture scheduleAtFixedRate(Runnable task, Instant startTime, Duration period);
ScheduledFuture scheduleAtFixedRate(Runnable task, Date startTime, long period);
ScheduledFuture scheduleAtFixedRate(Runnable task, Duration period);
ScheduledFuture scheduleAtFixedRate(Runnable task, long period);
ScheduledFuture scheduleWithFixedDelay(Runnable task, Instant startTime, Duration delay);
ScheduledFuture scheduleWithFixedDelay(Runnable task, Date startTime, long delay);
ScheduledFuture scheduleWithFixedDelay(Runnable task, long delay);
ScheduledFuture scheduleWithFixedDelay(Runnable task, Duration delay);
ScheduledFuture scheduleWithFixedDelay(Runnable task, long delay);
}
----
@@ -6077,8 +6072,8 @@ much more flexible.
[[scheduling-trigger-interface]]
==== Trigger interface
The `Trigger` interface is essentially inspired by JSR-236, which, as of Spring 3.0, has
not yet been officially implemented. The basic idea of the `Trigger` is that execution
The `Trigger` interface is essentially inspired by JSR-236 which, as of Spring 3.0,
was not yet officially implemented. The basic idea of the `Trigger` is that execution
times may be determined based on past execution outcomes or even arbitrary conditions.
If these determinations do take into account the outcome of the preceding execution,
that information is available within a `TriggerContext`. The `Trigger` interface itself
@@ -6090,7 +6085,6 @@ is quite simple:
public interface Trigger {
Date nextExecutionTime(TriggerContext triggerContext);
}
----
@@ -6109,7 +6103,6 @@ default). Here you can see what methods are available for `Trigger` implementati
Date lastActualExecutionTime();
Date lastCompletionTime();
}
----
@@ -6144,19 +6137,21 @@ could be configured externally and therefore easily modified or extended.
==== TaskScheduler implementations
As with Spring's `TaskExecutor` abstraction, the primary benefit of the `TaskScheduler`
is that code relying on scheduling behavior need not be coupled to a particular
scheduler implementation. The flexibility this provides is particularly relevant when
running within Application Server environments where threads should not be created
directly by the application itself. For such cases, Spring provides a
`TimerManagerTaskScheduler` that delegates to a CommonJ TimerManager instance, typically
configured with a JNDI-lookup.
arrangement is that an application's scheduling needs are decoupled from the deployment
environment. This abstraction level is particularly relevant when deploying to an
application server environment where threads should not be created directly by the
application itself. For such scenarios, Spring provides a `TimerManagerTaskScheduler`
delegating to a CommonJ TimerManager on WebLogic/WebSphere as well as a more recent
`DefaultManagedTaskScheduler` delegating to a JSR-236 `ManagedScheduledExecutorService`
in a Java EE 7+ environment, both typically configured with a JNDI lookup.
A simpler alternative, the `ThreadPoolTaskScheduler`, can be used whenever external
thread management is not a requirement. Internally, it delegates to a
`ScheduledExecutorService` instance. `ThreadPoolTaskScheduler` actually implements
Spring's `TaskExecutor` interface as well, so that a single instance can be used for
asynchronous execution __as soon as possible__ as well as scheduled, and potentially
recurring, executions.
Whenever external thread management is not a requirement, a simpler alternative is
a local `ScheduledExecutorService` setup within the application which can be adapted
through Spring's `ConcurrentTaskScheduler`. As a convenience, Spring also provides a
`ThreadPoolTaskScheduler` which internally delegates to a `ScheduledExecutorService`,
providing common bean-style configuration along the lines of `ThreadPoolTaskExecutor`.
These variants work perfectly fine for locally embedded thread pool setups in lenient
application server environments as well, in particular on Tomcat and Jetty.
@@ -7377,8 +7372,7 @@ Alternatively for XML configuration use the `cache:annotation-driven` element:
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd">
<cache:annotation-driven />
<cache:annotation-driven/>
</beans>
----