<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You 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.
-->

<document>
    <body>
        <section>
            <title>Cron Job Scheduler</title>
        
            <p>
                This implementation of the Java interface 
                <link href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/cron/JobScheduler.html">
                <code>JobScheduler</code></link> 
                is based on the <link href="http://www.opensymphony.com/quartz/">Quartz</link>
                job scheduling project and the 
                <code>RunnableManager</code> as a ThreadPool implementation for the Quartz Scheduler.
            </p>
            
            <p style="background-color: yellow">
                <strong>WARNING:</strong> Consider the <link href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/cron/JobScheduler.html">
                <code>JobScheduler</code></link> interface as beta in terms of defined functionality as it will be 
                extended with additional requirements in the near future (i.e. getJobList). 
            </p>
        
            <p>
                This <link href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/cron/QuartzJobScheduler.html">
                <code>QuartzJobScheduler</code></link> implementation is written as a standard 
                <link href="http://excalibur.apache.org/framework/index.html">Avalon</link> component. So, its definition you'll find in the
                <code>cocoon.xconf</code> file of Cocoon if you've included the cron-block in your build (see 
                block.properties or local.block.properties file respectively).
            </p>
        
            <p>
                The snippet below shows the configuration example of the component itself:
            </p>
            <source>
&lt;component role="org.apache.cocoon.components.cron.JobScheduler"
           class="org.apache.cocoon.components.cron.QuartzJobScheduler"
           logger="cron"&gt;
    &lt;thread-pool&gt;
        ...
    &lt;/thread-pool&gt;
    &lt;triggers&gt;
        ...
    &lt;/triggers&gt;
&lt;/component&gt;
            </source>
    
            <p>
                There is nothing special about it. As you could see from the snippet above, inside the job 
                scheduler component definition there are two parts:
                <ul>
                    <li>ThreadPool definition</li>
                    <li>Trigger definitions</li>
                </ul>
            </p>            

            <section>
                <title>ThreadPool</title>    
                <p>
                    The ThreadPool definition look like this:
                </p>
                <source>
&lt;!-- Definitions for a thread pool used to schedule jobs --&gt;
&lt;thread-pool&gt;

    &lt;!-- Should we queue up execution requests if the pool is busy? Defaults to false --&gt;
    &lt;use-queueing&gt;false&lt;/use-queueing&gt;

    &lt;!-- How big should the queue be. Defaults to unlimited size (&lt;0 == default) --&gt;
    &lt;queue-size&gt;-1&lt;/queue-size&gt;

    &lt;!-- The maximum size of the pool. Defaults to Integer.MAX_VALUE (&lt;0 == default) --&gt;
    &lt;max-pool-size&gt;-1&lt;/max-pool-size&gt;

    &lt;!-- The minimum size of the pool.Defaults to 1 (&lt;0 == default) --&gt;
    &lt;min-pool-size&gt;1&lt;/min-pool-size&gt;

    &lt;!-- How long will an idle thread be kept before it will be discarded. 
         Defaults to 60000ms (&lt;0 == default) --&gt;
    &lt;keep-alive-time-ms&gt;60000&lt;/keep-alive-time-ms&gt;

    &lt;!-- Which blocking policy should be used if the maximum pool size and queue size is bounded:
         Run:           (default) The thread making the execute request runs the task itself. 
                        This policy helps guard against lockup. 
         Wait:          Wait until a thread becomes available. 
         Abort:         Throw a RuntimeException 
         Discard:       Throw away the current request and return. 
         DiscardOldest: Throw away the oldest request and return. --&gt;
    &lt;block-policy&gt;RUN&lt;/block-policy&gt;

    &lt;!-- Should queued and running jobs be given a chance to finished on system shutdown. Defaults to true --&gt;
    &lt;shutdown-graceful&gt;true&lt;/shutdown-graceful&gt;

    &lt;!-- The maximum time to wait for running jobs to complete. Defaults to unlimited time (&lt;0 == default) --&gt;
    &lt;shutdown-wait-time-ms&gt;5000&lt;/shutdown-wait-time-ms&gt;
