← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/oscache/gutsy

« back to all changes in this revision

Viewing changes to docs/cron.html

  • Committer: Bazaar Package Importer
  • Author(s): Kalle Kivimaa
  • Date: 2004-08-13 14:00:00 UTC
  • Revision ID: james.westby@ubuntu.com-20040813140000-lyugvinublk1x8y2
Tags: upstream-2.0.2
Import upstream version 2.0.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/cron.html
 
1
<html>
 
2
<head>
 
3
<title>Expiring Cached Content with Cron Expressions</title>
 
4
</head>
 
5
 
 
6
<body bgcolor="#FFFFFF">
 
7
<p>Prior to version 2.0 of OSCache, content expiry could only be specified in terms of how long a
 
8
piece of content had been in the cache, ie, it was based on the age of the content. If you needed
 
9
to expire it at a particular time of day or on a specific date, you had to write a custom
 
10
<code>RefreshPolicy</code> class.</p>
 
11
<p>OSCache 2.0 now gives you the ability to expire content at specific dates and/or times based on
 
12
a <em>cron expression</em>.</p>
 
13
 
 
14
<h3>What is a Cron Expression?</h3>
 
15
<p>Many of you are probably already familiar with the unix cron program. For those that aren't,
 
16
cron is a daemon process that allows users to execute commands or scripts automatically at
 
17
user-configurable dates and times. The important part as far as OSCache is concerned is the cron
 
18
expression syntax that allows users to dictate when commands should be executed - you can now use
 
19
the same syntax to expire content in OSCache! A cron expression is a simple text string that
 
20
specifies particular dates and/or times that are matched against.</p>
 
21
 
 
22
<h3>How Does OSCache Match Against an Expression?</h3>
 
23
<p>OSCache uses cron expressions in a manner that might seem 'backwards' to what you might
 
24
initially expect. When using a cron expression to test if a cache entry is stale, OSCache finds
 
25
the date and time (prior to the current time) that <em>most recently matches</em> the supplied
 
26
expression. This date/time is used as the expiry time - entries that were placed in the cache prior
 
27
to this expiry time are considered stale and result in a <code>NeedsRefreshException</code> being
 
28
thrown.</p>
 
29
<p>As an example, suppose you specify a cron expiry that matches every hour, on the hour
 
30
(<code>"0 * * * *"</code>). If the current time is 10:42pm, then any content that was placed in
 
31
the cache prior to 10:00pm would be considered stale.</p>
 
32
 
 
33
<h3>The Cron Expression Syntax</h3>
 
34
<p>A cron expression consists of the following 5 fields:
 
35
<ul>
 
36
  <li><b>Minute</b> - specifies what minute of the hour to expire content on. It is a number
 
37
    between 0 and 59.</li>
 
38
  <li><b>Hour</b> - determines what hour of the day content will expire on. It is specified
 
39
    using the 24-hour clock, so the values must be between 0 (midnight) and 23 (11pm).</li>
 
40
  <li><b>DOM</b> - the Day of the Month. This is a number from 1 to 31. It indicates what day the
 
41
    content should expire on. For example, to expire content on the 10th of every month, set this
 
42
    field to 10.</li>
 
43
  <li><b>Month</b> - month of the year to expire the content. This can be specified either
 
44
    numerically (1 through 12), or by using the actual month name (eg 'January'). Month names are
 
45
    case-insensitive and only the first three characters are taken into account - the rest are
 
46
    ignored.</li>
 
47
  <li><b>DOW</b> - The Day of the Week that the content should be expired on. This can be a numeric
 
48
    value (0-6, where 0 = Sunday, 1 = Monday, ..., 6 = Saturday), or you can use the actual day name.
 
49
    As is the case with month names, DOW names are case-insensitive and only the first three
 
50
    characters matter.</li>
 
51
</ul>
 
52
 
 
53
If you don't want to specify a value for a particular field (ie you want the cron expression to
 
54
match <em>all</em> values for that field), just use a * character for the field value.</p>
 
55
 
 
56
<p>As an example, an expression that expired content at 11:45pm each day during April would
 
57
look like this: <code>"45 23 * April *"</code>.</p>
 
58
 
 
59
<p>OSCache also allows you to optionally specify lists, ranges and intervals (or even a combination
 
60
of all three) within each field:
 
61
<ul>
 
62
  <li><b>Lists</b> - items in a list are delimited using the ',' character. Content expiry times
 
63
    will be matched against all values in the list for that field. For example,
 
64
    <code>"0,15,30,45 * * * *"</code> will expire content every quarter-hour on the quarter hour.</li>
 
65
  <li><b>Ranges</b> - ranges are specified using the '-' character. A range will include all
 
66
    values from the start to the end value (inclusive). For example, <code>"* * * Jan-June *"</code>
 
67
    will expire content every minute only during the first 6 months of the year.</li>
 
68
  <li><b>Intervals</b> - an interval is specified using the '/' character. The value to the left of
 
69
    the '/' character indicates either the starting point or the range of values that should be
 
70
    incremented over, while the value to the right of the '/' specifies the interval or step size.
 
71
    Some examples - <code>"10/20 * * * *"</code> is equivalent to <code>"10,30,50 * * * *"</code>,
 
72
    while <code>"10-45/20 * * * *"</code> would only match 10 and 30 minutes past the hour, since 50
 
73
    is outside the specified range. Supplying '*' as the left-hand value of an interval will match
 
74
    the same values as if you had specified a range over all possible values. Eg <code>"*/10 * * * *"</code>
 
75
    matches minutes 0,10,20,30,40 and 50.</code></li>
 
76
</ul></p>
 
77
 
 
78
<p>To have a look at further examples of both valid and invalid syntax, it is suggested you take a look
 
79
at the JUnit test cases in the <code>com.opensymphony.oscache.util.TestFastCronParser</code>
 
80
class. This class is located under the <code>src/core/test</code> directory. For examples of how to
 
81
specify cron expiry times using the taglibs, see the <a href="tags.html">Tag Reference</a> and the
 
82
<code>cronTest.jsp</code> file in the example web application.</p>
 
83
 
 
84
 
 
85
<h3>Notes</h3>
 
86
<p>
 
87
<ul>
 
88
  <li>You can specify both a cron expression and a refresh interval at the same time if you like.
 
89
    This is useful in cases where you always want to expire content at midnight, but you also never
 
90
    want it to be more than 6 hours old.</li>
 
91
  <li>Specifying out of range values, such as a 13 in the month field, will cause a
 
92
    <code>ParseException</code> to be thrown.</li>
 
93
  <li>If a DOM is specified that cannot exist given the allowable months, a <code>ParseException</code>
 
94
    will be thrown. For example, <code>"* * 31 Feb *"</code> will fail because no date will ever match
 
95
    the 31st February!</li>
 
96
  <li>The DOM and DOW fields cannot both be specified at the same time. One must always be set to '*'
 
97
    otherwise a <code>ParseException</code> will be thrown.</li>
 
98
  <li>Leap years and local daylight savings time are taken into account. Eg <code>"0 0 29 Feb *"</code>
 
99
    will match midnight on the 29th February, ie only once every 4 years.</li>
 
100
  <li>Currently the time used to match the cron expression against is always based on the local time
 
101
    on the server. If there is demand support for specifying an alternate timezone may be added in a
 
102
    future release.</li>
 
103
</ul></p>
 
104
</body>
 
105
</html>
 
 
b'\\ No newline at end of file'