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