chap-scheduling.xml revision 4a2c14c95ba1b1dc8f51fac4f480e6688ce862a9
<?xml version="1.0" encoding="UTF-8"?>
<!--
! CCPL HEADER START
!
! This work is licensed under the Creative Commons
! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
! To view a copy of this license, visit
! or send a letter to Creative Commons, 444 Castro Street,
! Suite 900, Mountain View, California, 94041, USA.
!
! You can also obtain a copy of the license at
! See the License for the specific language governing permissions
! and limitations under the License.
!
! If applicable, add the following below this CCPL HEADER, with the fields
! enclosed by brackets "[]" replaced with your own identifying information:
! Portions Copyright [yyyy] [name of copyright owner]
!
! CCPL HEADER END
!
! Copyright 2011 ForgeRock AS
!
-->
<chapter xml:id='chap-scheduling'
xmlns='http://docbook.org/ns/docbook'
version='5.0' xml:lang='en'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
<title>Scheduling</title>
<sect1>
<title>Overview</title>
<para/>
<para>Invocations that need to be scheduled can use the scheduler facility. The facility is akin to a cron schedule, and uses the Quartz library.</para>
<para/>
<para>The facility can be configured via the org.forgerock.scheduler service, e.g. by creating a file with the name pattern</para>
<para/>
<para>where <code><my-schedule-name></code> is replaced with the logical name for the schedule to be configured.</para>
<para/>
<para>Or the scheduling can be requested by modules themselves, with the configuration in their format/location.</para>
<para/>
</sect1>
<sect1>
<title>Configuration</title>
<para>The scheduler configuration in the file conf/org.forgerock.scheduler-<my-schedule-name>.json has the format</para>
<example>
<literallayout class="monospaced">
<code><![CDATA[
{
"type" : "cron",
"startTime" : "<optional time>",
"endTime" : "<optional time>",
"schedule" : "<cron expression>",
"timeZone" : "<optional time zone" "<America/Los_Angeles",
"invokeService" : "<service identifier>",
"invokeContext" : "<service specific context info>"
}]]>
</code>
</literallayout>
</example>
<para/>
<para/>
<para>The optional properties can be absent, or empty</para>
<para/>
<para>The schedule expression is in the cron style format described here : </para>
<para>
<link xlink:href="http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html">http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html</link>
</para>
<para>
<link xlink:href="http://www.quartz-scheduler.org/docs/tutorial/TutorialLesson06.html">http://www.quartz-scheduler.org/docs/tutorial/TutorialLesson06.html</link>
</para>
<para/>
<para>The invokeServer service identifier is defined in the documentation of scheduleable services, as well as the context information they can take. The scheduler identifier can be "relative" without the reverse domain notation, in which case it is prefixed with org.forgerock.openidm - e.g. an invokeService service identifier of "active-sync" is equivalent to "org.forgerock.openidm.active-sync".</para>
<para/>
<example>
<title>Complex example</title>
<literallayout class="monospaced">
<code><![CDATA[
{
"type" : "cron",
"startTime" : "2011-05-03T10:00:00 ",
"endTime" : "2011-05-03T15:59:59",
"schedule" : "0 30 10-13 ? * WED,FRI"
"timeZone" : "America/Los_Angeles"
"invokeService" : "active-sync",
"invokeContext" : "system-x"
}]]>
</code>
</literallayout>
</example>
<para/>
<example>
<title>Simple example</title>
<literallayout class="monospaced">
<code><![CDATA[
{
"type", "cron",
"schedule" : "0 30 10-13 ? * WED,FRI"
"invokeService" : "active-sync",
"invokeContext" : "system-x"
}]]>
</code>
</literallayout>
</example>
</sect1>
<sect1>
<title>Service Implementer Notes</title>
<para/>
<para>To implement a service that can be scheduled, the service needs to implement ScheduledService. The service PID is used as a basis for the service identifier in schedule definitions.</para>
<para/>
</sect1>
</chapter>