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

Document @Enable* annotations

Browse Source 
Update reference manual with details of Java configuration @Enable*
annotations. Examples of Java style @Configuration is provided
when appropriate alongside existing XML samples.

Several existing @Configuration samples have been changed to placing
the @Enable annotation below the @Configuration annotation.
This has been done to provide consistency with existing Javadoc.

Issue: SPR-9920
This commit is contained in:
Phillip Webb
2012-11-20 12:09:44 -08:00
parent da50a0213b
commit 59b27004de
9 changed files with 415 additions and 275 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
src/reference/docbook/scheduling.xml
View File

@@ -357,155 +357,52 @@ public class TaskExecutorExample {
</section>
</section>
<section id="scheduling-task-namespace">
<title>The Task Namespace</title>
<para>Beginning with Spring 3.0, there is an XML namespace for configuring
<interfacename>TaskExecutor</interfacename> and
<interfacename>TaskScheduler</interfacename> instances. It also provides a
convenient way to configure tasks to be scheduled with a trigger.</para>
<section id="scheduling-task-namespace-scheduler">
<title>The 'scheduler' element</title>
<para>The following element will create a
<classname>ThreadPoolTaskScheduler</classname> instance with the
specified thread pool size.</para>
<programlisting language="xml">&lt;task:scheduler id="scheduler" pool-size="10"/&gt;</programlisting>
<para>The value provided for the 'id' attribute will be used as the
prefix for thread names within the pool. The 'scheduler' element is
relatively straightforward. If you do not provide a 'pool-size'
attribute, the default thread pool will only have a single thread. There
are no other configuration options for the scheduler.</para>
</section>
<section id="scheduling-task-namespace-executor">
<title>The 'executor' element</title>
<para>The following will create a
<classname>ThreadPoolTaskExecutor</classname> instance: <programlisting
language="xml">&lt;task:executor id="executor" pool-size="10"/&gt;</programlisting></para>
<para>As with the scheduler above, the value provided for the 'id'
attribute will be used as the prefix for thread names within the pool.
As far as the pool size is concerned, the 'executor' element supports
more configuration options than the 'scheduler' element. For one thing,
the thread pool for a <classname>ThreadPoolTaskExecutor</classname> is
itself more configurable. Rather than just a single size, an executor's
thread pool may have different values for the <emphasis>core</emphasis>
and the <emphasis>max</emphasis> size. If a single value is provided
then the executor will have a fixed-size thread pool (the core and max
sizes are the same). However, the 'executor' element's 'pool-size'
attribute also accepts a range in the form of "min-max". <programlisting
language="xml">&lt;task:executor id="executorWithPoolSizeRange"
pool-size="5-25"
queue-capacity="100"/&gt;</programlisting></para>
<para>As you can see from that configuration, a 'queue-capacity' value
has also been provided. The configuration of the thread pool should also
be considered in light of the executor's queue capacity. For the full
description of the relationship between pool size and queue capacity,
consult the documentation for <ulink
url="http://java.sun.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.html">ThreadPoolExecutor</ulink>.
The main idea is that when a task is submitted, the executor will first
try to use a free thread if the number of active threads is currently
less than the core size. If the core size has been reached, then the
task will be added to the queue as long as its capacity has not yet been
reached. Only then, if the queue's capacity <emphasis>has</emphasis>
been reached, will the executor create a new thread beyond the core
size. If the max size has also been reached, then the executor will
reject the task.</para>
<para>By default, the queue is <emphasis>unbounded</emphasis>, but this
is rarely the desired configuration, because it can lead to
<classname>OutOfMemoryErrors</classname> if enough tasks are added to
that queue while all pool threads are busy. Furthermore, if the queue is
unbounded, then the max size has no effect at all. Since the executor
will always try the queue before creating a new thread beyond the core
size, a queue must have a finite capacity for the thread pool to grow
beyond the core size (this is why a <emphasis>fixed size</emphasis> pool
is the only sensible case when using an unbounded queue).</para>
<para>In a moment, we will review the effects of the keep-alive setting
which adds yet another factor to consider when providing a pool size
configuration. First, let's consider the case, as mentioned above, when
a task is rejected. By default, when a task is rejected, a thread pool
executor will throw a <classname>TaskRejectedException</classname>.
However, the rejection policy is actually configurable. The exception is
thrown when using the default rejection policy which is the
<classname>AbortPolicy</classname> implementation. For applications
where some tasks can be skipped under heavy load, either the
<classname>DiscardPolicy</classname> or
<classname>DiscardOldestPolicy</classname> may be configured instead.
Another option that works well for applications that need to throttle
the submitted tasks under heavy load is the
<classname>CallerRunsPolicy</classname>. Instead of throwing an
exception or discarding tasks, that policy will simply force the thread
that is calling the submit method to run the task itself. The idea is
that such a caller will be busy while running that task and not able to
submit other tasks immediately. Therefore it provides a simple way to
throttle the incoming load while maintaining the limits of the thread
pool and queue. Typically this allows the executor to "catch up" on the
tasks it is handling and thereby frees up some capacity on the queue, in
the pool, or both. Any of these options can be chosen from an
enumeration of values available for the 'rejection-policy' attribute on
the 'executor' element.</para>
<programlisting language="xml">&lt;task:executor id="executorWithCallerRunsPolicy"
pool-size="5-25"
queue-capacity="100"
rejection-policy="CALLER_RUNS"/&gt;</programlisting>
</section>
<section id="scheduling-task-namespace-scheduled-tasks">
<title>The 'scheduled-tasks' element</title>
<para>The most powerful feature of Spring's task namespace is the
support for configuring tasks to be scheduled within a Spring
Application Context. This follows an approach similar to other
"method-invokers" in Spring, such as that provided by the JMS namespace
for configuring Message-driven POJOs. Basically a "ref" attribute can
point to any Spring-managed object, and the "method" attribute provides
the name of a method to be invoked on that object. Here is a simple
example.</para>
<programlisting language="xml">&lt;task:scheduled-tasks scheduler="myScheduler"&gt;
&lt;task:scheduled ref="beanA" method="methodA" fixed-delay="5000"/&gt;
&lt;/task:scheduled-tasks&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;</programlisting>
<para>As you can see, the scheduler is referenced by the outer element,
and each individual task includes the configuration of its trigger
metadata. In the preceding example, that metadata defines a periodic
trigger with a fixed delay indicating the number of milliseconds to wait
after each task execution has completed. Another option is 'fixed-rate',
indicating how often the method should be executed regardless of how long
any previous execution takes. Additionally, for both fixed-delay and
fixed-rate tasks an 'initial-delay' parameter may be specified indicating
the number of milliseconds to wait before the first execution of the
method. For more control, a "cron" attribute may be provided instead.
Here is an example demonstrating these other options.</para>
<programlisting language="xml">&lt;task:scheduled-tasks scheduler="myScheduler"&gt;
&lt;task:scheduled ref="beanA" method="methodA" fixed-delay="5000" initial-delay="1000"/&gt;
&lt;task:scheduled ref="beanB" method="methodB" fixed-rate="5000"/&gt;
&lt;task:scheduled ref="beanC" method="methodC" cron="*/5 * * * * MON-FRI"/&gt;
&lt;/task:scheduled-tasks&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;</programlisting>
</section>
</section>
<section id="scheduling-annotation-support">
<title>Annotation Support for Scheduling and Asynchronous
Execution</title>
<para>Spring 3.0 also adds annotation support for both task scheduling and
<para>Spring provides annotation support for both task scheduling and
asynchronous method execution.</para>
<section id="secheduling-enable-annotation-support">
<title>Enable scheduling annotations</title>
<para>To enable support for <interfacename>@Scheduled</interfacename> and
<interfacename>@Async</interfacename> annotations add
<interfacename>@EnableScheduling</interfacename> and
<interfacename>@EnableAsync</interfacename> to one of your
<interfacename>@Configuration</interfacename> classes:</para>
<programlisting language="java">@Configuration
@EnableAsync
@EnableSCheduling
public class AppConfig {
}</programlisting>
<para>You are free to pick and choose the relevant annotations
for your application. For example, if you only need support
for <interfacename>@Scheduled</interfacename>, simply omit
<interfacename>@EnableAsync</interfacename>. For more fine-grained
control you can additionally implement the
<interfacename>SchedulingConfigurer</interfacename> and/or
<interfacename>AsyncConfigurer</interfacename> interfaces. See
the Javadoc for full details.</para>
<para>If you prefer XML configuration use the
<literal>&lt;task:annotation-driven&gt;</literal> element.</para>
<programlisting language="xml">&lt;task:annotation-driven executor="myExecutor" scheduler="myScheduler"/&gt;
&lt;task:executor id="myExecutor" pool-size="5"/&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;}</programlisting>
<para>Notice with the above XML that an executor reference is provided
for handling those tasks that correspond to methods with the
<interfacename>@Async</interfacename> annotation, and the scheduler
reference is provided for managing those methods annotated
with <interfacename>@Scheduled</interfacename>.</para>
</section>
<section id="scheduling-annotation-support-scheduled">
<title>The @Scheduled Annotation</title>
@@ -636,25 +533,6 @@ public class SampleBeanInititalizer {
}</programlisting>
</section>
<section id="scheduling-annotation-support-namespace">
<title>The &lt;annotation-driven&gt; Element</title>
<para>To enable both @Scheduled and @Async annotations, simply include
the 'annotation-driven' element from the task namespace in your
configuration.</para>
<programlisting language="xml">&lt;task:annotation-driven executor="myExecutor" scheduler="myScheduler"/&gt;
&lt;task:executor id="myExecutor" pool-size="5"/&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;}</programlisting>
<para>Notice that an executor reference is provided for handling those
tasks that correspond to methods with the @Async annotation, and the
scheduler reference is provided for managing those methods annotated
with @Scheduled.</para>
</section>
<section id="scheduling-annotation-support-qualification">
<title>Executor qualification with @Async</title>
@@ -679,6 +557,148 @@ void doSomething(String s) {
</section>
</section>
<section id="scheduling-task-namespace">
<title>The Task Namespace</title>
<para>Beginning with Spring 3.0, there is an XML namespace for configuring
<interfacename>TaskExecutor</interfacename> and
<interfacename>TaskScheduler</interfacename> instances. It also provides a
convenient way to configure tasks to be scheduled with a trigger.</para>
<section id="scheduling-task-namespace-scheduler">
<title>The 'scheduler' element</title>
<para>The following element will create a
<classname>ThreadPoolTaskScheduler</classname> instance with the
specified thread pool size.</para>
<programlisting language="xml">&lt;task:scheduler id="scheduler" pool-size="10"/&gt;</programlisting>
<para>The value provided for the 'id' attribute will be used as the
prefix for thread names within the pool. The 'scheduler' element is
relatively straightforward. If you do not provide a 'pool-size'
attribute, the default thread pool will only have a single thread. There
are no other configuration options for the scheduler.</para>
</section>
<section id="scheduling-task-namespace-executor">
<title>The 'executor' element</title>
<para>The following will create a
<classname>ThreadPoolTaskExecutor</classname> instance: <programlisting
language="xml">&lt;task:executor id="executor" pool-size="10"/&gt;</programlisting></para>
<para>As with the scheduler above, the value provided for the 'id'
attribute will be used as the prefix for thread names within the pool.
As far as the pool size is concerned, the 'executor' element supports
more configuration options than the 'scheduler' element. For one thing,
the thread pool for a <classname>ThreadPoolTaskExecutor</classname> is
itself more configurable. Rather than just a single size, an executor's
thread pool may have different values for the <emphasis>core</emphasis>
and the <emphasis>max</emphasis> size. If a single value is provided
then the executor will have a fixed-size thread pool (the core and max
sizes are the same). However, the 'executor' element's 'pool-size'
attribute also accepts a range in the form of "min-max". <programlisting
language="xml">&lt;task:executor id="executorWithPoolSizeRange"
pool-size="5-25"
queue-capacity="100"/&gt;</programlisting></para>
<para>As you can see from that configuration, a 'queue-capacity' value
has also been provided. The configuration of the thread pool should also
be considered in light of the executor's queue capacity. For the full
description of the relationship between pool size and queue capacity,
consult the documentation for <ulink
url="http://java.sun.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.html">ThreadPoolExecutor</ulink>.
The main idea is that when a task is submitted, the executor will first
try to use a free thread if the number of active threads is currently
less than the core size. If the core size has been reached, then the
task will be added to the queue as long as its capacity has not yet been
reached. Only then, if the queue's capacity <emphasis>has</emphasis>
been reached, will the executor create a new thread beyond the core
size. If the max size has also been reached, then the executor will
reject the task.</para>
<para>By default, the queue is <emphasis>unbounded</emphasis>, but this
is rarely the desired configuration, because it can lead to
<classname>OutOfMemoryErrors</classname> if enough tasks are added to
that queue while all pool threads are busy. Furthermore, if the queue is
unbounded, then the max size has no effect at all. Since the executor
will always try the queue before creating a new thread beyond the core
size, a queue must have a finite capacity for the thread pool to grow
beyond the core size (this is why a <emphasis>fixed size</emphasis> pool
is the only sensible case when using an unbounded queue).</para>
<para>In a moment, we will review the effects of the keep-alive setting
which adds yet another factor to consider when providing a pool size
configuration. First, let's consider the case, as mentioned above, when
a task is rejected. By default, when a task is rejected, a thread pool
executor will throw a <classname>TaskRejectedException</classname>.
However, the rejection policy is actually configurable. The exception is
thrown when using the default rejection policy which is the
<classname>AbortPolicy</classname> implementation. For applications
where some tasks can be skipped under heavy load, either the
<classname>DiscardPolicy</classname> or
<classname>DiscardOldestPolicy</classname> may be configured instead.
Another option that works well for applications that need to throttle
the submitted tasks under heavy load is the
<classname>CallerRunsPolicy</classname>. Instead of throwing an
exception or discarding tasks, that policy will simply force the thread
that is calling the submit method to run the task itself. The idea is
that such a caller will be busy while running that task and not able to
submit other tasks immediately. Therefore it provides a simple way to
throttle the incoming load while maintaining the limits of the thread
pool and queue. Typically this allows the executor to "catch up" on the
tasks it is handling and thereby frees up some capacity on the queue, in
the pool, or both. Any of these options can be chosen from an
enumeration of values available for the 'rejection-policy' attribute on
the 'executor' element.</para>
<programlisting language="xml">&lt;task:executor id="executorWithCallerRunsPolicy"
pool-size="5-25"
queue-capacity="100"
rejection-policy="CALLER_RUNS"/&gt;</programlisting>
</section>
<section id="scheduling-task-namespace-scheduled-tasks">
<title>The 'scheduled-tasks' element</title>
<para>The most powerful feature of Spring's task namespace is the
support for configuring tasks to be scheduled within a Spring
Application Context. This follows an approach similar to other
"method-invokers" in Spring, such as that provided by the JMS namespace
for configuring Message-driven POJOs. Basically a "ref" attribute can
point to any Spring-managed object, and the "method" attribute provides
the name of a method to be invoked on that object. Here is a simple
example.</para>
<programlisting language="xml">&lt;task:scheduled-tasks scheduler="myScheduler"&gt;
&lt;task:scheduled ref="beanA" method="methodA" fixed-delay="5000"/&gt;
&lt;/task:scheduled-tasks&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;</programlisting>
<para>As you can see, the scheduler is referenced by the outer element,
and each individual task includes the configuration of its trigger
metadata. In the preceding example, that metadata defines a periodic
trigger with a fixed delay indicating the number of milliseconds to wait
after each task execution has completed. Another option is 'fixed-rate',
indicating how often the method should be executed regardless of how long
any previous execution takes. Additionally, for both fixed-delay and
fixed-rate tasks an 'initial-delay' parameter may be specified indicating
the number of milliseconds to wait before the first execution of the
method. For more control, a "cron" attribute may be provided instead.
Here is an example demonstrating these other options.</para>
<programlisting language="xml">&lt;task:scheduled-tasks scheduler="myScheduler"&gt;
&lt;task:scheduled ref="beanA" method="methodA" fixed-delay="5000" initial-delay="1000"/&gt;
&lt;task:scheduled ref="beanB" method="methodB" fixed-rate="5000"/&gt;
&lt;task:scheduled ref="beanC" method="methodC" cron="*/5 * * * * MON-FRI"/&gt;
&lt;/task:scheduled-tasks&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;</programlisting>
</section>
</section>
<section id="scheduling-quartz">
<title>Using the Quartz Scheduler</title>