| <?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> |
| <component role="org.apache.cocoon.components.cron.JobScheduler" |
| class="org.apache.cocoon.components.cron.QuartzJobScheduler" |
| logger="cron"> |
| <thread-pool> |
| ... |
| </thread-pool> |
| <triggers> |
| ... |
| </triggers> |
| </component> |
| </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> |
| <!-- Definitions for a thread pool used to schedule jobs --> |
| <thread-pool> |
| |
| <!-- Should we queue up execution requests if the pool is busy? Defaults to false --> |
| <use-queueing>false</use-queueing> |
| |
| <!-- How big should the queue be. Defaults to unlimited size (<0 == default) --> |
| <queue-size>-1</queue-size> |
| |
| <!-- The maximum size of the pool. Defaults to Integer.MAX_VALUE (<0 == default) --> |
| <max-pool-size>-1</max-pool-size> |
| |
| <!-- The minimum size of the pool.Defaults to 1 (<0 == default) --> |
| <min-pool-size>1</min-pool-size> |
| |
| <!-- How long will an idle thread be kept before it will be discarded. |
| Defaults to 60000ms (<0 == default) --> |
| <keep-alive-time-ms>60000</keep-alive-time-ms> |
| |
| <!-- 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. --> |
| <block-policy>RUN</block-policy> |
| |
| <!-- Should queued and running jobs be given a chance to finished on system shutdown. Defaults to true --> |
| <shutdown-graceful>true</shutdown-graceful> |
| |
| <!-- The maximum time to wait for running jobs to complete. Defaults to unlimited time (<0 == default) --> |
| <shutdown-wait-time-ms>5000</shutdown-wait-time-ms> |
| </thread-pool> |
| </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><triggers></code> element with as much as |
| needed <code><trigger></code> elements inside it. A <code><trigger></code> element |
| looks like: |
| </p> |
| <source> |
| <!-- Definintions of triggers --> |
| <triggers> |
| |
| <!-- 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 |
| --> |
| |
| <trigger name="test-job1" |
| target="org.apache.cocoon.components.cron.CronJob/test" |
| concurrent-runs="false"> |
| <cron>*/12 * * * * ? *</cron> |
| </trigger> |
| <trigger name="test-job2" |
| target="org.apache.cocoon.components.cron.CronJob/test" |
| concurrent-runs="true"> |
| <seconds>*/12</seconds> |
| <minutes>*/5</minutes> |
| <hours>8,10,12,14,16,18</hours> |
| <days>?</days> |
| <months>*</months> |
| <weekdays>SUN-FRI</weekdays> |
| </trigger> |
| </triggers> |
| </source> |
| <p> |
| The <code><cron></code> element is simply the concatenation of the values of the elements |
| <code><seconds></code>, <code><minutes></code>, <code><hours></code>, |
| <code><days></code>, <code><months></code>, <code><weekdays></code>, and |
| <code><year></code> delimeted with spaces. You can use either form but the |
| <code><cron></code> element will be preferred by the implementation if you use both forms |
| together in one <code><trigger></code> element. A description of the |
| expressions used inside the <code><trigger></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><trigger></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> |
| <!-- sample definition of cron job --> |
| <component role="org.apache.cocoon.components.cron.CronJob/test" |
| class="org.apache.cocoon.components.cron.TestCronJob" |
| logger="cron.test"> |
| <msg>I'm here</msg> |
| <sleep>23000</sleep> |
| </component> |
| </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> |
