home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F278296_mod_expires.xml < prev    next >
Extensible Markup Language  |  2004-08-11  |  9KB  |  231 lines
  1. <?xml version="1.0"?>
  2. <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  3. <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
  4. <!-- $Revision: 1.3.2.5 $ -->
  5.  
  6. <!--
  7.  Copyright 2002-2004 The Apache Software Foundation
  8.  
  9.  Licensed under the Apache License, Version 2.0 (the "License");
  10.  you may not use this file except in compliance with the License.
  11.  You may obtain a copy of the License at
  12.  
  13.      http://www.apache.org/licenses/LICENSE-2.0
  14.  
  15.  Unless required by applicable law or agreed to in writing, software
  16.  distributed under the License is distributed on an "AS IS" BASIS,
  17.  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18.  See the License for the specific language governing permissions and
  19.  limitations under the License.
  20. -->
  21.  
  22. <modulesynopsis metafile="mod_expires.xml.meta">
  23.  
  24. <name>mod_expires</name>
  25. <description>Generation of <code>Expires</code> and
  26. <code>Cache-Control</code> HTTP headers according to user-specified
  27. criteria</description>
  28. <status>Extension</status>
  29. <sourcefile>mod_expires.c</sourcefile>
  30. <identifier>expires_module</identifier>
  31.  
  32. <summary>
  33.     <p>This module controls the setting of the <code>Expires</code>
  34.     HTTP header and the <code>max-age</code> directive of the
  35.     <code>Cache-Control</code> HTTP header in server responses. The
  36.     expiration date can set to be relative to either the time the
  37.     source file was last modified, or to the time of the client
  38.     access.</p>
  39.  
  40.     <p>These HTTP headers are an instruction to the client about the
  41.     document's validity and persistence. If cached, the document may
  42.     be fetched from the cache rather than from the source until this
  43.     time has passed. After that, the cache copy is considered
  44.     "expired" and invalid, and a new copy must be obtained from the
  45.     source.</p> 
  46.  
  47.     <p>To modify <code>Cache-Control</code> directives other than
  48.     <code>max-age</code> (see <a
  49.     href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">RFC
  50.     2616 section 14.9</a>), you can use the <directive
  51.     module="mod_headers">Header</directive> directive.</p>
  52.  
  53. </summary>
  54.  
  55. <section id="AltSyn"><title>Alternate Interval Syntax</title>
  56.     <p>The <directive module="mod_expires">ExpiresDefault</directive> and
  57.     <directive module="mod_expires">ExpiresByType</directive> directives
  58.     can also be defined in a more readable syntax of the form:</p>
  59.  
  60.     <example>
  61.       ExpiresDefault "<base> [plus] {<num>
  62.       <type>}*"<br />
  63.       ExpiresByType type/encoding "<base> [plus]
  64.       {<num> <type>}*"
  65.     </example>
  66.  
  67.     <p>where <base> is one of:</p>
  68.  
  69.     <ul>
  70.       <li><code>access</code></li>
  71.  
  72.       <li><code>now</code> (equivalent to
  73.       '<code>access</code>')</li>
  74.  
  75.       <li><code>modification</code></li>
  76.     </ul>
  77.  
  78.     <p>The <code>plus</code> keyword is optional. <num>
  79.     should be an integer value [acceptable to <code>atoi()</code>],
  80.     and <type> is one of:</p>
  81.  
  82.     <ul>
  83.       <li><code>years</code></li>
  84.       <li><code>months</code></li>
  85.       <li><code>weeks</code></li>
  86.       <li><code>days</code></li>
  87.       <li><code>hours</code></li>
  88.       <li><code>minutes</code></li>
  89.       <li><code>seconds</code></li>
  90.     </ul>
  91.  
  92.     <p>For example, any of the following directives can be used to
  93.     make documents expire 1 month after being accessed, by
  94.     default:</p>
  95.  
  96.     <example>
  97.       ExpiresDefault "access plus 1 month"<br />
  98.       ExpiresDefault "access plus 4 weeks"<br />
  99.       ExpiresDefault "access plus 30 days"
  100.     </example>
  101.  
  102.     <p>The expiry time can be fine-tuned by adding several
  103.     '<num> <type>' clauses:</p>
  104.  
  105.     <example>
  106.       ExpiresByType text/html "access plus 1 month 15
  107.       days 2 hours"<br />
  108.       ExpiresByType image/gif "modification plus 5 hours 3
  109.       minutes"
  110.     </example>
  111.  
  112.     <p>Note that if you use a modification date based setting, the
  113.     Expires header will <strong>not</strong> be added to content
  114.     that does not come from a file on disk. This is due to the fact
  115.     that there is no modification time for such content.</p>
  116. </section>
  117.  
  118. <directivesynopsis>
  119. <name>ExpiresActive</name>
  120. <description>Enables generation of <code>Expires</code>
  121. headers</description>
  122. <syntax>ExpiresActive On|Off</syntax>
  123. <contextlist><context>server config</context>
  124. <context>virtual host</context><context>directory</context>
  125. <context>.htaccess</context></contextlist>
  126. <override>Indexes</override>
  127.  
  128. <usage>
  129.     <p>This directive enables or disables the generation of the
  130.     <code>Expires</code> and <code>Cache-Control</code> headers for
  131.     the document realm in question.  (That is, if found in an
  132.     <code>.htaccess</code> file, for instance, it applies only to
  133.     documents generated from that directory.) If set to
  134.     <code>Off</code>, the headers will not be generated for any
  135.     document in the realm (unless overridden at a lower level, such as
  136.     an <code>.htaccess</code> file overriding a server config
  137.     file). If set to <code>On</code>, the headers will be added to
  138.     served documents according to the criteria defined by the
  139.     <directive module="mod_expires">ExpiresByType</directive> and
  140.     <directive module="mod_expires">ExpiresDefault</directive>
  141.     directives (<em>q.v.</em>).</p>
  142.  
  143.     <p>Note that this directive does not guarantee that an
  144.     <code>Expires</code> or <code>Cache-Control</code> header will be
  145.     generated. If the criteria aren't met, no header will be sent, and
  146.     the effect will be as though this directive wasn't even
  147.     specified.</p>
  148.  </usage> 
  149. </directivesynopsis>
  150.  
  151. <directivesynopsis>
  152. <name>ExpiresByType</name>
  153. <description>Value of the <code>Expires</code> header configured
  154. by MIME type</description>
  155. <syntax>ExpiresByType <var>MIME-type</var>
  156. <var><code>seconds</var></syntax>
  157. <contextlist><context>server config</context><context>virtual host</context>
  158. <context>directory</context><context>.htaccess</context></contextlist>
  159. <override>Indexes</override>
  160.  
  161. <usage>
  162.     <p>This directive defines the value of the <code>Expires</code>
  163.     header and the <code>max-age</code> directive of the
  164.     <code>Cache-Control</code> header generated for documents of the
  165.     specified type (<em>e.g.</em>, <code>text/html</code>). The second
  166.     argument sets the number of seconds that will be added to a base
  167.     time to construct the expiration date.  The <code>Cache-Control:
  168.     max-age</code> is calculated by subtracting the request time from
  169.     the expiration date and expressing the result in seconds.</p>
  170.  
  171.     <p>The base time is either the last modification time of the
  172.     file, or the time of the client's access to the document. Which
  173.     should be used is specified by the
  174.     <code><var><code></var></code> field; <code>M</code>
  175.     means that the file's last modification time should be used as
  176.     the base time, and <code>A</code> means the client's access
  177.     time should be used.</p>
  178.  
  179.     <p>The difference in effect is subtle. If <code>M</code> is used,
  180.     all current copies of the document in all caches will expire at
  181.     the same time, which can be good for something like a weekly
  182.     notice that's always found at the same URL. If <code>A</code> is
  183.     used, the date of expiration is different for each client; this
  184.     can be good for image files that don't change very often,
  185.     particularly for a set of related documents that all refer to
  186.     the same images (<em>i.e.</em>, the images will be accessed
  187.     repeatedly within a relatively short timespan).</p>
  188.  
  189.     <example><title>Example:</title>
  190.       # enable expirations<br />
  191.       ExpiresActive On<br />
  192.       # expire GIF images after a month in the client's cache<br />
  193.       ExpiresByType image/gif A2592000<br />
  194.       # HTML documents are good for a week from the<br />
  195.       # time they were changed<br />
  196.       ExpiresByType text/html M604800
  197.     </example>
  198.  
  199.     <p>Note that this directive only has effect if
  200.     <code>ExpiresActive On</code> has been specified. It overrides,
  201.     for the specified MIME type <em>only</em>, any expiration date
  202.     set by the <directive module="mod_expires">ExpiresDefault</directive>
  203.     directive.</p>
  204.  
  205.     <p>You can also specify the expiration time calculation using
  206.     an <a href="#AltSyn">alternate syntax</a>, described earlier in
  207.     this document.</p>
  208. </usage>
  209. </directivesynopsis>
  210.  
  211. <directivesynopsis>
  212. <name>ExpiresDefault</name>
  213. <description>Default algorithm for calculating expiration time</description>
  214. <syntax>ExpiresDefault <var><code>seconds</var></syntax>
  215. <contextlist><context>server config</context><context>virtual host</context>
  216. <context>directory</context><context>.htaccess</context></contextlist>
  217. <override>Indexes</override>
  218.  
  219. <usage>
  220.     <p>This directive sets the default algorithm for calculating the
  221.     expiration time for all documents in the affected realm. It can be
  222.     overridden on a type-by-type basis by the <directive
  223.     module="mod_expires">ExpiresByType</directive> directive. See the
  224.     description of that directive for details about the syntax of the
  225.     argument, and the <a href="#AltSyn">alternate syntax</a>
  226.     description as well.</p>
  227. </usage>
  228. </directivesynopsis>
  229. </modulesynopsis>
  230.  
  231.