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

Update reference documentation generation tools to get source highlighting [SPRNET-1045]

Browse Source
This commit is contained in:
bbaia
2008-10-05 17:25:10 +00:00
parent 26cb75d4e0
commit 5dfa039603
125 changed files with 4487 additions and 7338 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
doc/reference/src/scheduling.xml
View File

@@ -1,41 +1,58 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="scheduling">
<!--
/*
* Copyright 2002-2008 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.
*/
-->
<chapter xml:id="scheduling" xmlns="http://docbook.org/ns/docbook" version="5">
<title>Scheduling and Thread Pooling</title>
<section id="scheduling-introduction">
<section xml:id="scheduling-introduction">
<title>Introduction</title>
<para>The Spring Framework features integration classes for scheduling
support. Currently, Spring supports the Quartz Scheduler (<ulink
url="http://quartznet.sourceforge.net/"></ulink>). The scheduler is set up
using a <interfacename>IFactoryObject</interfacename> with optional
references to <classname>Trigger</classname> instances, respectively.
using a <literal>IFactoryObject</literal> with optional
references to <literal>Trigger</literal> instances, respectively.
Furthermore, a convenience class for both the Quartz Scheduler is
available that allows you to invoke a method of an existing target
object.</para>
</section>
<section id="scheduling-quartz">
<section xml:id="scheduling-quartz">
<title>Using the Quartz.NET Scheduler</title>
<para>Quartz uses <classname>Trigger</classname>,
<classname>Job</classname> and <classname>JobDetail</classname> objects to
<para>Quartz uses <literal>Trigger</literal>,
<literal>Job</literal> and <literal>JobDetail</literal> objects to
realize scheduling of all kinds of jobs. For the basic concepts behind
Quartz, have a look at <ulink
url="http://quartznet.sourceforge.net/"></ulink>. For convenience
purposes, Spring offers a couple of classes that simplify the usage of
Quartz within Spring-based applications.</para>
<section id="scheduling-quartz-jobdetail">
<section xml:id="scheduling-quartz-jobdetail">
<title>Using the JobDetailObject</title>
<para><classname>JobDetail</classname> objects contain all information
<para><literal>JobDetail</literal> objects contain all information
needed to run a job. The Spring Framework provides a
<classname>JobDetailObject</classname> that makes the
<classname>JobDetail</classname> easier to configure and with sensible
<literal>JobDetailObject</literal> that makes the
<literal>JobDetail</literal> easier to configure and with sensible
defaults. Let's have a look at an example:</para>
<programlisting>
<programlisting language="myxml">
&lt;object name="ExampleJob" type="Spring.Scheduling.Quartz.JobDetailObject, Spring.Scheduling.Quartz"&gt;
&lt;property name="JobType" value="Example.Quartz.ExampleJob, Example.Quartz" /&gt;
&lt;property name="JobDataAsMap"&gt;
@@ -46,17 +63,17 @@
&lt;/object&gt;</programlisting>
<para>The job detail object has all information it needs to run the job
(<classname>ExampleJob</classname>). The timeout is specified in the job
(<literal>ExampleJob</literal>). The timeout is specified in the job
data dictionary. The job data dictonary is available through the
<classname>JobExecutionContext</classname> (passed to you at execution
time), but the <classname>JobDetailObject</classname> also maps the
<literal>JobExecutionContext</literal> (passed to you at execution
time), but the <literal>JobDetailObject</literal> also maps the
properties from the job data map to properties of the actual job. So in
this case, if the <classname>ExampleJob</classname> contains a property
this case, if the <literal>ExampleJob</literal> contains a property
named <literal>Timeout</literal>, the
<classname>JobDetailObject</classname> will automatically apply
<literal>JobDetailObject</literal> will automatically apply
it:</para>
<programlisting>namespace Example.Quartz;
<programlisting language="csharp">namespace Example.Quartz;
public class ExampleJob extends QuartzJobObject {
@@ -85,15 +102,15 @@ public class ExampleJob extends QuartzJobObject {
<literal>ExampleJob</literal>).</emphasis></para>
</section>
<section id="scheduling-quartz-method-invoking-job">
<section xml:id="scheduling-quartz-method-invoking-job">
<title>Using the
<classname>MethodInvokingJobDetailFactoryObject</classname></title>
<literal>MethodInvokingJobDetailFactoryObject</literal></title>
<para>Often you just need to invoke a method on a specific object. Using
the <classname>MethodInvokingJobDetailFactoryObject</classname> you can
the <literal>MethodInvokingJobDetailFactoryObject</literal> you can
do exactly this:</para>
<programlisting>&lt;object id="JobDetail" type="Spring.Scheduling.Quartz.MethodInvokingJobDetailFactoryObject, Spring.Scheduling.Quartz"&gt;
<programlisting language="myxml">&lt;object id="JobDetail" type="Spring.Scheduling.Quartz.MethodInvokingJobDetailFactoryObject, Spring.Scheduling.Quartz"&gt;
&lt;property name="TargetObject" ref="ExampleBusinessObject" /&gt;
&lt;property name="TargetMethod" value="DoIt" /&gt;
&lt;/object&gt;</programlisting>
@@ -102,7 +119,7 @@ public class ExampleJob extends QuartzJobObject {
method being called on the <literal>exampleBusinessObject</literal>
method (see below):</para>
<programlisting>public class ExampleBusinessObject {
<programlisting language="csharp">public class ExampleBusinessObject {
<lineannotation>// properties and collaborators</lineannotation>
@@ -111,28 +128,28 @@ public class ExampleJob extends QuartzJobObject {
}
}</programlisting>
<programlisting>
<programlisting language="myxml">
&lt;object id="ExampleBusinessObject" type="Examples.BusinessObjects.ExampleBusinessObject, Examples.BusinessObjects"/&gt;</programlisting>
<para>Using the
<classname>MethodInvokingJobDetailFactoryObject</classname>, you don't
<literal>MethodInvokingJobDetailFactoryObject</literal>, you don't
need to create one-line jobs that just invoke a method, and you only
need to create the actual business object and wire up the detail
object.</para>
<para>By default, Quartz Jobs are stateless, resulting in the
possibility of jobs interfering with each other. If you specify two
triggers for the same <classname>JobDetail</classname>, it might be
triggers for the same <literal>JobDetail</literal>, it might be
possible that before the first job has finished, the second one will
start. If <classname>JobDetail</classname> classes implement the
<interfacename>Stateful</interfacename> interface, this won't happen.
start. If <literal>JobDetail</literal> classes implement the
<literal>Stateful</literal> interface, this won't happen.
The second job will not start before the first one has finished. To make
jobs resulting from the
<classname>MethodInvokingJobDetailFactoryObject</classname>
<literal>MethodInvokingJobDetailFactoryObject</literal>
non-concurrent, set the <literal>concurrent</literal> flag to
<literal>false</literal>.</para>
<programlisting>&lt;object id="JobDetail" type="Spring.Scheduling.Quartz.MethodInvokingJobDetailFactoryObject, Spring.Scheduling.Quartz"&gt;
<programlisting language="myxml">&lt;object id="JobDetail" type="Spring.Scheduling.Quartz.MethodInvokingJobDetailFactoryObject, Spring.Scheduling.Quartz"&gt;
&lt;property name="TargetObject" ref="ExampleBusinessObject" /&gt;
&lt;property name="TargetMethod" value="DoIt" /&gt;
&lt;property name="Concurrent" value="false" /&gt;
@@ -148,27 +165,27 @@ public class ExampleJob extends QuartzJobObject {
</note>
</section>
<section id="scheduling-quartz-cron">
<section xml:id="scheduling-quartz-cron">
<title>Wiring up jobs using triggers and the
<classname>SchedulerFactoryObject</classname></title>
<literal>SchedulerFactoryObject</literal></title>
<para>We've created job details and jobs. We've also reviewed the
convenience class that allows to you invoke a method on a specific
object. Of course, we still need to schedule the jobs themselves. This
is done using triggers and a
<classname>SchedulerFactoryObject</classname>. Several triggers are
<literal>SchedulerFactoryObject</literal>. Several triggers are
available within Quartz. Spring offers two subclassed triggers with
convenient defaults: <classname>CronTriggerObject</classname> and
<classname>SimpleTriggerObject</classname></para>
convenient defaults: <literal>CronTriggerObject</literal> and
<literal>SimpleTriggerObject</literal></para>
<para>Triggers need to be scheduled. Spring offers a
<classname>SchedulerFactoryObject</classname> that exposes triggers to
be set as properties. <classname>SchedulerFactoryObject</classname>
<literal>SchedulerFactoryObject</literal> that exposes triggers to
be set as properties. <literal>SchedulerFactoryObject</literal>
schedules the actual jobs with those triggers.</para>
<para>Find below a couple of examples:</para>
<programlisting>&lt;object id="SimpleTrigger" type="Spring.Scheduling.Quartz.SimpleTriggerObject, Spring.Scheduling.Quartz"&gt;
<programlisting language="myxml">&lt;object id="SimpleTrigger" type="Spring.Scheduling.Quartz.SimpleTriggerObject, Spring.Scheduling.Quartz"&gt;
&lt;!-- see the example of method invoking job above --&gt;
&lt;property name="JobDetail" ref="ExampleJob" /&gt;
@@ -190,9 +207,9 @@ public class ExampleJob extends QuartzJobObject {
<para>Now we've set up two triggers, one running every 50 seconds with a
starting delay of 10 seconds and one every morning at 6 AM. To finalize
everything, we need to set up the
<classname>SchedulerFactoryObject</classname>:</para>
<literal>SchedulerFactoryObject</literal>:</para>
<programlisting>&lt;object id="quartzSchedulerFactory" type="Spring.Scheduling.Quartz.SchedulerFactoryObject, Spring.Scheduling.Quartz"&gt;
<programlisting language="myxml">&lt;object id="quartzSchedulerFactory" type="Spring.Scheduling.Quartz.SchedulerFactoryObject, Spring.Scheduling.Quartz"&gt;
&lt;property name="triggers"&gt;
&lt;list&gt;
&lt;ref object="CronTrigger" /&gt;
@@ -203,7 +220,7 @@ public class ExampleJob extends QuartzJobObject {
</programlisting>
<para>More properties are available for the
<classname>SchedulerFactoryObjecct</classname> for you to set, such as
<literal>SchedulerFactoryObjecct</literal> for you to set, such as
the calendars used by the job details, properties to customize Quartz
with, etc. Have a look at the <ulink
url="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/scheduling/quartz/SchedulerFactoryBean.html">SchedulerFactoryObject