home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / docs.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  10.4 KB  |  214 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17.  
  18. <document>
  19.     <body>
  20.         <section>
  21.             <title>Cron Job Scheduler</title>
  22.         
  23.             <p>
  24.                 This implementation of the Java interface 
  25.                 <link href="/api/java/org/apache/cocoon/components/cron/JobScheduler.html">
  26.                 <code>JobScheduler</code></link> 
  27.                 is based on the <link href="http://quartz.sf.net">Quartz</link>
  28.                 job scheduling project and the 
  29.                 <link href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/PooledExecutor.html">
  30.                 <code>PooledExecutor</code></link> of 
  31.                 <link href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html">
  32.                 Doug Leas Concurrency Package</link> as a ThreadPool implementation for the Quartz Scheduler.
  33.             </p>
  34.             
  35.             <p style="background-color: yellow">
  36.                 <strong>WARNING:</strong> Consider the <link href="/api/java/org/apache/cocoon/components/cron/JobScheduler.html">
  37.                 <code>JobScheduler</code></link> interface as beta in terms of defined functionality as it will be 
  38.                 extended with additional requirements in the near future (i.e. getJobList). 
  39.             </p>
  40.         
  41.             <p>
  42.                 This <link href="/api/java/org/apache/cocoon/components/cron/QuartzJobScheduler.html">
  43.                 <code>QuartzJobScheduler</code></link> implementation is written as a standard 
  44.                 <link href="http://avalon.apache.org/">Avalon</link> component. So, its definition you'll find in the
  45.                 <code>cocoon.xconf</code> file of Cocoon if you've included the cron-block in your build (see 
  46.                 block.properties or local.block.properties file respectively).
  47.             </p>
  48.         
  49.             <p>
  50.                 The snippet below shows the configuration example of the component itself:
  51.             </p>
  52.             <source>
  53. <component role="org.apache.cocoon.components.cron.JobScheduler"
  54.            class="org.apache.cocoon.components.cron.QuartzJobScheduler"
  55.            logger="cron">
  56.     <thread-pool>
  57.         ...
  58.     </thread-pool>
  59.     <triggers>
  60.         ...
  61.     </triggers>
  62. </component>
  63.             </source>
  64.     
  65.             <p>
  66.                 There is nothing special about it. As you could see from the snippet above, inside the job 
  67.                 scheduler component definition there are two parts:
  68.                 <ul>
  69.                     <li>ThreadPool definition</li>
  70.                     <li>Trigger definitions</li>
  71.                 </ul>
  72.             </p>            
  73.  
  74.             <section>
  75.                 <title>ThreadPool</title>    
  76.                 <p>
  77.                     The ThreadPool definition look like this:
  78.                 </p>
  79.                 <source>
  80. <!-- Definitions for a thread pool used to schedule jobs -->
  81. <thread-pool>
  82.  
  83.     <!-- Should we queue up execution requests if the pool is busy? Defaults to false -->
  84.     <use-queueing>false</use-queueing>
  85.  
  86.     <!-- How big should the queue be. Defaults to unlimited size (<0 == default) -->
  87.     <queue-size>-1</queue-size>
  88.  
  89.     <!-- The maximum size of the pool. Defaults to Integer.MAX_VALUE (<0 == default) -->
  90.     <max-pool-size>-1</max-pool-size>
  91.  
  92.     <!-- The minimum size of the pool.Defaults to 1 (<0 == default) -->
  93.     <min-pool-size>1</min-pool-size>
  94.  
  95.     <!-- How long will an idle thread be kept before it will be discarded. 
  96.          Defaults to 60000ms (<0 == default) -->
  97.     <keep-alive-time-ms>60000</keep-alive-time-ms>
  98.  
  99.     <!-- Which blocking policy should be used if the maximum pool size and queue size is bounded:
  100.          Run:           (default) The thread making the execute request runs the task itself. 
  101.                         This policy helps guard against lockup. 
  102.          Wait:          Wait until a thread becomes available. 
  103.          Abort:         Throw a RuntimeException 
  104.          Discard:       Throw away the current request and return. 
  105.          DiscardOldest: Throw away the oldest request and return. -->
  106.     <block-policy>RUN</block-policy>
  107.  
  108.     <!-- Should queued and running jobs be given a chance to finished on system shutdown. Defaults to true -->
  109.     <shutdown-graceful>true</shutdown-graceful>
  110.  
  111.     <!-- The maximum time to wait for running jobs to complete. Defaults to unlimited time (<0 == default) -->
  112.     <shutdown-wait-time-ms>5000</shutdown-wait-time-ms>
  113. </thread-pool>
  114.                 </source>
  115.                 <p>
  116.                     As mentioned in the beginning, more information about the thread pool details of the base
  117.                     <link href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/PooledExecutor.html">
  118.                     <code>PooledExecutor</code></link> class can be found there.
  119.                 </p>
  120.             </section>
  121.             
  122.             <section>
  123.                 <title>Triggers</title>
  124.                 <p>
  125.                     The trigger definition section consists of a single <code><triggers></code> element with as much as
  126.                     needed <code><trigger></code> elements inside it. A <code><trigger></code> element 
  127.                     looks like:
  128.                 </p>
  129.                 <source>
  130. <!-- Definintions of triggers -->
  131. <triggers>
  132.  
  133.     <!-- A trigger element has the following attributes:
  134.             name:            A name for the trigger. Mandatory
  135.             target:          A role name to lookup the job object in the ServiceManager. Mandatory
  136.             concurrent-runs: Is it allowed to reschedule a job even if the previous one is
  137.                              still running. Optionl, defaults to true.
  138.          A trigger element has the following child elements:
  139.             cron: A string expression defining the scheduling timing.
  140.                   Optional. If not specified the following elements are explored:
  141.                seconds:  A string expression for the secods part of a cron expression.
  142.                minutes:  A string expression for the secods part of a cron expression.
  143.                hours:    A string expression for the secods part of a cron expression.
  144.                days:     A string expression for the secods part of a cron expression.
  145.                month:    A string expression for the secods part of a cron expression.
  146.                weekdays: A string expression for the secods part of a cron expression.
  147.                years:    A string expression for the secods part of a cron expression.
  148.             For detailed information about the expressions look at the documentation
  149.     -->
  150.  
  151.     <trigger name="test-job1"
  152.              target="org.apache.cocoon.components.cron.CronJob/test"
  153.              concurrent-runs="false">
  154.         <cron>*/12 * * * * ? *</cron>
  155.     </trigger>
  156.     <trigger name="test-job2"
  157.          target="org.apache.cocoon.components.cron.CronJob/test"
  158.          concurrent-runs="true">
  159.         <seconds>*/12</seconds>
  160.         <minutes>*/5</minutes>
  161.         <hours>8,10,12,14,16,18</hours>
  162.         <days>?</days>
  163.         <months>*</months>
  164.         <weekdays>SUN-FRI</weekdays>
  165.     </trigger>
  166. </triggers>
  167.                 </source>
  168.                 <p>
  169.                     The <code><cron></code> element is simply the concatenation of the values of the elements 
  170.                     <code><seconds></code>, <code><minutes></code>, <code><hours></code>, 
  171.                     <code><days></code>, <code><months></code>, <code><weekdays></code>, and 
  172.                     <code><year></code> delimeted with spaces. You can use either form but the 
  173.                     <code><cron></code> element will be preferred by the implementation if you use both forms 
  174.                     together in one <code><trigger></code> element. A description of the 
  175.                     expressions used inside the <code><trigger></code> elements is described in the 
  176.                     <link href="http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html">
  177.                     <code>CronTrigger</code></link> class.
  178.                 </p>
  179.             </section>
  180.             
  181.             <section>
  182.                 <title>Job Components</title>
  183.                 <p>
  184.                     The 
  185.                     <link href="/api/java/org/apache/cocoon/components/cron/CronJob.html"><code>CronJob</code></link> 
  186.                     object doing your work can be defined in the <code>cocoon.xconf</code> 
  187.                     file as a regular Avalon components. The <code>role</code> attribute given to this component is 
  188.                     refered to by the <code>target</code> attribute in the <code><trigger></code> element above.
  189.                     Below is the sample for the 
  190.                     <link href="/api/java/org/apache/cocoon/components/cron/TestCronJob.html">
  191.                     <code>TestCronJob</code></link> component.
  192.                 </p>
  193.                 <source>
  194. <!-- sample definition of cron job -->
  195. <component role="org.apache.cocoon.components.cron.CronJob/test"
  196.            class="org.apache.cocoon.components.cron.TestCronJob"
  197.            logger="cron.test">
  198.     <msg>I'm here</msg>
  199.     <sleep>23000</sleep>
  200. </component>
  201.                 </source>
  202.             </section>
  203.  
  204.             <section>
  205.                 <title>Samples</title>
  206.                 <p>
  207.                     Now you should take a look at the samples to show you how the API of the 
  208.                     <link href="cron.html"><code>JobScheduler</code></link> can be used.
  209.                 </p>
  210.             </section>
  211.         </section>
  212.     </body>
  213. </document>
  214.