You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2010/07/15 00:11:31 UTC
svn commit: r964219 [2/2] - in /tomcat/trunk:
java/org/apache/catalina/filters/ test/org/apache/catalina/filters/
webapps/docs/ webapps/docs/config/
Modified: tomcat/trunk/webapps/docs/config/filter.xml
URL: http://svn.apache.org/viewvc/tomcat/trunk/webapps/docs/config/filter.xml?rev=964219&r1=964218&r2=964219&view=diff
==============================================================================
--- tomcat/trunk/webapps/docs/config/filter.xml (original)
+++ tomcat/trunk/webapps/docs/config/filter.xml Wed Jul 14 22:11:30 2010
@@ -159,6 +159,406 @@
</section>
+<section name="Expires Filter">
+
+ <subsection name="Introduction">
+
+ <p>
+ ExpiresFilter is a Java Servlet API port of <a
+ href="http://httpd.apache.org/docs/2.2/mod/mod_expires.html">Apache
+ mod_expires</a>.
+ This filter controls the setting of the <tt>Expires</tt> HTTP header and the
+ <tt>max-age</tt> directive of the <tt>Cache-Control</tt> HTTP header in
+ server responses. The expiration date can set to be relative to either the
+ time the source file was last modified, or to the time of the client access.
+ </p>
+
+ <p>
+ These HTTP headers are an instruction to the client about the document's
+ validity and persistence. If cached, the document may be fetched from the
+ cache rather than from the source until this time has passed. After that, the
+ cache copy is considered "expired" and invalid, and a new copy must
+ be obtained from the source.
+ </p>
+ <p>
+ To modify <tt>Cache-Control</tt> directives other than <tt>max-age</tt> (see
+ <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9" >RFC
+ 2616 section 14.9</a>), you can use other servlet filters or <a
+ href="http://httpd.apache.org/docs/2.2/mod/mod_headers.html" >Apache Httpd
+ mod_headers</a> module.
+ </p>
+
+ </subsection>
+
+ <subsection name="Basic configuration sample">
+ <p>
+ Basic configuration to add '<tt>Expires</tt>' and '<tt>Cache-Control: max-age=</tt>'
+ headers to images, css and javascript.
+ </p>
+
+ <source>
+<filter>
+ <filter-name>ExpiresFilter</filter-name>
+ <filter-class>org.apache.catalina.filters.ExpiresFilter</filter-class>
+ <init-param>
+ <param-name>ExpiresByType image</param-name>
+ <param-value>access plus 10 minutes</param-value>
+ </init-param>
+ <init-param>
+ <param-name>ExpiresByType text/css</param-name>
+ <param-value>access plus 10 minutes</param-value>
+ </init-param>
+ <init-param>
+ <param-name>ExpiresByType text/javascript</param-name>
+ <param-value>access plus 10 minutes</param-value>
+ </init-param>
+</filter>
+...
+<filter-mapping>
+ <filter-name>ExpiresFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ <dispatcher>REQUEST</dispatcher>
+</filter-mapping>
+
+ </source>
+
+ </subsection>
+
+ <subsection name="Alternate Syntax">
+ <p>
+ The <tt>ExpiresDefault</tt> and <tt>ExpiresByType</tt> directives can also be
+ defined in a more readable syntax of the form:
+ </p>
+
+ <source>
+<init-param>
+ <param-name>ExpiresDefault</param-name>
+ <param-value><base> [plus] {<num> <type>}*</param-value>
+</init-param>
+
+<init-param>
+ <param-name>ExpiresByType type</param-name>
+ <param-value><base> [plus] {<num> <type>}*</param-value>
+</init-param>
+
+<init-param>
+ <param-name>ExpiresByType type;encoding</param-name>
+ <param-value><base> [plus] {<num> <type>}*</param-value>
+</init-param>
+ </source>
+ <p>
+ where <tt><base></tt> is one of:
+ <ul>
+ <li><tt>access</tt></li>
+ <li><tt>now</tt> (equivalent to '<tt>access</tt>')</li>
+ <li><tt>modification</tt></li>
+ </ul>
+ </p>
+ <p>
+ The <tt>plus</tt> keyword is optional. <tt><num></tt> should be an
+ integer value (acceptable to <tt>Integer.parseInt()</tt>), and
+ <tt><type></tt> is one of:
+ <ul>
+ <li><tt>years</tt></li>
+ <li><tt>months</tt></li>
+ <li><tt>weeks</tt></li>
+ <li><tt>days</tt></li>
+ <li><tt>hours</tt></li>
+ <li><tt>minutes</tt></li>
+ <li><tt>seconds</tt></li>
+ </ul>
+ For example, any of the following directives can be used to make documents
+ expire 1 month after being accessed, by default:
+ </p>
+
+ <source>
+<init-param>
+ <param-name>ExpiresDefault</param-name>
+ <param-value>access plus 1 month</param-value>
+</init-param>
+
+<init-param>
+ <param-name>ExpiresDefault</param-name>
+ <param-value>access plus 4 weeks</param-value>
+</init-param>
+
+<init-param>
+ <param-name>ExpiresDefault</param-name>
+ <param-value>access plus 30 days</param-value>
+</init-param>
+</source>
+<p>
+The expiry time can be fine-tuned by adding several '
+<tt><num> <type></tt>' clauses:
+</p>
+
+<source>
+<init-param>
+ <param-name>ExpiresByType text/html</param-name>
+ <param-value>access plus 1 month 15 days 2 hours</param-value>
+</init-param>
+
+<init-param>
+ <param-name>ExpiresByType image/gif</param-name>
+ <param-value>modification plus 5 hours 3 minutes</param-value>
+</init-param>
+ </source>
+ <p>
+ Note that if you use a modification date based setting, the <tt>Expires</tt>
+ header will <strong>not</strong> be added to content that does not come from
+ a file on disk. This is due to the fact that there is no modification time
+ for such content.
+ </p>
+ </subsection>
+
+ <subsection name="Expiration headers generation eligibility">
+ <p>
+ A response is eligible to be enriched by <tt>ExpiresFilter</tt> if :
+ <ol>
+ <li>no expiration header is defined (<tt>Expires</tt> header or the
+ <tt>max-age</tt> directive of the <tt>Cache-Control</tt> header),</li>
+ <li>the response status code is not excluded by the directive
+ <tt>ExpiresExcludedResponseStatusCodes</tt>,</li>
+ <li>The <tt>Content-Type</tt> of the response matches one of the types
+ defined the in <tt>ExpiresByType</tt> directives or the
+ <tt>ExpiresDefault</tt> directive is defined.</li>
+ </ol>
+ </p>
+ <p>
+ Note : If <tt>Cache-Control</tt> header contains other directives than
+ <tt>max-age</tt>, they are concatenated with the <tt>max-age</tt> directive
+ that is added by the <tt>ExpiresFilter</tt>.
+ </p>
+
+ </subsection>
+
+ <subsection name="Expiration configuration selection">
+ <p>
+ The expiration configuration if elected according to the following algorithm:
+ <ol>
+ <li><tt>ExpiresByType</tt> matching the exact content-type returned by
+ <tt>HttpServletResponse.getContentType()</tt> possibly including the charset
+ (e.g. '<tt>text/xml;charset=UTF-8</tt>'),</li>
+ <li><tt>ExpiresByType</tt> matching the content-type without the charset if
+ <tt>HttpServletResponse.getContentType()</tt> contains a charset (e.g. '
+ <tt>text/xml;charset=UTF-8</tt>' -> '<tt>text/xml</tt>'),</li>
+ <li><tt>ExpiresByType</tt> matching the major type (e.g. substring before
+ '<tt>/</tt>') of <tt>HttpServletResponse.getContentType()</tt>
+ (e.g. '<tt>text/xml;charset=UTF-8</tt>' -> '<tt>text</tt>
+ '),</li>
+ <li><tt>ExpiresDefault</tt></li>
+ </ol>
+ </p>
+ </subsection>
+
+ <subsection name="Filter Class Name">
+
+ <p>The filter class name for the Expires Filter is
+ <strong><code>org.apache.catalina.filters.ExpiresFilter</code>
+ </strong>.</p>
+
+ </subsection>
+
+ <subsection name="Initialisation parameters">
+
+ <p>The <strong>Expires Filter</strong> supports the following
+ initialisation parameters:</p>
+
+ <attributes>
+
+ <attribute name="ExpiresActive" required="false">
+ <p>
+ This directive enables or disables the generation of the <tt>Expires</tt> and
+ <tt>Cache-Control</tt> headers by this <tt>ExpiresFilter</tt>. If set to
+ <tt>Off</tt>, the headers will not be generated for any HTTP response. If set
+ to <tt>On</tt> or <tt>true</tt>, the headers will be added to served HTTP
+ responses according to the criteria defined by the
+ <tt>ExpiresByType <content-type></tt> and <tt>ExpiresDefault</tt>
+ directives. Note that this directive does not guarantee that an
+ <tt>Expires</tt> or <tt>Cache-Control</tt> header will be generated. If the
+ criteria aren't met, no header will be sent, and the effect will be as
+ though this directive wasn't even specified.
+ </p>
+ <p>
+ Default value is <tt>true</tt>.
+ </p>
+
+ <p>
+ <i>Sample: enable filter</i>
+ </p>
+
+ <source>
+<init-param>
+ <!-- supports case insensitive 'On' or 'true' -->
+ <param-name>ExpiresActive</param-name>
+ <param-value>On</param-value>
+</init-param>
+ </source>
+ <p>
+ <i>Sample: disable filter</i>
+ </p>
+
+ <source>
+<init-param>
+ <!-- supports anything different from case insensitive 'On' and 'true' -->
+ <param-name>ExpiresActive</param-name>
+ <param-value>Off</param-value>
+</init-param>
+ </source>
+ </attribute>
+
+ <attribute name="ExpiresExcludedResponseStatusCodes" required="false">
+ <p>
+ This directive defines the http response status codes for which the
+ <tt>ExpiresFilter</tt> will not generate expiration headers. By default, the
+ <tt>304</tt> status code ("<tt>Not modified</tt>") is skipped. The
+ value is a comma separated list of http status codes.
+ </p>
+ <p>
+ This directive is useful to ease usage of <tt>ExpiresDefault</tt> directive.
+ Indeed, the behavior of <tt>304 Not modified</tt> (which does specify a
+ <tt>Content-Type</tt> header) combined with <tt>Expires</tt> and
+ <tt>Cache-Control:max-age=</tt> headers can be unnecessarily tricky to
+ understand.
+ </p>
+ <p>
+ <i>Sample : exclude response status codes 302, 500 and 503</i>
+ </p>
+
+ <source>
+<init-param>
+ <param-name>ExpiresExcludedResponseStatusCodes</param-name>
+ <param-value>302, 500, 503</param-value>
+</init-param>
+ </source>
+ </attribute>
+
+ <attribute name="ExpiresByType <content-type>" required="false">
+ <p>
+ This directive defines the value of the <tt>Expires</tt> header and the
+ <tt>max-age</tt> directive of the <tt>Cache-Control</tt> header generated for
+ documents of the specified type (<i>e.g.</i>, <tt>text/html</tt>). The second
+ argument sets the number of seconds that will be added to a base time to
+ construct the expiration date. The <tt>Cache-Control: max-age</tt> is
+ calculated by subtracting the request time from the expiration date and
+ expressing the result in seconds.
+ </p>
+ <p>
+ The base time is either the last modification time of the file, or the time
+ of the client's access to the document. Which should be used is
+ specified by the <tt><code></tt> field; <tt>M</tt> means that the
+ file's last modification time should be used as the base time, and
+ <tt>A</tt> means the client's access time should be used. The duration
+ is expressed in seconds. <tt>A2592000</tt> stands for
+ <tt>access plus 30 days</tt> in alternate syntax.
+ </p>
+ <p>
+ The difference in effect is subtle. If <tt>M</tt> (<tt>modification</tt> in
+ alternate syntax) is used, all current copies of the document in all caches
+ will expire at the same time, which can be good for something like a weekly
+ notice that's always found at the same URL. If <tt>A</tt> (
+ <tt>access</tt> or <tt>now</tt> in alternate syntax) is used, the date of
+ expiration is different for each client; this can be good for image files
+ that don't change very often, particularly for a set of related
+ documents that all refer to the same images (<i>i.e.</i>, the images will be
+ accessed repeatedly within a relatively short timespan).
+ </p>
+ <p>
+ <strong>Note:</strong> When the content type includes a charset (e.g.
+ <tt>'ExpiresByType text/xml;charset=utf-8'</tt>), Tomcat removes blank chars
+ between the '<tt>;</tt>' and the '<tt>charset</tt>' keyword. Due to this,
+ configuration of an expiration with a charset must <strong>not</strong> include
+ such a space character.
+ </p>
+ <p>
+ <i>Sample:</i>
+ </p>
+
+ <source>
+<init-param>
+ <param-name>ExpiresByType text/html</param-name>
+ <param-value>access plus 1 month 15 days 2 hours</param-value>
+</init-param>
+
+<init-param>
+ <!-- 2592000 seconds = 30 days -->
+ <param-name>ExpiresByType image/gif</param-name>
+ <param-value>A2592000</param-value>
+</init-param>
+ </source>
+ <p>
+ Note that this directive only has effect if <tt>ExpiresActive On</tt> has
+ been specified. It overrides, for the specified MIME type <i>only</i>, any
+ expiration date set by the <tt>ExpiresDefault</tt> directive.
+ </p>
+ <p>
+ You can also specify the expiration time calculation using an alternate
+ syntax, described earlier in this document.
+ </p>
+ </attribute>
+
+ <attribute name="ExpiresDefault" required="false">
+ <p>
+ This directive sets the default algorithm for calculating the
+ expiration time for all documents in the affected realm. It can be
+ overridden on a type-by-type basis by the <tt>ExpiresByType</tt> directive. See the
+ description of that directive for details about the syntax of the
+ argument, and the "alternate syntax"
+ description as well.
+ </p>
+ </attribute>
+ </attributes>
+
+ </subsection>
+
+ <subsection name="Troubleshooting">
+ <p>
+ To troubleshoot, enable logging on the
+ <tt>org.apache.catalina.filters.ExpiresFilter</tt>.
+ </p>
+ <p>
+ Extract of logging.properties
+ </p>
+
+ <source>
+org.apache.catalina.filters.ExpiresFilter.level = FINE
+ </source>
+ <p>
+ Sample of initialization log message :
+ </p>
+
+ <source>
+Mar 26, 2010 2:01:41 PM org.apache.catalina.filters.ExpiresFilter init
+FINE: Filter initialized with configuration ExpiresFilter[
+ active=true,
+ excludedResponseStatusCode=[304],
+ default=null,
+ byType={
+ image=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]],
+ text/css=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]],
+ text/javascript=ExpiresConfiguration[startingPoint=ACCESS_TIME, duration=[10 MINUTE]]}]
+ </source>
+ <p>
+ Sample of per-request log message where <tt>ExpiresFilter</tt> adds an
+ expiration date
+ </p>
+
+ <source>
+Mar 26, 2010 2:09:47 PM org.apache.catalina.filters.ExpiresFilter onBeforeWriteResponseBody
+FINE: Request "/tomcat.gif" with response status "200" content-type "image/gif", set expiration date 3/26/10 2:19 PM
+ </source>
+ <p>
+ Sample of per-request log message where <tt>ExpiresFilter</tt> does not add
+ an expiration date
+ </p>
+
+ <source>
+Mar 26, 2010 2:10:27 PM org.apache.catalina.filters.ExpiresFilter onBeforeWriteResponseBody
+FINE: Request "/docs/config/manager.html" with response status "200" content-type "text/html", no expiration configured
+ </source>
+ </subsection>
+
+</section>
<section name="Remote Address Filter">
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org