| <?xml version="1.0"?> |
| <!-- |
| 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. |
| --> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="filter.html"> |
| |
| &project; |
| |
| <properties> |
| <title>Container Provided Filters</title> |
| </properties> |
| |
| <body> |
| |
| <section name="Table of Contents"> |
| <toc/> |
| </section> |
| |
| <section name="Introduction"> |
| |
| <p>Tomcat provides a number of <strong>Filters</strong> which may be |
| configured for use with all web applications using |
| <code>$CATALINA_BASE/conf/web.xml</code> or may be configured for individual |
| web applications by configuring them in the application's |
| <code>WEB-INF/web.xml</code>. Each filter is described below.</p> |
| |
| <blockquote><em> |
| <p>This description uses the variable name $CATALINA_BASE to refer the |
| base directory against which most relative paths are resolved. If you have |
| not configured Tomcat for multiple instances by setting a CATALINA_BASE |
| directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, |
| the directory into which you have installed Tomcat.</p> |
| </em></blockquote> |
| |
| </section> |
| |
| |
| <section name="Set Character Encoding Filter"> |
| |
| <subsection name="Introduction"> |
| |
| <p>User agents don't always include character encoding information in |
| requests. Depending on the how the request is processed, usually the |
| default encoding of ISO-8859-1 is used. This is not always |
| desirable. This filter provides options for setting that encoding or |
| forcing it to a particular value. Essentially this filter calls |
| <code>ServletRequest.setCharacterEncoding()</code> method.</p> |
| |
| <p>Effectively the value set by this filter is used when parsing parameters |
| in a POST request, if parameter parsing occurs later than this filter. Thus |
| the order of filter mappings is important. Note that the encoding for GET |
| requests is not set here, but on a <strong>Connector</strong>. See |
| CharacterEncoding page in the FAQ for details.</p> |
| |
| </subsection> |
| |
| <subsection name="Filter Class Name"> |
| |
| <p>The filter class name for the Set Character Encoding Filter is |
| <strong><code>org.apache.catalina.filters.SetCharacterEncodingFilter</code></strong>.</p> |
| |
| </subsection> |
| |
| <subsection name="Initialisation parameters"> |
| |
| <p>The Set Character Encoding Filter supports the following initialization |
| parameters:</p> |
| |
| <attributes> |
| |
| <attribute name="encoding" required="true"> |
| <p>Name of the character encoding which should be set.</p> |
| </attribute> |
| |
| <attribute name="ignore" required="false"> |
| <p>Determines if any character encoding specified by the user agent is |
| ignored. If this attribute is <code>true</code>, any value provided by |
| the user agent is ignored. If <code>false</code>, the encoding is only |
| set if the user agent did not specify an encoding. The default value |
| is <code>false</code>.</p> |
| </attribute> |
| |
| </attributes> |
| |
| </subsection> |
| |
| </section> |
| |
| |
| <section name="Failed Request Filter"> |
| |
| <subsection name="Introduction"> |
| |
| <p>This filter triggers parameters parsing in a request and rejects the |
| request if some parameters were skipped during parameter parsing because |
| of parsing errors or request size limitations (such as |
| <code>maxParameterCount</code> attribute in a |
| <a href="http.html">Connector</a>). |
| This filter can be used to ensure that none parameter values submitted by |
| client are lost.</p> |
| |
| <p>Note that parameter parsing may consume the body of an HTTP request, so |
| caution is needed if the servlet protected by this filter uses |
| <code>request.getInputStream()</code> or <code>request.getReader()</code> |
| calls. In general the risk of breaking a web application by adding this |
| filter is not so high, because parameter parsing does check content type |
| of the request before consuming the request body.</p> |
| |
| <p>Note, that for the POST requests to be parsed correctly, a |
| <code>SetCharacterEncodingFilter</code> filter must be configured above |
| this one. See CharacterEncoding page in the FAQ for details.</p> |
| |
| <p>The request is rejected with HTTP status code 400 (Bad Request).</p> |
| |
| </subsection> |
| |
| <subsection name="Filter Class Name"> |
| |
| <p>The filter class name for the Failed Request Filter is |
| <strong><code>org.apache.catalina.filters.FailedRequestFilter</code></strong>.</p> |
| |
| </subsection> |
| |
| <subsection name="Initialisation parameters"> |
| |
| <p>The Failed Request Filter does not support any initialization parameters.</p> |
| |
| </subsection> |
| |
| </section> |
| |
| |
| </body> |
| |
| |
| </document> |
