View Javadoc

1   /*
2   * Copyright 2004 The Apache Software Foundation
3   *
4   * Licensed under the Apache License, Version 2.0 (the "License");
5   * you may not use this file except in compliance with the License.
6   * You may obtain a copy of the License at
7   *
8   *     http://www.apache.org/licenses/LICENSE-2.0
9   *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16  
17  
18  package filters;
19  
20  
21  import java.io.IOException;
22  import javax.servlet.Filter;
23  import javax.servlet.FilterChain;
24  import javax.servlet.FilterConfig;
25  import javax.servlet.ServletException;
26  import javax.servlet.ServletRequest;
27  import javax.servlet.ServletResponse;
28  import javax.servlet.UnavailableException;
29  
30  
31  /**
32   * <p>Example filter that sets the character encoding to be used in parsing the
33   * incoming request, either unconditionally or only if the client did not
34   * specify a character encoding.  Configuration of this filter is based on
35   * the following initialization parameters:</p>
36   * <ul>
37   * <li><strong>encoding</strong> - The character encoding to be configured
38   *     for this request, either conditionally or unconditionally based on
39   *     the <code>ignore</code> initialization parameter.  This parameter
40   *     is required, so there is no default.</li>
41   * <li><strong>ignore</strong> - If set to "true", any character encoding
42   *     specified by the client is ignored, and the value returned by the
43   *     <code>selectEncoding()</code> method is set.  If set to "false,
44   *     <code>selectEncoding()</code> is called <strong>only</strong> if the
45   *     client has not already specified an encoding.  By default, this
46   *     parameter is set to "true".</li>
47   * </ul>
48   *
49   * <p>Although this filter can be used unchanged, it is also easy to
50   * subclass it and make the <code>selectEncoding()</code> method more
51   * intelligent about what encoding to choose, based on characteristics of
52   * the incoming request (such as the values of the <code>Accept-Language</code>
53   * and <code>User-Agent</code> headers, or a value stashed in the current
54   * user's session.</p>
55   *
56   * @author Craig McClanahan
57   * @version $Revision: 267129 $ $Date: 2004-03-18 08:40:35 -0800 (Thu, 18 Mar 2004) $
58   */
59  
60  public class SetCharacterEncodingFilter implements Filter {
61  
62  
63      // ----------------------------------------------------- Instance Variables
64  
65  
66      /**
67       * The default character encoding to set for requests that pass through
68       * this filter.
69       */
70      protected String encoding = null;
71  
72  
73      /**
74       * The filter configuration object we are associated with.  If this value
75       * is null, this filter instance is not currently configured.
76       */
77      protected FilterConfig filterConfig = null;
78  
79  
80      /**
81       * Should a character encoding specified by the client be ignored?
82       */
83      protected boolean ignore = true;
84  
85  
86      // --------------------------------------------------------- Public Methods
87  
88  
89      /**
90       * Take this filter out of service.
91       */
92      public void destroy() {
93  
94          this.encoding = null;
95          this.filterConfig = null;
96  
97      }
98  
99  
100     /**
101      * Select and set (if specified) the character encoding to be used to
102      * interpret request parameters for this request.
103      *
104      * @param request The servlet request we are processing
105      * @param result The servlet response we are creating
106      * @param chain The filter chain we are processing
107      *
108      * @exception IOException if an input/output error occurs
109      * @exception ServletException if a servlet error occurs
110      */
111     public void doFilter(ServletRequest request, ServletResponse response,
112                          FilterChain chain)
113 	throws IOException, ServletException {
114 
115         // Conditionally select and set the character encoding to be used
116         if (ignore || (request.getCharacterEncoding() == null)) {
117             String encoding = selectEncoding(request);
118             if (encoding != null)
119                 request.setCharacterEncoding(encoding);
120         }
121 
122 	// Pass control on to the next filter
123         chain.doFilter(request, response);
124 
125     }
126 
127 
128     /**
129      * Place this filter into service.
130      *
131      * @param filterConfig The filter configuration object
132      */
133     public void init(FilterConfig filterConfig) throws ServletException {
134 
135 	this.filterConfig = filterConfig;
136         this.encoding = filterConfig.getInitParameter("encoding");
137         String value = filterConfig.getInitParameter("ignore");
138         if (value == null)
139             this.ignore = true;
140         else if (value.equalsIgnoreCase("true"))
141             this.ignore = true;
142         else if (value.equalsIgnoreCase("yes"))
143             this.ignore = true;
144         else
145             this.ignore = false;
146 
147     }
148 
149 
150     // ------------------------------------------------------ Protected Methods
151 
152 
153     /**
154      * Select an appropriate character encoding to be used, based on the
155      * characteristics of the current request and/or filter initialization
156      * parameters.  If no character encoding should be set, return
157      * <code>null</code>.
158      * <p>
159      * The default implementation unconditionally returns the value configured
160      * by the <strong>encoding</strong> initialization parameter for this
161      * filter.
162      *
163      * @param request The servlet request we are processing
164      */
165     protected String selectEncoding(ServletRequest request) {
166 
167         return (this.encoding);
168 
169     }
170 
171 
172 }