&lt;/thread-pool&gt;
                </source>
                <p>
                    As mentioned in the beginning, more information about the thread pool details base on the
                    <code>RunnableManager#createPool(...)</code> method can be found there.
                </p>
            </section>
            
            <section>
                <title>Triggers</title>
                <p>
                    The trigger definition section consists of a single <code>&lt;triggers&gt;</code> element with as much as
                    needed <code>&lt;trigger&gt;</code> elements inside it. A <code>&lt;trigger&gt;</code> element 
                    looks like:
                </p>
                <source>
&lt;!-- Definintions of triggers --&gt;
&lt;triggers&gt;

    &lt;!-- A trigger element has the following attributes:
            name:            A name for the trigger. Mandatory
            target:          A role name to lookup the job object in the ServiceManager. Mandatory
            concurrent-runs: Is it allowed to reschedule a job even if the previous one is
                             still running. Optionl, defaults to true.
         A trigger element has the following child elements:
            cron: A string expression defining the scheduling timing.
                  Optional. If not specified the following elements are explored:
               seconds:  A string expression for the secods part of a cron expression.
               minutes:  A string expression for the secods part of a cron expression.
               hours:    A string expression for the secods part of a cron expression.
               days:     A string expression for the secods part of a cron expression.
               month:    A string expression for the secods part of a cron expression.
               weekdays: A string expression for the secods part of a cron expression.
               years:    A string expression for the secods part of a cron expression.
            For detailed information about the expressions look at the documentation
    --&gt;

    &lt;trigger name="test-job1"
             target="org.apache.cocoon.components.cron.CronJob/test"
             concurrent-runs="false"&gt;
        &lt;cron&gt;*/12 * * * * ? *&lt;/cron&gt;
    &lt;/trigger&gt;
    &lt;trigger name="test-job2"
         target="org.apache.cocoon.components.cron.CronJob/test"
         concurrent-runs="true"&gt;
        &lt;seconds&gt;*/12&lt;/seconds&gt;
        &lt;minutes&gt;*/5&lt;/minutes&gt;
        &lt;hours&gt;8,10,12,14,16,18&lt;/hours&gt;
        &lt;days&gt;?&lt;/days&gt;
        &lt;months&gt;*&lt;/months&gt;
        &lt;weekdays&gt;SUN-FRI&lt;/weekdays&gt;
    &lt;/trigger&gt;
&lt;/triggers&gt;
                </source>
                <p>
                    The <code>&lt;cron&gt;</code> element is simply the concatenation of the values of the elements 
                    <code>&lt;seconds&gt;</code>, <code>&lt;minutes&gt;</code>, <code>&lt;hours&gt;</code>, 
                    <code>&lt;days&gt;</code>, <code>&lt;months&gt;</code>, <code>&lt;weekdays&gt;</code>, and 
                    <code>&lt;year&gt;</code> delimeted with spaces. You can use either form but the 
                    <code>&lt;cron&gt;</code> element will be preferred by the implementation if you use both forms 
                    together in one <code>&lt;trigger&gt;</code> element. A description of the 
                    expressions used inside the <code>&lt;trigger&gt;</code> elements is described in the 
                    <link href="http://www.opensymphony.com/quartz/api/org/quartz/CronTrigger.html">
                    <code>CronTrigger</code></link> class.
                </p>
            </section>
            
            <section>
                <title>Job Components</title>
                <p>
                    The 
                    <link href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/cron/CronJob.html"><code>CronJob</code></link> 
                    object doing your work can be defined in the <code>cocoon.xconf</code> 
                    file as a regular Avalon components. The <code>role</code> attribute given to this component is 
                    refered to by the <code>target</code> attribute in the <code>&lt;trigger&gt;</code> element above.
                    Below is the sample for the 
                    <link href="http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/components/cron/TestCronJob.html">
                    <code>TestCronJob</code></link> component.
                </p>
                <source>
&lt;!-- sample definition of cron job --&gt;
&lt;component role="org.apache.cocoon.components.cron.CronJob/test"
           class="org.apache.cocoon.components.cron.TestCronJob"
           logger="cron.test"&gt;
    &lt;msg&gt;I'm here&lt;/msg&gt;
    &lt;sleep&gt;23000&lt;/sleep&gt;
&lt;/component&gt;
                </source>
            </section>

            <section>
                <title>Samples</title>
                <p>
                    Now you should take a look at the samples to show you how the API of the 
                    <link href="cron.html"><code>JobScheduler</code></link> can be used.
                </p>
            </section>
        </section>
    </body>
</document>
